mnote/ARCHITECTURE.md

# MNOTE 当前架构梳理

> 更新时间：2026-04-28

本文只描述当前仓库中真实成立的主线结构，以及当前最优先的架构收口点。

## 1. 当前主线结论

当前仓库的主线不是：

- `BlockNote-first`
- `Mindmap-first`
- “先拆掉 Convex 再谈 Rust”

当前主线固定为：

1. `tree-first graph kernel` 是长期对象真相层
2. `Convex` 继续保留为当前自托管存储 / 实时 / 文件协作底座
3. `mnote-web` 是当前 Rust Web 主执行面，负责 3000 gateway、server-first shell、query / command / projection / transport 与 realtime stream；Next App Router 已降为 legacy compat / island bundle source，不再是当前主入口
4. 文档页默认主编辑器已切到页面内 `leptos-tiptap` island
5. `BlockNote` 当前保留为 fallback / 对照链，不再代表默认主编辑器方向

一句话收口：

> **Rust 持有语义主导权，Convex 保留底座，前端逐步从重壳转向消费稳定 projection 与少量交互 island。**

补充口径：

> **主 Web 执行面当前以 `mnote-web` 为 3000 owner；Next App Router 只保留为 legacy compat、交互 island bundle source 与显式 debug/迁移辅助边界。**

## 2. 当前主线目录

- `/mnt/Data1T/mnote/wolai-frontend/`
  当前 React island 与 legacy compat 代码来源；Next.js App Router 不再作为 3000 主入口，只在显式 legacy/debug 迁移边界继续服务重交互运行态与对照链。
- `/mnt/Data1T/mnote/rust/crates/core-protocol/`
  Kernel 类型、projection 协议、编辑器协议、树 / 图核心术语。
- `/mnt/Data1T/mnote/rust/crates/bridge-runtime/`
  Kernel query / command、bridge transport、Tiptap <-> editor document 适配、命令解释层。
- `/mnt/Data1T/mnote/rust/crates/mnote-web/`
  Rust Web route、kernel projection、documents/search/mindmap shell、Hermes bridge、stream transport、compat，以及显式开启时的 debug shell；它是当前主 Web gateway / shell / transport owner。
- `/mnt/Data1T/mnote/wolai-frontend/convex/`
  仍在使用的 Convex functions 与数据侧逻辑。
- `/mnt/Data1T/mnote/infra/convex/`
  Convex 自托管部署与基础设施。
- `/mnt/Data1T/mnote/wolai-backend/`
  辅助后端与异步处理，不是当前页面主链。

## 3. 当前页面运行结构

### 3.1 根布局

- `/mnt/Data1T/mnote/wolai-frontend/src/app/layout.tsx`

职责：

- 注入运行时配置
- 挂载 Convex / Query Provider
- 作为前端 App Router 根布局

### 3.2 工作区壳与 Sidebar

- `/mnt/Data1T/mnote/wolai-frontend/src/components/app-layout-shell.tsx`
- `/mnt/Data1T/mnote/wolai-frontend/src/hooks/use-sidebar-data.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/lib/tree-stream/use-sidebar-tree-stream.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/use-preferred-sidebar-snapshot.ts`

当前 Sidebar 不是单一路径，而是三层组合：

1. 初始 SSR / route snapshot
2. query / refetch snapshot
3. tree stream live snapshot

`PreferredSidebarSnapshotProvider` 负责在 query 与 tree stream 之间做 freshness 选择，再把同一份 preferred snapshot 同时给：

- `Sidebar`
- `Breadcrumb`
- 文档页头标题消费链

这说明当前工作区树链已经开始收口，但还不是最终的单一正式 realtime 主链。

## 4. 文档页主链

### 4.1 入口

- `/mnt/Data1T/mnote/wolai-frontend/src/app/(app)/documents/[id]/page.tsx`

当前文档页入口已经不再直接把若干独立字段散传给页面壳，而是：

1. 拉取 `documents.meta.get`
2. 拉取 `documents.content.get`
3. 在前端入口组装 `PageAggregateProjection`
4. 传给 `DocumentShell -> DocumentContent`

对应聚合类型定义：

- `/mnt/Data1T/mnote/wolai-frontend/src/lib/documents/page-aggregate.ts`

### 4.2 文档壳

- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-shell.tsx`
- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx`

`DocumentShell` 现在只是薄封装，文档页核心状态和交互壳集中在 `DocumentContent`。

### 4.3 默认编辑器 host

- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/editor-host-config.ts`
- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/editor-host.tsx`

当前默认 host 为：

- `leptos_tiptap_island`

调试桥仍保留：

- `leptos_tiptap_iframe_debug`

兼容回退仍保留：

- `blocknote`

### 4.4 正式主编辑器

- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/leptos-tiptap-island-editor-host.tsx`

当前默认主编辑器已经是页面内 Leptos island，不再是 iframe bridge。

它负责：

- 加载 Leptos/WASM 编辑器本体
- 接收初始化内容与 page options
- 处理同页事件、命令、保存与状态同步

### 4.5 BlockNote 的当前位置

- `/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocknote-editor.tsx`

`BlockNote` 当前仍保留，但其定位已变成：

- fallback / 对照链
- 迁移期保险丝

而不是默认主编辑器方向。

## 5. 当前编辑器与页面聚合关系

当前文档页已经开始消费统一的前端侧 `PageAggregateProjection`，但仍不能说“页面域已完全统一成 Rust 单一真源”。

当前真实状态是：

- 标题链路已开始与工作区树 canonical snapshot 对齐
- 正文默认由 `leptos-tiptap` island 编辑与保存
- 页面设置已有一部分进入 island 运行时语义
- `page_tree` / `pageSubtree` 已进入统一聚合入口

但仍未完成的关键点是：

1. Rust 侧还没有原生 `Page Aggregate` 契约
2. 标题 / 正文 / 页面设置还不是同一组 page aggregate command family
3. 页面聚合当前仍主要由前端入口装配，而不是 Rust 直接输出

因此当前正确表述应是：

> **文档页已经进入 page aggregate 过渡态，但页面域单一真源仍在推进中。**

## 6. 当前树域结构

### 6.1 Kernel projection 与 route

- `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/kernel.rs`

当前 Rust 已提供：

- `sidebar_tree`
- `page_tree`
- `file_tree`
- `subtree`
- `edges`
- `graph`

这些 route 说明树域 projection family 已经在 Rust 侧具备清晰边界。

### 6.2 树命令现状

- `/mnt/Data1T/mnote/wolai-frontend/src/lib/documents/tree-command-client.ts`
- `/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/tree.rs`
- `/mnt/Data1T/mnote/rust/crates/storage-convex-bridge/src/mapping.rs`

当前树命令已经开始以 `tree.*` 为 preferred command name，例如：

- `tree.node.create`
- `tree.node.rename`
- `tree.subtree.move`

但兼容层仍广泛保留：

- `documents.create`
- `documents.title.update`
- `documents.move`

这说明 tree command cutover 已开始，但还没有完成。

### 6.3 树 realtime 现状

当前 Sidebar 已有：

- query snapshot
- tree stream
- preferred snapshot 选择

正式的 snapshot + delta 主链已经固定到 `mnote-web` 的 `/api/tree/events`，Next `/api/mnote-web/stream` 只保留 compat alias。

因此当前正确表述应是：

> **树域 realtime 主链由 Rust Web `/api/tree/events` 持有，前端只消费稳定 stream contract 与 projection。**

## 7. Mindmap 与 OnlyOffice

### 7.1 Mindmap

当前 Mindmap 不再是系统中心，而是：

- `tree-first graph kernel` 的一种视图 / 编辑挂件

它仍有：

- 文档内嵌块形态
- 独立页面形态

但不应再被理解为对象真相层。

### 7.2 OnlyOffice

OnlyOffice 仍然是：

- 独立页面型编辑器

它不直接嵌入正文主编辑画布；正文中通常通过附件块跳转进入。

## 8. 当前最优先的架构收口

当前最优先的三条主线，不是继续大规模 UI 重写，而是：

### 8.1 Page Aggregate

目标：

- 让标题 / 页面设置 / 正文 / page tree 统一成同一组 page aggregate projection 与 command family

对应设计稿：

- `/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`
- `/mnt/Data1T/mnote/design/05-editor-mainline/done/5-5-1-page-aggregate-contract-v1.md`

### 8.2 Tree Command Cutover

目标：

- 让 `tree.*` 成为正式命令面
- `documents.*` 降为兼容层

对应设计稿：

- `/mnt/Data1T/mnote/design/04-tree-domain/process/4-6-tree-command-protocol-cutover-stage2-v1.md`

### 8.3 Tree Realtime Event Stream

目标：

- 让 snapshot + delta 正式成为树域实时主链
- 减少当前 query/refetch/freshness 补偿链的长期存在

对应设计稿：

- `/mnt/Data1T/mnote/design/03-rust-web/process/3-3-rust-web-tree-realtime-event-stream-v1.md`

## 9. 当前不该再用的旧口径

下面这些说法现在都不准确：

- “默认文档页仍然是 `BlockNoteEditor`”
- “主编辑器还没切到页面内 Leptos island”
- “当前最优先是继续证明 `leptos-tiptap` 能不能跑”
- “当前最优先是先做树域 UI 重构”

当前真正的卡点已经变成：

> **单一真源如何收口，以及 projection / command / realtime 三条链如何从兼容态进入正式主链。**