mnote/design/05-editor-mainline/reference/5-5-page-aggregate-single-truth-alignment-v1.md

# 5-5 [reference] 主编辑区与树域单一真源对齐方案 v1

> 更新时间：2026-05-18
>
> 当前状态：`reference`。本文作为 Page Aggregate 单一真源长期方案保留；当前执行进度与剩余项以 `5-6` 及 MVP 后阶段 checklist 为准。
>
> 2026-05-18 口径补充：
> - 页面聚合的默认 source 已开始向 local-first workspace 收口；页面正文、标题、设置和上传资源不应再默认把 Convex 视作主数据层。
> - 本文中涉及 Convex 的表述只应理解为 local-first 与 Convex-backed 两种 `WorkspaceSource` 的过渡兼容背景，不应再作为默认产品形态解释。
>
> 2026-05-19 口径补充：
> - local-first 下，本地 `.md` 文件是正文真相；Page Aggregate / EditorBlockDocument / tiptap state 都是投影或工作副本。
> - `documents/save` 只能作为 compat adapter，不能继续承担长期写侧仲裁。AI 后台写入、tiptap 保存、外部编辑器修改必须统一到本地文件版本冲突模型。
>
> 2026-05-22 口径补充：
> - 默认控制面已由 Rust SQLite `control-plane` 承接；本文中“Convex 作为控制面 / 可选同步协作 source”的表述仅代表 2026-05-18 阶段性背景。当前 Convex 只保留历史迁移源、显式 cloud source / compat / sync replica 边界。
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-4-leptos-tiptap-mainline-correction-v1.md`
> - `/mnt/Data1T/mnote/design/old/05-editor-mainline/process/5-3-tiptap-leptos-rust-migration-checklist-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-sidebar-pagetree-filetree-rust-web-rebuild-v1.md`
> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-4-tree-projection-protocol-contract-v1.md`
> - `/mnt/Data1T/mnote/design/01-tree-first-graph-kernel/reference/1-tree-first-graph-kernel-v1.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md`

## 1. 文档目的

这份文档只回答一个当前已经暴露出来的主线问题：

> **当 `leptos-tiptap` 已经成为页面内正式主编辑区后，页面树 / 文件树 / 页面标题 / 页面设置 / 页面正文，是否已经统一成 Rust 主导的单一真源架构。**

当前结论是：

> **还没有。**

当前系统已经不再是：

- `iframe runtime`
- 纯前端假接入
- 纯 `BlockNote` 主链

但也还不是：

- Rust 持有页面聚合真相
- Leptos island 只消费 Rust projection
- 树域与主编辑区共享同一份 page aggregate

它现在更接近于：

> **`Rust snapshot 主读链 + local-first / Convex-backed 双 source 过渡 + 前端本地 state 仍存在` 的混合态。**

因此，当前看到的这些“小问题”：

- 标题单一真源问题已经开始收口，但页面聚合仍未完全统一
- 页面宽度和主编辑区宽度看起来不是一套规则
- 页面设置大部分只改了壳层，没有真正进入主编辑器

并不是孤立 UI bug，而是同一个底层断层的表现：

> **树域 projection 与主编辑区 page runtime 之间，还缺一个统一的 page aggregate 真相层。**

---

## 2. 先给结论

### 2.1 当前不能说已经实现了 Rust 单一真源

虽然当前文档页已经：

- 默认使用页面内正式 `leptos-tiptap` island
- 不再依赖外部 iframe bridge 作为主编辑器
- 正文保存已经能按 `workspaceId/documentId` 绑定到正确页面

但以下事实仍然成立：

- 读取主链已固定为 Rust `mnote.page_aggregate.v1` snapshot，不再通过 TS builder 兜底
- 标题、正文、页面设置虽已开始收口到同一组 page aggregate command family，但 projection 回流与运行时语义还没完全闭环
- 页面树 / 文件树与页头标题的一致性已明显改善，但页头标题、页面设置与编辑器 runtime 还没有完全共享同一份聚合真相
- `pageOptions` 已部分进入 `leptos-tiptap` 运行时语义层，但还没有整体收口完成

所以当前不能把这条线描述成：

> **“主编辑区、页面树、文件树已经统一为 Rust 下唯一真源”。**

更准确的表述应该是：

> **树域已经在向 Rust canonical contract 靠拢，但文档页主编辑区仍处于页面聚合尚未完成的混合切流阶段。**

### 2.2 当前最该收口的不是换编辑器，而是统一页面聚合边界

当前不该重新争论：

