mnote/design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md

# 5-5-1 [done] Page Aggregate Contract v1

> 更新时间：2026-05-14
>
> 关联文档：
> - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-5-page-aggregate-single-truth-alignment-v1.md`
> - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-6-page-aggregate-alignment-checklist-v1.md`

## 1. 文档目的

这份文档只定义一件事：

> **文档页在前端与 Rust 主链之间，当前最小可落地的 `Page Aggregate` 契约。**

它的作用不是取代长期 Rust kernel contract，而是先冻结当前主文档页的聚合边界，阻止：

- 标题、正文、页面设置、page subtree 继续各自散长字段
- 页面壳继续在 props 链上拼第二份页面真相
- `leptos-tiptap` island 继续只接正文而不接页面布局语义

## 2. 当前最小契约

当前最小 `Page Aggregate` 固定为五层：

- `page_identity`
- `page_head`
- `page_layout`
- `page_body`
- `page_tree`

以及一组附属统计：

- `page_stats`

### 2.1 `page_identity`

作用：

> **标识这份页面聚合属于哪一个 page aggregate。**

当前最小字段：

- `documentId`
- `workspaceId`

说明：

- 这层是聚合身份，不是 UI 展示字段。
- 后续如果 Rust kernel 侧补 `nodeId / aggregateId / projectionVersion`，应继续落在这一层，而不是散回页面 props。

### 2.2 `page_head`

作用：

> **承载页面头部的正式真相。**

当前最小字段：

- `title`
- `updatedAt`
- `permissions.readOnly`
- `permissions.disableDownload`
- `permissions.disableCopy`

说明：

- 页头标题属于 `page_head truth`，不是组件局部输入框自己的真相。
- 前端仍可保留一个“输入中”的临时编辑态，但提交后必须回到 `page_head.title`。

### 2.3 `page_layout`

作用：

> **承载页面布局与编辑器 runtime 相关设置。**

当前最小字段：

- `pageOptions.wideLayout`
- `pageOptions.smallText`
- `pageOptions.layoutDensity`
- `pageOptions.showHeadingNumbers`
- `pageOptions.showToc`
- `pageOptions.showStructure`
- `pageOptions.protectEditing`
- `pageOptions.showWordCount`
- `pageOptions.collapseBacklinks`
- `pageOptions.pageFont`
- `pageOptions.hideChildPages`
- `pageOptions.showBlockRefCount`
- `pageOptions.embedDefaultBlockId`

说明：

- 这层不是“页面设置面板 UI state”，而是页面设置的持久化真相。
- 以下字段已经进入 `leptos-tiptap` island runtime payload：
  - `wideLayout`
  - `smallText`
  - `layoutDensity`
  - `showHeadingNumbers`
  - `embedDefaultBlockId`
- 其中 `showHeadingNumbers` / `embedDefaultBlockId` 已进入 runtime payload，但深层语义仍是阶段性桥接：前者还不能描述成完整 heading 编号渲染闭环，后者还不能描述成完整嵌入默认落点闭环。

### 2.4 `page_body`

作用：

> **承载正文内容与保存元数据。**

当前最小字段：

- `content`
- `revision`
- `conflictDetectionKey`

说明：

- 正文相关命令都应收口到 `page_body`，而不是继续发明新的“页面内临时写回”路径。
- `/api/documents/save -> documents.save -> documents:updateContent` 是当前正式 page body 保存入口。
- 2026-04-28 更新：`page.body.saved` 与 `document.snapshot.saved` 已拆成两条正式 domain event。`page.body.saved` 只表达正文块集合保存，`document.snapshot.saved` 承载 snapshot version / content hash / updatedAt，避免正文事件 payload 继续夹带快照语义。
- 2026-04-28 更新：`tree.node.embed` 的 `pageReference` block 结构与插入位置由 Rust `pageAggregateEmbedPlan` 产出；3000 route 只提供源页面标题、目标内容、anchor block 等 substrate preflight，不再自行拼装页面聚合正文结构。

### 2.5 `page_tree`

作用：

> **承载当前页面对应的子树投影。**

当前最小字段：

- `pageSubtree`

说明：

- 当前 `pageSubtree` 仍是兼容过渡态 projection，不应夸大为最终 Rust page aggregate tree contract。
- 但在文档页入口和阅读态/TOC 消费层，它已经归属于 `page_tree`，不再继续散成独立 props。

