mnote/design/04-tree-domain/process/4-23-local-cloud-explicit-bridge-p3-candidate-v1.md

4-23 [process] Local / Cloud 显式桥接 P3 候选合同 v1

更新时间：2026-05-07

关联：

• 4-21-local-folder-convex-unified-tree-source-v1.md
• 4-22-local-folder-convex-unified-tree-execution-checklist-v1.md

1. 结论

Local / Cloud 桥接只允许作为显式动作出现，不进入 Local Folder 打开、读取、watcher、保存、拖拽或普通树操作主链。

固定候选动作：

• tree.bridge.import.preview
• tree.bridge.import.execute
• tree.bridge.export.preview
• tree.bridge.export.execute
• tree.bridge.publish.preview
• tree.bridge.publish.execute
• tree.bridge.sync.preview

sync.execute 不进入 P3 默认范围；P3 只冻结候选 preview 和手动执行边界。

2. Import Local Folder To Cloud

输入：

• sourceKind=local_folder
• rootUri=file://...
• targetWorkspaceId=ws_...
• selection=rowIds | all

preview 必须输出：

• 将创建的 cloud documents。
• 将上传的附件。
• 本地 mnote_id / .mnote/page-ids.json 到 Convex document id 的映射策略。
• 冲突列表：同名页面、重复 mnote_id、不可读文件、超限附件。
• 回滚计划：已创建 document id、已上传 storage id、可删除顺序。

execute 规则：

• 必须引用 preview id。
• 必须幂等。
• 失败时返回可重试 cursor 和 rollback plan。
• 不允许修改 local root，除非用户显式要求写入 cloud id mapping。

3. Cloud Workspace Export To Local Folder

输入：

• sourceKind=convex_workspace
• workspaceId=ws_...
• targetRootUri=file://...
• selection=rowIds | all

preview 必须输出：

• 将写入的 .md 文件路径。
• 将下载的附件路径。
• Convex document id / asset id 到本地路径的映射。
• 冲突策略：默认 incremental naming，不静默覆盖。
• 回滚计划：本次新建文件、覆盖前备份、下载失败项。

execute 规则：

• 必须引用 preview id。
• Markdown frontmatter 必须保留 mnote_id 或 cloud_document_id。
• 附件路径和对象存储 id 写入 .mnote/cloud-export-map.json。
• 失败时不删除已存在用户文件；只删除本次创建且仍未被用户修改的文件。

4. Publish Local Page To Cloud

输入：

• sourceKind=local_folder
• rootUri=file://...
• documentId=local-md...
• targetWorkspaceId=ws_...
• visibility=private | workspace | public

preview 必须输出：

• 将创建或更新的 cloud page。
• 页面正文、frontmatter、附件引用的转换计划。
• 权限差异说明：local OS 权限不等于 Convex ACL。

execute 规则：

• 只发布选中的单页或显式选择的子树。
• 不启动双向同步。
• 发布结果写入 .mnote/publish-map.json 时必须经用户确认。

5. Manual Sync Candidate

sync 只能作为候选 preview：

• 比较 local revision、cloud domain event cursor 和 mapping。
• 输出三方差异：local-only、cloud-only、conflict。
• 不自动执行。

禁止项：

• 打开 local folder 时自动 import。
• 保存 local .md 时自动上传 Convex。
• Convex stream 事件自动改写本地文件。
• 把 OS 文件权限解释为 Convex ACL。

6. Done Gate

P3 进入实现前必须先满足：

• P0/P1/P2 的 local 和 convex 树操作 smoke 全绿。
• preview UI 已复用统一 preflight/result 组件。
• import/export/publish 均有 rollback plan。
• 至少一个真实浏览器 smoke 覆盖 preview，不允许直接跳 execute。