- 要不要 `Tiptap`
- 要不要 `leptos-tiptap`
- 要不要继续保留 Convex 作为显式 cloud/compat/sync replica source

这些结论都已经足够明确：

- `Tiptap` 继续作为浏览器输入 runtime
- `leptos-tiptap` 继续作为 Leptos 内正式 editor island 接缝
- `local_folder` 作为默认页面数据真相，SQLite control-plane 持有默认控制面，Convex / 服务端退居显式 cloud/compat/sync replica source

当前真正要收口的是：

> **页面这一层，到底由谁持有聚合语义，前端到底应该消费什么，编辑器到底应该回发什么。**

local-first 后，答案进一步收紧为：

> **正文真相由本地 Markdown 文件持有；Page Aggregate 负责把文件投影成 UI 和 editor runtime 所需结构；写侧必须围绕文件版本做仲裁，而不是继续让 `documents/save` 兼容面决定谁的 revision 有效。**

### 2.3 后续主线应固定为 Page Aggregate，而不是继续零散补洞

从长期架构看，当前主线不应再描述成：

- “继续补几个 `leptos-tiptap` 细节”
- “再把标题同步修一下”
- “再把页面设置接一点进去”

后续主线应改写成：

> **建立 Rust 主导的 `page aggregate`：让页面树 / 文件树 / 页面头部 / 页面设置 / 主编辑区 / AI 写入，都围绕同一组 page projection 与 page command family 运转。**

---

## 3. 当前问题的精确判断

## 3.1 当前页面数据并不是一个统一聚合

当前文档页读取主链已经固定走 Rust `mnote.page_aggregate.v1` 快照：

- Rust `/api/page-aggregate/:id` snapshot
- 页面本地 aggregate state reducer
- preferred sidebar snapshot / 页头标题补偿链

需要特别区分“Rust route 主读链”和“完整 kernel-native projection”：当前 `/api/page-aggregate/:id` 已经由 Rust route / Rust runtime adapter 对外提供稳定 `mnote.page_aggregate.v1` 契约，前端不再恢复 TS runtime builder 主链；但底层 substrate 仍主要来自 `documents:getMeta + documents:getContent` 的兼容聚合。因此当前 projection provenance 应标记为 `CompatMetaContentJoin`，不能写成已经完全由 Rust kernel 原生投影闭环的 `KernelProjection`。

这意味着当前已经不再是：

- `page.tsx` 手工拉 `meta + content` 再现场拼 props

但也还不是：

- 页面所有读写、标题回流、页面设置运行时语义都只围绕一份 Rust page aggregate 自动闭环

这条链本身已经说明：

> **当前页面已经进入 Rust-first 聚合读取阶段，但 canonical page projection 仍未成为页面域唯一真相。**

### 3.1.1 标题链已开始收口，但尚未完成页面聚合统一

当前页头标题已经不再单纯由 `DocumentContent` 内部的长期本地 `pageTitle` 真相驱动，而是开始依赖与 sidebar / breadcrumb 共享的 preferred sidebar snapshot。

这带来两个直接后果：

1. 标题不同步这一类“前端本地状态长期漂移”问题已经明显减少
2. 但标题仍然没有和正文、页面设置一起统一到单一 page aggregate command / projection 边界中

于是：

- 页头、breadcrumb、sidebar、page tree、file tree 的标题一致性已有一轮真实收口
- 但从聚合语义上看，标题仍是一条相对独立的更新链，不等于 page aggregate 已经完成

这类问题不是“防抖没配好”，而是：

> **标题更新仍然是页面聚合之外的一条独立 side effect 链。**

### 3.1.2 正文和页面树仍然不是同一份 projection family

当前正文编辑器使用的是：

- `leptos-tiptap` runtime
- `/api/documents/save`
- `EditorBlockDocument / Tiptap / blocks` 的转换边界

而页面子树 / outline / evidence 使用的是：

- `pageSubtree`
- 前端本地定义的 TS 结构
- “内容与标题未变化时复用旧快照”的策略

这说明当前主编辑区与树域虽然已经能同时工作，但它们仍然不是：

- 同一个 Rust projection family 的不同视图

而是：

- 一边是编辑器保存链
- 一边是页面子树附带快照

因此当前 `pageSubtree` 更像：

- 页面阅读态和 TOC 的辅助投影

而不是：

- 主编辑区与树域共享的 canonical page aggregate

### 3.1.3 页面设置已部分进入 island，但还不是完整 editor runtime 语义

当前页面设置里至少有三类配置：

#### A. 页面壳层布局类

- `wideLayout`
- `smallText`
- `layoutDensity`

#### B. 页面视图类

