mnote/design/03-rust-web/done/3-6-rust-web-main-execution-plane-checklist-v1.md

# 3-6 [done] Rust Web 主 Web 执行面迁移 checklist v1

> 更新时间：2026-04-28
>
> 对应计划：
> - `/mnt/Data1T/mnote/design/03-rust-web/process/3-5-rust-web-main-execution-plane-cutover-plan-v1.md`
>
> Harness 拆分：
> - `task-019` 到 `task-026`

## 1. 目标

本 checklist 只检查一个长期目标：

> **主 Web 执行面最终迁到 Rust family，而不只是“Rust 拥有 kernel 语义”。**

当前树域 `Sidebar / 页面树 / 文件树 / picker` 已完成 Rust family 默认执行面切换，但这只是树域执行面收口。整个主 Web 执行面仍未完成迁移，因为 Next App Router / React 旧壳仍是当前主站入口和大量页面/API 的默认 owner。

## 2. 完成口径

完成时必须同时成立：

- [ ] `3000` 仍是唯一公开入口。
- [ ] `mnote-web` 默认拥有 `3000` 背后的 gateway / shell / transport。
- [ ] Next App Router 从主入口降级为 legacy compat / island bundle source / debug。
- [ ] 文档页默认 shell 由 Rust Web 输出，并消费 Page Aggregate snapshot。
- [ ] tree realtime 正式主链由 Rust Web 输出 snapshot + delta。
- [x] Search / AI / Mindmap 的页面壳 owner 迁到 Rust Web，React 只保留交互 island。
- [ ] `SKIP_NEXT_LEGACY=1` 下核心 smoke 仍可通过。
- [ ] `design/03-rust-web/process` 中本 checklist 和 plan 移入 `done/`。

## 3. 当前未完成项

### W-0：冻结主执行面 owner manifest 与负向门禁

- [x] 新增 `RUST_WEB_MAIN_EXECUTION_BOUNDARY`。
- [x] manifest 明确 `publicEntry=3000`、`mainWebOwner=mnote-web`、`legacyCompatOwner=next-app-router`。
- [x] 测试禁止把 Next App Router 写回主 Web owner。
- [x] `ARCHITECTURE.md` 明确当前主 Web 执行面仍处于迁移阶段，树域完成不等于全 Web 完成。
- [ ] 验证命令：

```bash
cd /mnt/Data1T/mnote/wolai-frontend
pnpm vitest run src/lib/rust-web-main-execution-boundary.test.ts src/lib/runtime-config.test.ts
cd /mnt/Data1T/mnote
git diff --check -- ARCHITECTURE.md design/03-rust-web wolai-frontend/src/lib
```

### W-1：让 `mnote-web` 默认成为 3000 gateway owner

- [x] `mnote-web` 支持 `MNOTE_WEB_PUBLIC_BIND=127.0.0.1:3000`。
- [x] Next dev 默认改到 legacy upstream port，例如 `127.0.0.1:3100`。
- [x] `scripts/desktop-hot.js` 默认启动 Rust Web gateway 作为 3000 owner。
- [x] `MNOTE_WEB_SKIP_GATEWAY=1` 仅作为紧急回退。
- [x] `task114-rust-web-gateway-entry-smoke.js` 证明 3000 响应来自 Rust gateway。
- [ ] 验证命令：

```bash
node --test /mnt/Data1T/mnote/scripts/desktop-hot.test.js
cd /mnt/Data1T/mnote/rust
cargo test -p mnote-web gateway
cd /mnt/Data1T/mnote
node scripts/task114-rust-web-gateway-entry-smoke.js
```

### W-2：把 runtime config 与 auth/session handoff 迁到 Rust Web

- [x] `mnote-web` 新增 `/api/runtime/config`。
- [x] `mnote-web` 新增 `/api/auth/session` 与 session refresh/handoff route。
- [x] 浏览器 runtime config 不泄漏 internal `MNOTE_WEB_*` base URL。
- [x] Next `/api/auth/mnote-web-token` 降级为 compat/debug。
- [ ] 验证命令：

```bash
cd /mnt/Data1T/mnote/rust
cargo test -p mnote-web session runtime_config
cd /mnt/Data1T/mnote/wolai-frontend
pnpm vitest run src/lib/runtime-config.test.ts src/app/api/auth/mnote-web-token/route.test.ts
```

### W-3：建立 Rust-owned 文档页 / Page Aggregate server-first shell

- [x] `mnote-web` 新增 `/documents/:id` server-first shell。
- [x] `mnote-web` 新增或固定 `/api/page-aggregate/:id`。
- [x] 文档页首屏 HTML 包含 Page Aggregate snapshot / island mount 信息。
- [x] Next 文档页降级为 legacy compat。
- [x] `task115-rust-web-document-shell-smoke.js` 证明默认文档页由 Rust shell 服务。
- [ ] 验证命令：

```bash
cd /mnt/Data1T/mnote/rust
cargo test -p mnote-web document_shell page_aggregate
cd /mnt/Data1T/mnote/wolai-frontend
pnpm vitest run src/components/editor/document-content.test.ts src/lib/documents/page-aggregate-builder.test.ts
cd /mnt/Data1T/mnote
node scripts/task115-rust-web-document-shell-smoke.js
```

