lix/mnote

Files

T

lix-2026 1569699fbb docs: separate design reference queue

- 将不直接执行的 process-reference 文档迁入各域 reference 目录

- 更新 design/README、AGENTS 和总序文档，固定 process/draft/reference/done 目录语义

- 修正活跃文档中指向旧 process 位置的参考链接

验证：git diff --check；codegraph sync .

2026-05-21 10:19:02 +08:00

3.7 KiB

Raw Blame History

3-17 Convex Export Web Entry v1

状态：reference

归档说明（2026-05-21）：CLI 迁移闭环已具备并有 smoke 证据；本文只保留为后续 Web 管理入口设计参考，当前不作为 active implementation checklist。若决定短期落地 Web UI，应新建执行 checklist。

目标

旧 Convex workspace 迁移到本地 workspace 时，用户应能在 Web 控制台完成：

选择 Convex workspace。
选择目标本地 root。
先 dry run，查看计划、冲突和预计写入。
apply 后得到 manifest、冲突报告、索引重建结果。
需要时按 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 列表。

最小返回：

{
  "ok": true,
  "workspaces": [
    { "workspaceId": "ws_1", "name": "默认空间", "documentCount": 12 }
  ]
}

`POST /api/admin/convex-export/plan`

输入：

{
  "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`

输入：

{
  "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`

输入：

{
  "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

后续落码顺序

把 CLI planner/apply/rollback 拆成可被 Web route 复用的模块。
新增 admin API 的 dry-run route。
新增 admin UI “Convex 迁移”面板。
新增 apply / rollback route。
补 browser smoke：dry-run 不写文件、冲突 409、不覆盖、rollback 后 root 恢复。

3.7 KiB Raw Blame History Unescape Escape