- `showToc`
- `collapseBacklinks`
- `hideChildPages`

#### C. 编辑器语义类

- `showHeadingNumbers`
- `showBlockRefCount`
- `embedDefaultBlockId`

现在的主要问题不是“这些字段没有存下来”，而是：

> **它们虽然能持久化到 documents 表，也已有一部分进入 `leptos-tiptap` island，但还没有统一进入正式 page aggregate，更没有完整地进入 editor runtime 语义层。**

结果就是：

- 一部分设置已经作用于 island 布局或排版
- 一部分设置只影响阅读态
- 一部分设置被展示出来，但主编辑器内部几乎不消费

这也是为什么当前会出现：

> **页面设置看起来像是真的，但很多只是 UI 层局部生效。**

### 3.1.4 所谓“Rust 路径”里仍有明显 compat 痕迹

当前 rename / move / archive 等页面操作，虽然已经开始声明：

- `preferredCommandName`

但真实落地仍大量停留在：

- `documents.title.update`
- `documents.move`
- `documents.delete`

这说明当前并不能说：

- 树域命令已经完整切到 Rust tree command family

更不能说：

- 页面编辑域已经和树域命令收敛到同一个 page aggregate contract

因此现状应判定为：

> **Rust bridge 已经进入主链，但 page aggregate command cutover 仍未完成。**

### 3.1.5 写侧冲突不能继续藏在 `documents/save` 后面

当前读侧已优先消费 Rust `mnote.page_aggregate.v1` snapshot，但写侧仍有明显兼容痕迹：

- tiptap 保存仍通过 `/api/documents/save` 兼容入口进入 `page.body.save`
- AI 兼容工具写正文时也可能最终进入同一条保存链
- local-first 下 agent 还会直接修改 `.md` 文件

如果继续让这些写入都挤在 `documents/save` 兼容面后面，会再次出现：

- 谁拥有最新 revision
- AI 写入是否覆盖了用户未保存编辑
- tiptap autosave 是否覆盖了 agent 刚写回的文件
- Page Aggregate 读到的是旧 content、EditorBlockDocument 还是最新 `.md`

因此写侧必须改成 VSCode-like 文件版本模型：

```text
current .md file
  -> fileVersion = hash + mtime + size
  -> Page Aggregate snapshot 带 baseFileVersion
  -> tiptap 工作副本记录 baseFileVersion 与 dirty 状态
  -> AI / 外部编辑器写入触发 watcher
  -> clean editor 自动 reload；dirty editor 进入 conflict state
```

这意味着 `EditorBlockDocument` 原生落库闭环不能理解成“再建一份新的正文真相”。local-first 下更合理的定位是：

- `.md` 是 canonical body
- `EditorBlockDocument` 是 runtime-native projection / cache
- `.mnote/cache/<page-id>.editor.json` 或内存缓存可用于加速和保留编辑器特有信息，但必须带 `sourceFileVersion`
- 当 source file version 不匹配时，cache 失效并重新从 `.md` 投影

长期命令面应从 `/api/documents/save` compat route 收口到 `page.body.write` / LocalFS executor，并显式接收 `expectedFileVersion`。任何不带 expected version 的正文写入都只能进入 compat / import 路径，不能作为自动保存主链。

---

## 4. 为什么这些问题会直接影响长期方向

## 4.1 它会削弱 Rust + Leptos 的真正优势

你们要的不是：

- “一个能跑的 Tiptap 页面”

而是：

- Rust 掌握页面与树的真相
- Leptos 成为页面内正式 editor island
- AI 最终直接接入主编辑区写作

如果标题、正文、设置、树节点标题分别走不同链路，那么 Rust + Leptos 的长期优势就会被削弱成：

- 只是“比纯前端多了一层 bridge”

而不是：

- “由 Rust 持有统一对象语义，前端只消费真相投影”

### 4.1.1 AI 直接写主编辑区会缺乏稳定入口

如果后续 AI 要直接进入主编辑区编写，而当前系统没有统一的 page aggregate command family，那么 AI 最终只能选下面几条坏路：

- 直接操作前端 DOM
- 直接操作 Tiptap JSON
- 直接调用不同的标题 / 正文 / 设置接口拼写入

这三条路都不符合长期目标。

长期正确路线必须是：

> **AI 先操作 Rust page aggregate 的命令与块语义，再由 editor island 把结果投影到 live editing surface。**

### 4.1.2 树域与页面域会继续出现“双真相漂移”

只要页面树 / 文件树消费的还是一套资源 meta，而主编辑区头部和页面设置是另一套前端状态，那么后续还会不断出现：