### W-4：把主 API transport 从 Next route 收薄为 Rust Web owned

- [x] Rust Web owner 覆盖 documents meta/content/save。
- [x] Rust Web owner 覆盖 tree commands 与 tree projections。
- [x] Rust Web owner 覆盖 search documents transport。
- [x] Next route 只保留 cookie/header 透传和 legacy compat。
- [x] `TREE_3000_ROUTE_BOUNDARY_MANIFEST` 的 owner 口径从 `next-3000` 改成 `rust-web-gateway`。
- [ ] 验证命令：

```bash
cd /mnt/Data1T/mnote/rust
cargo test -p mnote-web documents_api tree_commands search
cargo test -p bridge-runtime page_aggregate tree_subtree_move_command
cd /mnt/Data1T/mnote/wolai-frontend
pnpm vitest run src/lib/tree-route-boundary.test.ts src/app/api/documents/route-adapters.test.ts src/lib/search/request.test.ts
```

### W-5：把 tree realtime stream 固定为 Rust Web 主链

- [ ] Rust Web 输出正式 `/api/tree/events`。
- [ ] 事件覆盖 `snapshot`、`delta`、`resync`、`heartbeat`。
- [ ] `/api/mnote-web/stream` 降级为 compat alias。
- [ ] Sidebar / page tree / file tree consumer 使用 Rust-owned stream。
- [ ] Preferred snapshot 只保留 fallback，不再作为实时事实 owner。
- [ ] 验证命令：

```bash
cd /mnt/Data1T/mnote/rust
cargo test -p mnote-web tree_realtime stream
cd /mnt/Data1T/mnote/wolai-frontend
pnpm vitest run src/app/api/mnote-web/stream/route.test.ts src/lib/tree-stream/tree-stream.test.ts src/lib/tree-stream/use-sidebar-tree-stream.test.tsx
cd /mnt/Data1T/mnote
node scripts/task112-tree-rust-family-regression-smoke.js
```

### W-6：把 Search / AI / Mindmap 页面壳迁到 Rust Web shell + islands

- [ ] `GET /search` 由 Rust Web 输出 server-first shell。
- [ ] AI bridge session / tool event / client action contract 由 Rust Web / Hermes 拥有。
- [ ] `GET /mindmap/:docId/:mindmapId` 由 Rust Web 输出对象页 shell。
- [ ] React Search / AI / Mindmap runtime 只作为 island 或 legacy compat。
- [ ] `task116-rust-web-islands-smoke.js` 证明三类壳 owner 已迁移。
- [ ] 验证命令：

```bash
cd /mnt/Data1T/mnote/rust
cargo test -p mnote-web search_shell ai_bridge mindmap_shell
cd /mnt/Data1T/mnote/wolai-frontend
pnpm vitest run src/components/editor/DocumentAiAgentPanel.runtime.test.tsx src/lib/ai-agent/runtime/runAgent.test.ts src/lib/search/request.test.ts
cd /mnt/Data1T/mnote
node scripts/task116-rust-web-islands-smoke.js
```

### W-7：退役 Next App Router 主入口，完成文档收口

- [x] `task117-next-retirement-guard.js` 证明 `SKIP_NEXT_LEGACY=1` 时核心 smoke 仍可通过。
- [x] 默认启动链不再把 `pnpm dev` 作为 3000 owner。
- [x] `3104` 不恢复为公开入口。
- [x] `ARCHITECTURE.md` 把 Next App Router 改为 legacy compat，而不是当前主入口。
- [x] `3-1-rust-web-long-term-checklist-v2.md` 同步 Phase 8 状态。
- [ ] 本 plan/checklist 移到 `design/03-rust-web/done/`。
- [ ] 验证命令：

```bash
cd /mnt/Data1T/mnote
node scripts/task097-homepage-entry-smoke.js
node scripts/task114-rust-web-gateway-entry-smoke.js
node scripts/task115-rust-web-document-shell-smoke.js
node scripts/task116-rust-web-islands-smoke.js
node scripts/task117-next-retirement-guard.js
git diff --check -- ARCHITECTURE.md design/03-rust-web scripts wolai-frontend rust/crates/mnote-web
```

## 4. Harness task 映射

| Checklist | Harness task | 状态 |
| --- | --- | --- |
| W-0 | `task-019` | completed |
| W-1 | `task-020` | completed |
| W-2 | `task-021` | completed |
| W-3 | `task-022` | completed |
| W-4 | `task-023` | completed |
| W-5 | `task-024` | completed |
| W-6 | `task-025` | completed |
| W-7 | `task-026` | completed |

## 5. 不可误判为完成的情况

- [ ] 只完成树域 DOM shell，不算主 Web 执行面完成。
- [ ] 只让 Rust kernel 拥有 tree / page 语义，不算主 Web 执行面完成。
- [ ] 只在 3000 Next route 中 thin proxy 到 Rust，不算主 Web gateway owner 完成。
- [ ] 恢复 `3104` 作为公开入口，不算完成。
- [ ] React components 仍作为 island 存在可以接受；但 React / Next 继续拥有页面事实源不可接受。

## 6. 当前结论

截至本文件创建时：

- 树域 Rust family 默认执行面：已完成。
- 主 Web 执行面 Rust family 切换：未完成，已拆为 `task-019` 到 `task-026`。