Merge branch 'master' of http://82.157.175.59:3000/GenarrativeAI/Genarrative

docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md

@@ -0,0 +1,94 @@
+# Jenkins SpacetimeDB 数据库导入导出流水线方案
+
+日期：`2026-04-29`
+
+## 1. 目标
+
+为 Jenkins 增加两条人工触发的数据库迁移流水线：
+
+1. `Genarrative-Database-Export`：调用仓库内 `scripts/spacetime-export-migration-json.mjs`，通过 SpacetimeDB 迁移导出 procedure 生成迁移 JSON，并归档为 Jenkins 产物。
+2. `Genarrative-Database-Import`：调用仓库内 `scripts/spacetime-import-migration-json.mjs`，通过 SpacetimeDB 迁移导入 procedure 导入迁移 JSON，默认只执行 `dry-run`。
+
+本方案只编排已有迁移脚本，不在 Jenkinsfile 中重新实现表结构枚举、JSON 解析或 SQL 拼接逻辑。
+
+## 2. 执行依据
+
+1. SpacetimeDB CLI 调用按仓库技能 `spacetimedb-cli` 执行，数据库调用通过 `spacetime call` 或 HTTP procedure API 完成。
+2. SpacetimeDB 读写语义按 `spacetimedb-concepts` 执行：导入导出能力由模块内 procedure/reducer 负责校验和事务处理，Jenkins 不直接改表。
+3. 迁移脚本复用当前仓库的参数解析与错误处理：
+   - `scripts/spacetime-export-migration-json.mjs`
+   - `scripts/spacetime-import-migration-json.mjs`
+   - `scripts/spacetime-migration-common.mjs`
+
+## 3. Jenkins 作业
+
+### 3.1 数据库导出
+
+脚本路径：
+
+```text
+jenkins/Jenkinsfile.database-export
+```
+
+推荐作业名：
+
+```text
+Genarrative-Database-Export
+```
+
+关键参数：
+
+1. `DATABASE`：目标 SpacetimeDB 数据库名；留空时读取仓库环境变量。
+2. `SERVER`：SpacetimeDB server 别名，默认 `maincloud`。
+3. `SERVER_URL`：显式服务地址；填写后优先于 `SERVER`。
+4. `ROOT_DIR`：可选，透传给 `spacetime --root-dir`。
+5. `INCLUDE_TABLES`：可选，逗号分隔的表名白名单。
+6. `OUTPUT_DIRECTORY`：导出文件目录，默认 `database-exports`。
+7. `EXPORT_NAME`：导出文件名；留空时使用 `spacetime-migration-<BUILD_NUMBER>.json`。
+
+导出成功后，Jenkins 归档：
+
+```text
+<OUTPUT_DIRECTORY>/<EXPORT_NAME>
+```
+
+### 3.2 数据库导入
+
+脚本路径：
+
+```text
+jenkins/Jenkinsfile.database-import
+```
+
+推荐作业名：
+
+```text
+Genarrative-Database-Import
+```
+
+关键参数：
+
+1. `INPUT_FILE`：必填，迁移 JSON 文件路径。
+2. `DATABASE`、`SERVER`、`SERVER_URL`、`ROOT_DIR`：与导出流水线一致。
+3. `INCLUDE_TABLES`：可选，只导入指定表。
+4. `DRY_RUN`：默认 `true`，只校验不写入。
+5. `INCREMENTAL`：默认 `true`，跳过已存在或冲突的行。
+6. `REPLACE_EXISTING`：默认 `false`，只覆盖本次迁移文件中涉及的表；不可与 `INCREMENTAL` 同时启用。
+7. `BOOTSTRAP_SECRET`：可选，用于授权临时 Web API identity。
+8. `TOKEN`：可选，SpacetimeDB 客户端连接 token；留空时脚本会自动创建临时 identity 并在结束后撤销。
+9. `NOTE`：迁移授权备注。
+
+## 4. 安全边界
+
+1. 导入流水线默认 `DRY_RUN=true`，需要人工明确关闭才会写入数据。
+2. `INCREMENTAL` 与 `REPLACE_EXISTING` 互斥，Jenkinsfile 会在执行前阻止同时启用。
+3. Jenkinsfile 不打印 token；生产环境应通过 Jenkins 凭据或目标机器环境变量传入敏感值。
+4. 如果不传 `TOKEN`，导入脚本会创建临时 Web API identity，并调用迁移授权/撤销 procedure 收敛权限窗口。
+
+## 5. 文件清单
+
+```text
+jenkins/Jenkinsfile.database-export
+jenkins/Jenkinsfile.database-import
+docs/technical/JENKINS_SPACETIMEDB_DATABASE_MIGRATION_PIPELINES_2026-04-29.md
+```

docs/technical/SPACETIMEDB_JSON_STRING_MIGRATION_PROCEDURE_2026-04-27.md

@@ -122,6 +122,38 @@ node scripts/spacetime-revoke-migration-operator.mjs \
 
 ## Node 脚本
 
+### 发布冲突自动迁移
+
+`npm run spacetime:publish:maincloud` 默认采用冲突感知发布：
+
+1. 先不清库发布新 wasm。
+2. 如果发布成功，流程结束。
+3. 如果发布失败且输出可判定为 schema 冲突，脚本自动导出旧库迁移 JSON 到 `tmp/spacetime-migrations/maincloud/<database>/<timestamp>.json`。
+4. 导出成功后执行清库发布新 wasm。
+5. 新 wasm 发布成功后，把第 3 步导出的 JSON 自动导入回灌。
+
+任一阶段失败都会中止流程，并保留已经导出的迁移 JSON。非 schema 冲突的发布失败不会进入迁移流程。
+
+```bash
+npm run spacetime:publish:maincloud -- --database xushi-p4wfr
+```
+
+可选参数：
+
+- `--no-migrate-on-conflict`：禁用冲突自动迁移，只保留原始发布失败。
+- `--migration-dir <dir>`：指定迁移 JSON 输出目录。
+- `--clear-database`：显式清库发布；该模式代表人工确认清库，不触发自动迁移。
+
+冲突自动迁移需要发布脚本本次生成的 `GENARRATIVE_SPACETIME_MIGRATION_BOOTSTRAP_SECRET`。因此不要和 `--no-migration-bootstrap-secret` 同时使用。
+
+### 删除表和删除字段
+
+迁移文件来自旧模块时，可能包含新模块已经删除的表或字段。导入阶段按以下规则处理：
+
+- 迁移文件包含新模块已删除或不在白名单内的表时，不中断迁移；该表全部行计入 `skipped_row_count`，并在导入结束后统一展示 `dropped_table` 告警。
+- 迁移行包含新模块已删除的旧字段时，导入 procedure 会尝试丢弃旧字段后继续反序列化；恢复成功则导入该行，并在导入结束后统一展示 `dropped_field` 告警。
+- 新模块新增必填字段、字段类型变化、枚举不兼容等无法通过“丢弃旧字段”恢复的情况仍会失败并回滚，避免写入不完整数据。
+
 本机导出时，先确保本机 SpacetimeDB 服务和源数据库可访问，然后授权本机调用身份：
 
 ```bash