- 标题单一真源已开始收口，但当前尚未和正文、页面设置统一成同一 page aggregate 命令边界
- 页面设置变更只影响一部分视图
- 阅读态与编辑态宽度规则不一致
- 新增一个页面能力时，要改三四条链路

这类问题越到后面越难收。

---

## 5. 正确的目标重写

当前阶段的目标不应再写成：

- “把 `leptos-tiptap` 再打磨得更像官方模板”

而应重写为：

> **建立 Rust 主导的 `page aggregate`，让页面树 / 文件树 / 页面头部 / 页面设置 / 主编辑区 / AI 写入共享同一份页面真相。**

这句话拆开后，意味着下面五点。

### 5.1 Page Aggregate Projection

Rust 侧需要提供一个统一的页面聚合投影，至少包含：

- `page_identity`
  - `workspace_id`
  - `document_id`
  - `node_id`
- `page_head`
  - `title`
  - `icon`
  - `cover`
  - `updated_at`
  - `permissions`
- `page_layout`
  - `wide_layout`
  - `small_text`
  - `layout_density`
  - `show_toc`
  - `show_structure`
- `page_body`
  - `editor_document`
  - `revision`
  - `conflict_detection_key`
  - `stats`
- `page_tree`
  - `outline`
  - `child_pages`
  - `resource_meta`

当前不要求一次把所有字段做满，但必须先把口径冻结。

### 5.2 Page Command Family

后续页面域的操作不应继续被拆成互不统属的零散 mutation，而应在语义上统一到 page aggregate 之下。

最小命令族至少包括：

- `page.head.rename`
- `page.layout.update`
- `page.body.save`
- `page.body.insert_reference`
- `page.body.set_embed_default_block`
- `page.tree.refresh_projection`

这不意味着现在立刻把所有接口名都改掉，而是：

> **从现在开始，所有页面能力都应先判断它属于哪个 page aggregate 子域，而不是继续新增离散 mutation。**

### 5.3 Leptos Island 的正式边界

`leptos-tiptap` island 的职责应收敛为：

- 消费 `page_body`
- 消费必要的 `page_layout` 编辑器相关配置
- 回发正文与块级命令
- 暴露可供 AI / 页面壳使用的稳定 editor handle

它不应再负责：

- 定义页面总真相
- 自己发明页面设置语义
- 在页面壳之外另持有一套页面元信息状态

### 5.4 Tree Domain 的接缝

页面树 / 文件树不需要知道编辑器内部细节，但必须与页面聚合共享：

- 同一份 `document_id`
- 同一份页面标题
- 同一份 `resource_meta`
- 同一份页面可见状态与能力语义

也就是说：

- 树域保持 tree-first
- 页面域保持 page aggregate
- 两者通过稳定 projection contract 对齐

而不是：

- 树域一套标题来源
- 页面域另一套标题来源

### 5.5 Convex 的正确定位

当前不应该把 Convex 当作默认页面主数据层继续扩写，也不应该无计划硬拆已有 Convex 路径。

正确口径是：

- local folder 是早期产品默认页面数据真相
- Convex / 服务端继续作为账号、分享、同步、协作和远端副本控制面
- Rust 持有 canonical contract 与语义编排
- Leptos / Next 负责消费 projection 与呈现 island

因此，“Rust 单一真源”在当前阶段的正确含义不是：

- 只有 Rust 数据库

而是：

- **Rust 持有语义单一真源，local-first workspace 持有默认数据真相，SQLite control-plane 持有默认控制面；Convex 只作为历史迁移源、显式 cloud source / compat / sync replica。**

---

## 6. 当前哪些地方需要纠偏

## 6.1 需要纠偏的不是“页面里还有前端状态”

页面壳中存在一些本地临时状态本身没有问题。

问题在于：

- 哪些状态是临时 UI 状态
- 哪些状态却在冒充对象真相

后续必须把两者分清。

### 6.1.1 可以继续留在前端壳的状态

- inspector 开关
- comments drawer 开关
- history drawer 开关
- 当前是否在编辑态
- 当前 host observability

这些都是 UI state，不必进入 Rust 真相层。

### 6.1.2 必须退出前端壳真相地位的状态

- 页面标题
- 页面宽度 / 页面布局正式选项
- 编辑器默认嵌入位置
- 页面 outline 的正式来源
- 页面 stats 的正式来源

这些都不应继续被前端 `useState` 长期定义为页面事实。

## 6.2 需要纠偏的不是继续换保存底座

当前正文保存链已经基本可用，真正的问题不是“保存不到页面”，而是：

