推进本地优先迁移与资源闭环

- 补齐共享只读页面 AI 浏览器 smoke，并回填当前优先级 checklist 的 P4/P5/P6 证据。 - 为 OnlyOffice 资源增加 /office/{documentId}/{assetId} 对象壳，固定 resource identity 与侧边栏打开路径。 - 扩展 Convex 导出脚本，支持 dry-run、manifest、冲突报告、索引刷新与 rollback，并补充 smoke。 - 补充资源 AI 工具合同与 Convex 导出 Web 入口设计。
2026-05-19 11:39:04 +08:00
parent a1b28a8e38
commit 94be1c927b
11 changed files with 1097 additions and 73 deletions
@@ -0,0 +1,149 @@
+# 3-17 Convex Export Web Entry v1
+
+状态：process
+
+## 目标
+
+旧 Convex workspace 迁移到本地 workspace 时，用户应能在 Web 控制台完成：
+
+1. 选择 Convex workspace。
+2. 选择目标本地 root。
+3. 先 dry run，查看计划、冲突和预计写入。
+4. apply 后得到 manifest、冲突报告、索引重建结果。
+5. 需要时按 manifest rollback。
+
+## 当前基础
+
+CLI 已具备最小迁移闭环：
+
+- `scripts/export-convex-workspace-to-local.js --fixture <fixture.json> --out <dir>`
+- `--dry-run`
+- `--manifest <file>`
+- `--conflict-report <file>`
+- `--rollback <manifest.json>`
+
+验证：
+
+- `node scripts/task444-convex-workspace-export-local-fixture-smoke.js`
+- `node scripts/task455-convex-export-plan-rollback-smoke.js`
+
+## Web 入口设计
+
+入口位置：管理员控制台 `/admin` 新增“Convex 迁移”面板。
+
+字段：
+
+- `workspaceId`
+- `targetRootUri`
+- `mode=dryRun | apply | rollback`
+- `manifestPath`，rollback 时必填
+- `conflictPolicy=stop`，默认只支持 stop，不覆盖目标文件
+
+## API 设计
+
+### `GET /api/admin/convex-export/workspaces`
+
+返回当前可导出的 Convex workspace 列表。
+
+最小返回：
+
+```json
+{
+  "ok": true,
+  "workspaces": [
+    { "workspaceId": "ws_1", "name": "默认空间", "documentCount": 12 }
+  ]
+}
+```
+
+### `POST /api/admin/convex-export/plan`
+
+输入：
+
+```json
+{
+  "workspaceId": "ws_1",
+  "targetRootUri": "file:///mnt/Data1T/Mnote_data/users/user_1/workspaces/imported"
+}
+```
+
+行为：
+
+- 导出 Convex workspace fixture / snapshot 到临时计划。
+- 调用迁移 planner，等价于 CLI `--dry-run`。
+- 写入 `<target>/.mnote/migration-plan.json` 或控制面 job 目录。
+- 不写正文文件。
+
+### `POST /api/admin/convex-export/apply`
+
+输入：
+
+```json
+{
+  "workspaceId": "ws_1",
+  "targetRootUri": "file:///mnt/Data1T/Mnote_data/users/user_1/workspaces/imported",
+  "manifestPath": "/mnt/Data1T/Mnote_data/users/user_1/workspaces/imported/.mnote/migration-manifest.json"
+}
+```
+
+行为：
+
+- 默认 `conflictPolicy=stop`。
+- 目标文件存在时返回 409 和 conflict report。
+- 成功后写 `.mnote/migration-manifest.json`、`.mnote/index/search-index.json`。
+
+### `POST /api/admin/convex-export/rollback`
+
+输入：
+
+```json
+{
+  "manifestPath": "/mnt/Data1T/Mnote_data/users/user_1/workspaces/imported/.mnote/migration-manifest.json"
+}
+```
+
+行为：
+
+- 按 manifest 删除本次新增文件。
+- 如 manifest 存在备份文件，则恢复备份。
+- 不删除 manifest 本身，追加 rollback report。
+
+## 权限
+
+- 只有 admin 可以从任意 Convex workspace 导出。
+- 普通用户只能导出自己拥有的 workspace 到自己有 write grant 的本地 root。
+- 所有 `targetRootUri` 必须通过 local access policy 校验。
+- Web API 不能接受任意 shell 命令；CLI 迁移逻辑应抽成 Rust/Node 可调用模块或由受控 job runner 调用固定脚本和固定参数。
+
+## 状态与报告
+
+任务状态包含：
+
+- `queued`
+- `planning`
+- `blocked_by_conflict`
+- `applying`
+- `indexing`
+- `completed`
+- `failed`
+- `rolled_back`
+
+报告包含：
+
+- `documentCount`
+- `resourceCount`
+- `aiSessionCount`
+- `operationCount`
+- `createdFiles`
+- `conflicts`
+- `indexRefresh`
+- `manifestPath`
+- `conflictReportPath`
+
+## 后续落码顺序
+
+1. 把 CLI planner/apply/rollback 拆成可被 Web route 复用的模块。
+2. 新增 admin API 的 dry-run route。
+3. 新增 admin UI “Convex 迁移”面板。
+4. 新增 apply / rollback route。
+5. 补 browser smoke：dry-run 不写文件、冲突 409、不覆盖、rollback 后 root 恢复。