mnote/design/02-convex-rust-long-term-architecture/done/2-1-page-block-storage-projection-alignment-v1.md

2-1 [done] 页面块存储与投影对齐方案 v1

更新时间：2026-05-16

当前状态：DONE。

2026-05-22 口径补充：本文是 2026-05-18 前后的阶段性 Convex-backed snapshot 对齐记录；当前默认正文真相已收口到 local-first .md / Page Aggregate 投影，Rust SQLite control-plane 承接默认控制面，Convex 仅保留历史迁移源、显式 cloud source / compat / sync replica 边界。

关联文档：

• /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/done/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/done/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 工具要可读、可写、可移动，必须先把三层对齐：

Rust canonical block model
  <-> Page Aggregate block projection
  <-> Convex persisted page body snapshot

当前真实持久化主链仍是：

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。当前默认策略已继续演进为 local-first .md 正文真相 + Rust SQLite control-plane 默认控制面；Convex snapshot 只作为显式 cloud / compat source。

---

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 短期目标

短期固定为：

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

页面正文当前使用：

content_revision: number
content_conflict_key: `${documentId}:${revision}`

AI 写工具必须携带：

• expectedRevision
• conflictDetectionKey
• idempotencyKey
• dryRun

缺少 expectedRevision 或 conflictDetectionKey 时：

• 只允许 dry-run。
• 不允许真实写入。

4.2 块级 revisionRef

块级工具需要额外返回 revisionRef：

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 应从当前：

{
  "content": [],
  "revision": 12,
  "conflictDetectionKey": "doc_1:12"
}

扩展为：

{
  "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，done 边界是“页面块存储与投影关系已经冻结为当前代码可执行合同”；后续更宽执行验收继续由 7-10 承接。

• 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 回读一致的最小闭环已有 smoke 证据。
• blocks 表当前定位在代码和设计中不再被误称为正文主链；当前正文主链仍是 documents.content / Page Aggregate block projection 过渡态。