- 保存成功不等于 page aggregate 已建立

因此：

- 现在不该推翻 `documents.save`
- 也不该另造一套临时保存格式

而应做的是：

> **把标题 / 正文 / 页面设置的语义边界对齐到同一 page aggregate 之下。**

## 6.3 需要纠偏的是页面设置的产品口径

当前页面设置里已经混入了三类字段：

- 真正属于页面布局的
- 真正属于阅读壳的
- 真正属于编辑器 runtime 的

后续必须先分类，再决定哪些继续保留在页面设置面板里，哪些推迟支持，哪些进入 editor island。

否则只会继续出现：

- UI 有按钮
- 数据能存
- 但主编辑器不真正消费

---

## 7. 分阶段落地

下面的阶段不是完整开发清单，而是主线纠偏顺序。

## 7.1 Phase F: 冻结 Page Aggregate Contract

目标：

- 在设计层明确页面聚合的 canonical contract
- 不再让页面页头 / 正文 / 设置 / 子树各自长字段

完成标准：

- 有单独的 page aggregate contract 文档
- 明确 `page_head / page_layout / page_body / page_tree` 的最小字段
- 明确哪些字段是 UI state，哪些字段是 aggregate truth

## 7.2 Phase G: 主文档页改为消费统一聚合

目标：

- 文档页不再手工拼 `title + options + content + pageSubtree`
- 改为消费统一页面聚合返回值

完成标准：

- 页面头部使用聚合中的 `page_head`
- 页面设置初始值使用聚合中的 `page_layout`
- 主编辑区 bootstrap 使用聚合中的 `page_body`
- 树与 TOC 使用聚合中的 `page_tree`

## 7.3 Phase H: `leptos-tiptap` 正式消费 editor-related page options

目标：

- 把真正属于编辑器 runtime 的设置接入 `leptos-tiptap`

最小优先级建议：

1. `wideLayout`
2. `smallText`
3. `layoutDensity`
4. `showHeadingNumbers`
5. `embedDefaultBlockId`

完成标准：

- inspector 改动后，主编辑区表现真实变化
- 不再出现“设置能存，但编辑器内部几乎没变化”

## 7.4 Phase I: 树域与页面域标题统一

目标：

- rename 后页头、sidebar row、page tree、file tree 一致刷新

完成标准：

- 标题变更只经过一套 page aggregate command 语义
- 所有标题消费者都来自同一份更新后的 projection

## 7.5 Phase J: AI 写入入口对齐 page aggregate

> 2026-05-16 口径补充：`mnote.doc.fetch/find/plan_update` 与 `mnote.block.fetch/replace/insert_after/move_after` 已进入 Rust Hermes tool manifest 与 dispatch，最小块级读写闭环已启动。本文继续保留本节，是因为 `scope=selection`、`format=page_xml/text`、多块插入、复杂块移动矩阵和持久审阅 UI 仍由 `7-10` 继续验收。

目标：

- AI 不再绕过 page aggregate 直接拼前端对象

完成标准：

- AI 能通过统一页面命令把内容写入主编辑区
- 人工编辑与 AI 编辑共享同一块语义边界

---

## 8. 当前阶段的完成判定

只有当下面这些条件同时成立时，才能把这条线描述成：

> **“主编辑区与树域已经基本统一到 Rust 主导的单一真源架构”。**

- 文档页消费统一 `page aggregate projection`
- 标题 / 正文 / 页面设置不再是三条分裂真相链
- `leptos-tiptap` island 真正消费 editor-related `page_layout`
- 树标题与页头标题来自同一份 projection
- AI 写入入口开始围绕 page aggregate command family 设计

在此之前，正确口径都应保持为：

> **`leptos-tiptap` 主编辑区已基本可用，但页面聚合仍未收口，当前仍处于从混合态向 Rust 单一真源过渡的过程中。**

---

## 9. 本文结论

这次暴露出的页面宽度不统一、页面设置只部分生效，以及标题链虽已收口但聚合仍未统一，并不是坏消息。

它们的价值在于：

> **它们准确暴露了当前真正缺的不是“再修几个细节”，而是“把页面域提升成一个与树域对齐的 Rust page aggregate”。**

因此，后续主线不应继续散落成：

- 修标题
- 修宽度
- 修页面设置

而应统一收口为：

> **Page Aggregate Contract**
>
> **Page Aggregate Projection**
>
> **Page Aggregate Command Family**

这才是让 `tree-first graph kernel`、`leptos-tiptap` 主编辑区、以及后续 AI 直接写入主编辑区三者真正对齐的正确底层方向。