118 lines
3.4 KiB
Markdown
118 lines
3.4 KiB
Markdown
# 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。
|