1.0 mvp

2026-05-16 12:34:48 +08:00
parent f9336257a5
commit d8bfaea306
17 changed files with 2817 additions and 543 deletions
@@ -0,0 +1,356 @@
+# 2-1 [process] 页面块存储与投影对齐方案 v1
+
+> 更新时间：2026-05-16
+>
+> 当前状态：`PROCESS`。
+>
+> 关联文档：
+> - `/mnt/Data1T/mnote/design/02-convex-rust-long-term-architecture/process/2-tree-first-graph-convex-rust-long-term-architecture-v1.md`
+> - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-13-page-block-identity-and-command-contract-v1.md`
+> - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md`
+> - `/mnt/Data1T/mnote/design/07-ai/process/7-9-page-block-ai-tooling-roadmap-v1.md`
+>
+> 代码依据：
+> - `/mnt/Data1T/mnote/wolai-frontend/convex/schema.ts`
+> - `/mnt/Data1T/mnote/wolai-frontend/convex/documents.ts`
+> - `/mnt/Data1T/mnote/wolai-frontend/convex/blocks.ts`
+> - `/mnt/Data1T/mnote/rust/crates/storage-convex-bridge/src/mapping.rs`
+> - `/mnt/Data1T/mnote/rust/crates/bridge-runtime/src/lib.rs`
+
+---
+
+## 1. 结论
+
+页面块 AI 工具要可读、可写、可移动，必须先把三层对齐：
+
+```text
+Rust canonical block model
+  <-> Page Aggregate block projection
+  <-> Convex persisted page body snapshot
+```
+
+当前真实持久化主链仍是：
+
+```text
+documents.content
+documents.content_revision
+documents.content_conflict_key
+```
+
+`blocks` 表存在，但当前 schema 没有 `order_key` 字段，mutation 也没有维护父子排序和正文 snapshot 的一致性；因此第一阶段不能把 `blocks` 表描述为页面正文事实源。
+
+第一阶段正确策略是：
+
+> **Rust 先持有块语义和命令计划，Convex 仍保存 canonical snapshot 到 `documents.content`；Page Aggregate 从 snapshot 投影出稳定 block view。等块投影、revision、刷新链路稳定后，再评估是否把 `blocks` 表升级为写主链。**
+
+---
+
+## 2. 当前存储状态
+
+### 2.1 `documents` 表
+
+`wolai-frontend/convex/schema.ts` 中 `documents` 保存：
+
+- `content: v.any()`
+- `content_revision: v.optional(v.number())`
+- `content_conflict_key: v.optional(v.union(v.string(), v.null()))`
+- `raw_text`
+- 页面标题、父级、排序、页面设置、统计等字段
+
+`documents.ts` 的 `updateContent` / `updateDocumentContentRecord` 已经支持：
+
+- `expectedRevision`
+- `conflictDetectionKey`
+- revision 自增
+- conflict key 更新为 `${documentId}:${nextRevision}`
+- raw text 回写
+- ingest job debounce
+
+这说明当前页面正文冲突检测已经有页面级版本基础。
+
+### 2.2 `blocks` 表
+
+`blocks` 表当前字段：
+
+- `id`
+- `workspace_id`
+- `page_id`
+- `parent_block_id`
+- `type`
+- `props`
+- `content`
+- `child_block_ids`
+- `created_by`
+- `created_at`
+- `updated_at`
+
+当前问题：
+
+- schema 没有 `order_key`，但 `blocks.ts` 的 append/insertAfter 入参包含 `orderKey` 却未持久化。
+- `insertAfter` 只插入新 block，不维护 sibling order。
+- `replace/remove` 操作的是 `blocks` 表，不会同步 `documents.content`。
+- storage mapping 中旧 `insert_block/update_block/move_block/delete_block` 指向 blocks 类命令，但当前长期页面正文保存仍映射到 `documents:updateContent`。
+
+因此 `blocks` 表当前只能视为历史/辅助/实验 substrate，不是页面正文单一真源。
+
+### 2.3 Rust command 到 Convex 的映射
+
+`storage-convex-bridge` 当前将：
+
+- `documents.save`
+- `page.body.save`
+- `blocks.patch`
+- `tree.node.embed`
+
+映射到 `documents:updateContent`。
+
+这说明当前正式页面正文写入边界仍是 `page.body.save -> documents:updateContent`。
+
+---
+
+## 3. 对齐目标
+
+### 3.1 短期目标
+
+短期固定为：
+
+```text
+AI tool / editor command
+  -> Rust EditorCommand
+  -> canonical EditorBlockDocument
+  -> legacy content snapshot
+  -> page.body.save
+  -> documents:updateContent
+  -> Page Aggregate reload
+```
+
+允许：
+
+- 底层整份 snapshot 回写。
+- `documents.content` 继续是 persisted body。
+- `blocks` 表保持只读参考或历史兼容。
+
+不允许：
+
+- AI 直接写 `documents.content` 私有数组。
+- AI 直接写 `blocks` 表并期待页面正文自动变化。
+- 前端临时 Tiptap JSON 成为存储事实源。
+
+### 3.2 中期目标
+
+中期应让 `PageAggregate.page_body` 输出：
+
+- `content`
+- `revision`
+- `conflictDetectionKey`
+- `blockDocument`
+- `blockProjectionVersion`
+- `projectionSource`
+
+并保证：
+
+- `blockDocument` 可由 `documents.content` 可靠生成。
+- `blockDocument` 可生成 canonical `documents.content`。
+- 保存后 `/api/page-aggregate/:id` 与 `mnote.doc.fetch` 看到相同 block ids。
+- editor session 能基于 revision 刷新。
+
+### 3.3 长期目标
+
+长期如果升级 `blocks` 表为写主链，必须先满足：
+
+- `blocks` 表补齐 `order_key` 或等价排序字段。
+- `blocks` 表与 `documents.content` 的关系明确：谁是事实源，谁是 materialized snapshot。
+- 每个 block write 都能产出 page body revision。
+- 页面读取、搜索、引用、评论、历史、实时事件都消费同一投影。
+- 有迁移、回填、校验和回滚方案。
+
+在这些完成前，不把 `blocks` 表提升为页面正文事实源。
+
+---
+
+## 4. Revision 与 Conflict Key
+
+### 4.1 页面级 revision
+
+页面正文当前使用：
+
+```text
+content_revision: number
+content_conflict_key: `${documentId}:${revision}`
+```
+
+AI 写工具必须携带：
+
+- `expectedRevision`
+- `conflictDetectionKey`
+- `idempotencyKey`
+- `dryRun`
+
+缺少 `expectedRevision` 或 `conflictDetectionKey` 时：
+
+- 只允许 dry-run。
+- 不允许真实写入。
+
+### 4.2 块级 revisionRef
+
+块级工具需要额外返回 `revisionRef`：
+
+```text
+pageRev:{revision}:block:{blockId}:hash:{hash}
+```
+
+用途：
+
+- 防止 AI 基于旧块内容写入。
+- 防止移动时 anchor 已改变。
+- 帮助 dry-run 返回精确 warning。
+
+说明：
+
+- `hash` 可以用 canonical block JSON 或文本/结构摘要计算。
+- Tiptap AI Toolkit `_hash` 可作为参考，但不能替代 mnote `blockId`。
+- 第一阶段 `revisionRef` 不需要单独持久化，可以由 Page Aggregate projection 生成。
+
+### 4.3 冲突粒度
+
+第一阶段冲突粒度：
+
+- 写入仍以页面级 revision 为硬门槛。
+- 块级 `revisionRef` 作为额外预检和 warning 来源。
+
+后续如果引入块级持久化：
+
+- 可以把块级 revision 升级为硬冲突键。
+- 但仍必须推进 page body revision，保证页面快照和实时事件一致。
+
+---
+
+## 5. Projection 对齐
+
+### 5.1 Page Aggregate 输出
+
+`PageAggregate.page_body` 应从当前：
+
+```json
+{
+  "content": [],
+  "revision": 12,
+  "conflictDetectionKey": "doc_1:12"
+}
+```
+
+扩展为：
+
+```json
+{
+  "content": [],
+  "revision": 12,
+  "conflictDetectionKey": "doc_1:12",
+  "blockDocument": {
+    "documentId": "doc_1",
+    "rootBlockIds": [],
+    "blocks": []
+  },
+  "blockProjectionVersion": 1,
+  "projectionSource": "documents.content"
+}
+```
+
+### 5.2 投影来源
+
+投影来源必须显式标记：
+
+- `documents.content`：从当前 persisted snapshot 生成。
+- `editorDocument`：从 canonical editor document 直接生成。
+- `tiptapDocument`：从 Tiptap JSON bridge 生成。
+- `blocksTable`：仅在未来 blocks 表成为受控投影或主链后使用。
+
+### 5.3 Page Aggregate 与 AI 工具一致性
+
+`mnote.doc.fetch`、`mnote.block.fetch`、`mnote.block.replace`、`mnote.block.insert_after`、`mnote.block.move_after` 都必须以 Page Aggregate block projection 为读来源。
+
+写入完成后必须验证三处一致：
+
+- `/api/page-aggregate/:id`
+- 当前 editor session 可见内容
+- 再次 `mnote.doc.fetch` / `mnote.block.fetch`
+
+---
+
+## 6. Editor Session Refresh
+
+块写工具成功后，必须解决“后端已写、前端编辑器还停在旧文档”的问题。
+
+第一阶段可选策略：
+
+1. 触发 page aggregate reload。
+2. 向当前页面 stream/event 发 `page.body.saved` 或等价 body refresh event。
+3. editor island 收到 revision 变化后 reload canonical content。
+
+最低要求：
+
+- 写工具返回新 revision。
+- 前端能检测当前 editor session revision 已落后。
+- smoke 中必须证明刷新页面后内容仍在。
+
+不得把“Convex 已保存”当成用户可见编辑闭环。
+
+---
+
+## 7. 实施顺序
+
+### Phase 1：snapshot canonicalization
+
+- [ ] 从 `documents.content` 稳定生成 `EditorBlockDocument`。
+- [ ] 从 `EditorBlockDocument` 稳定生成 canonical `documents.content`。
+- [ ] 为每个可编辑块生成 `blockId/type/text/attrs/children/order/path/revisionRef`。
+- [ ] Page Aggregate 输出 block projection。
+
+### Phase 2：read projection
+
+- [ ] `mnote.doc.fetch scope=block/full/outline/keyword` 消费 Page Aggregate。
+- [ ] `mnote.block.fetch` 消费 Page Aggregate。
+- [ ] 返回 page revision、conflict key、block revision refs。
+
+### Phase 3：write through Rust command
+
+- [ ] `mnote.block.replace` 生成 `EditorCommand::ReplaceBlock`。
+- [ ] `mnote.block.insert_after` 生成 `EditorCommand::InsertBlockAfter`。
+- [ ] Rust 将命令应用到 canonical `EditorBlockDocument`。
+- [ ] 生成 canonical content 后走 `page.body.save -> documents:updateContent`。
+
+### Phase 4：move gate
+
+- [ ] `mnote.block.move_after` 先只做同父级叶子块 dry-run。
+- [ ] 同父级移动真实写入通过后再考虑标题子树、列表、复杂块。
+
+### Phase 5：blocks 表评估
+
+- [ ] 补 `order_key` 设计。
+- [ ] 明确 `blocks` 表是主链还是 materialized projection。
+- [ ] 设计迁移和双写校验。
+- [ ] 通过后再移动长期写主链。
+
+---
+
+## 8. 不做清单
+
+- [ ] 不让 AI 直接调用 `documents:updateContent`。
+- [ ] 不让 AI 直接调用 `blocks:*` mutation。
+- [ ] 不把 `blocks` 表描述为当前页面正文事实源。
+- [ ] 不把 Tiptap `UniqueID` 或 `_hash` 当作业务 block id。
+- [ ] 不在没有 page revision 的情况下真实写入。
+- [ ] 不在 editor session refresh 未闭环时宣布块写工具完成。
+
+---
+
+## 9. 完成定义
+
+本设计不能标记 `DONE`，直到：
+
+- [ ] Page Aggregate 输出稳定 block projection。
+- [ ] `documents.content -> EditorBlockDocument -> documents.content` 有测试覆盖。
+- [ ] `mnote.block.fetch` 能读取 projection 中任意可编辑块。
+- [ ] `mnote.block.replace` 和 `mnote.block.insert_after` 通过真实页面 smoke。
+- [ ] 写入后 revision/conflict key 更新，刷新页面和 AI 回读一致。
+- [ ] `blocks` 表当前定位在代码和设计中不再被误称为正文主链。