### 2.6 `page_stats`

作用：

> **承载页面统计的附属投影。**

当前最小字段：

- `wordCount`
- `characterCount`
- `blockCount`
- `todoTotal`
- `todoDone`

说明：

- 统计不是页面身份，也不是布局或正文真相，但它是 page aggregate 的附属部分。

### 2.7 `source` / provenance

作用：

> **标识这份 `PageAggregateProjection` 的真实构建来源。**

当前允许值：

- `KernelProjection`：底层已经由 Rust kernel 原生 page aggregate projection 产出。
- `CompatMetaContentJoin`：对外已经是 Rust `mnote.page_aggregate.v1` 契约，但底层仍由 Rust runtime adapter 消费 `documents:getMeta + documents:getContent` substrate 后聚合。
- `Fixture`：仅允许在测试或显式 dev fixture 场景出现。

说明：

- 当前 `/api/page-aggregate/:id` 主读链属于 `CompatMetaContentJoin`，不是完整 `KernelProjection`。
- `source_label()` / `x-mnote-page-aggregate-owner` 必须与实际来源一致：`KernelProjection -> rust-kernel`，`CompatMetaContentJoin -> compat-join`，`Fixture -> fixture`。
- 前端 loader 只消费 `mnote.page_aggregate.v1` 契约，不应因为来源是 `CompatMetaContentJoin` 而恢复 TS runtime builder 主链。

## 3. 哪些字段是 aggregate truth，哪些只是 UI state

### 3.1 Aggregate Truth

下面这些字段属于 page aggregate truth：

- `page_identity.*`
- `page_head.*`
- `page_layout.pageOptions.*`
- `page_body.*`
- `page_tree.pageSubtree`
- `page_stats.*`

### 3.2 UI State

下面这些只能算前端临时态，不是正式真相：

- 标题输入框当前未提交文本
- 当前是否处于编辑态/阅读态
- host fallback banner / runtime observability
- inspector 当前 tab
- history drawer / comments drawer / AI panel 的打开状态
- slash 菜单、浮动工具条、块手柄 hover 等 island 交互态

约束：

> **UI state 允许存在，但不能再反客为主冒充 page aggregate truth。**

## 4. 哪些字段必须由 Rust 主导，哪些当前允许前端临时持有

### 4.1 必须由 Rust 主导

- `page_head.title` 的持久化结果
- `page_body.content/revision/conflictDetectionKey`
- `page_layout.pageOptions` 的持久化结果
- `page_tree.pageSubtree` 的正式投影来源

### 4.2 当前允许前端临时持有

- 标题输入中的 debounce 缓冲态
- 正文 host 内的未保存 dirty 态
- 只影响单次交互的面板/菜单开关
- `showHeadingNumbers/embedDefaultBlockId` 的“runtime payload 已贯通，但深语义未完成”阶段性桥接逻辑

约束：

> **允许前端临时持有，不等于允许前端成为第二真相。**

## 5. 当前命令收口口径

当前最小命令口径：

- `page.head.updateTitle`
  - 当前前端别名映射到 `documents.title.update`
- `page.layout.updateOptions`
  - 当前前端别名映射到 `documents.options.update`
- `page.body.save`
  - 当前正式入口映射到 `documents.save`

说明：

- 这轮只是把命名与调用口径收口到 page aggregate 子域。
- 底层 bridge / Convex / Rust mutation 名称暂不要求一次性全部重命名。

## 6. 当前未完成边界

以下事项当前仍未完成，不应在 checklist 中超前打钩：

- 树标题与页头标题已经证明消费同一份更新后的 projection
- AI 写入口已经完全脱离 editor bridge，正式执行 page body command
- `showHeadingNumbers` 完整进入 heading 编号渲染语义
- `embedDefaultBlockId` 完整进入嵌入默认落点逻辑

## 7. 当前可对外口径

当前可以准确描述为：

> **文档页已开始消费统一 `Page Aggregate`，标题/页面设置/正文保存也开始按 `page_head / page_layout / page_body` 收口；当前 Rust route 主读链已成立，但 `/api/page-aggregate/:id` 底层仍是 `CompatMetaContentJoin`，树域投影统一与 AI 正式 page body 写入口也仍未完全完成。**