mnote/design/04-tree-domain/done/4-17-tree-3000-route-thin-proxy-boundary-v1.md

# 4-17 [done] tree 3000 route thin proxy boundary v1

> 创建时间：2026-04-27
>
> 来源：`4-16` Phase N。

## 1. 结论

`3000` 继续是唯一浏览器公开入口，但 tree route 不再承载长期树域主语义。

- Rust runtime 负责 tree command legality、canonical plan、write operation、domain event plan 与稳定 stream delta 语义。
- Rust `mnote-web` route 负责 session/actor、source-specific client、browser/substrate 能力桥、CommandEnvelope、transport、artifact writer 调用与用户可见回包；本文中的 Next route 是历史 thin-proxy 阶段记录。
- Convex 仅在显式 cloud / compat source 下作为 substrate 执行器，不重新生成 tree truth；默认 local-first 路径走 LocalFS + Rust SQLite control-plane。

## 2. Thin Proxy Route

### `/api/tree/commands`

保留职责：

- 读取 auth / cookie 并获取 Convex client。
- 构造 `CommandEnvelope`。
- 调用 `resolveRustBridgeCommandPlan`。
- 调用 `executeRustBridgeMutationTransport`。
- 调用 `recordRustBridgeCommandArtifacts` / failure artifact writer。
- 对浏览器返回 `requestId / traceId / result`。

不得新增：

- 树合法性判断。
- 排序 canonical plan。
- 第二套 tree write truth。
- 长期 streamDelta 主语义拼装。

当前仍保留的 substrate / browser 边界：

- create / copy 后创建页面 scaffold。
- copy 后复制 mindmap 文件。
- move 前采集 sidebar snapshot 作为 Rust preflight data。
- `tree.node.embed` 的目标内容读取与 Rust preflight 数据准备。

`tree.node.embed` 的 `pageReference` block 结构与插入位置已经迁入 Rust `pageAggregateEmbedPlan`；3000 route 不再定义该语义，只负责源/目标快照读取与 preflight 桥接。

### `/api/tree/stream`

保留职责：

- 作为浏览器 SSE / polling 入口。
- 读取 bridge overview。
- 优先转发 command log / domain event 中的 Rust `streamDelta`。
- 缺少稳定 delta 或 command/event 不一致时保守 `resync`。

不得新增：

- 在 Next 层重新解释树排序或 projection truth。
- 为复合命令伪造局部树补丁。

## 3. Debug / Compat Route

### `/api/tree/shell`

定位：

- 仅显式 debug/internal runtime 验证入口。
- 3000 主路径不应默认请求 `mnote-web:3104`。
- 主路径继续使用 same-origin inline host 与 Rust runtime artifact。

## 4. 代码锚点

- `wolai-frontend/src/lib/tree-route-boundary.ts` 固定 3000 route boundary manifest。
- `wolai-frontend/src/app/api/tree/commands/route.test.ts` 绑定 tree commands route 的 thin proxy 定位。
- `wolai-frontend/src/lib/tree-stream/tree-delta.ts` 明确 `resync_required` 为保守等待 snapshot/resync 的 delta。