lix-2026
1956a8a21a
- 统一 local-first MVP 后阶段架构口径，补充 process 执行总序和 Reasonix 协作记录 - 归档已完成的 design checklist，标注参考型 process，更新 AGENTS/REASONIX/架构文档 - 补充文件树/主编辑器下载与上下文菜单相关实现、bug 记录和 smoke 脚本 验证：git diff --check；codegraph sync .；cargo test -p mnote-web；node --check scripts/task476-filetree-editor-context-menu-download-smoke.js
152 lines
3.8 KiB
Markdown
152 lines
3.8 KiB
Markdown
# 3-17 Convex Export Web Entry v1
|
||
|
||
状态：process-reference
|
||
|
||
归档说明（2026-05-21）：CLI 迁移闭环已具备并有 smoke 证据；本文只保留为后续 Web 管理入口设计参考，当前不作为 active implementation checklist。若决定短期落地 Web UI，应新建执行 checklist。
|
||
|
||
## 目标
|
||
|
||
旧 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 恢复。
|