chore: 保存当前架构收口与 bug 修复快照

归档本轮 P0/P1 bug 修复、设计审查迁移、AI selection scope 收口与 stream contract 调整，并保留当前 05 主线迁移起点。
2026-05-18 17:01:35 +08:00
parent 61ee4a38a2
commit a2cb1338c8
953 changed files with 14383 additions and 211845 deletions
@@ -3,7 +3,7 @@
 > 更新时间：2026-05-14
 >
 > 分类归属：
-> - `05-editor-mainline/process`
+> - `05-editor-mainline/done`
 > - 涉及边界：`04-tree-domain/tree command + file_tree projection`、`06-mindmap/runtime save + resource relation`
 >
 > 用户证据：
@@ -0,0 +1,41 @@
+# 5-15 [done][bug] PageAggregateClientState 仍在前端生成第二份 page tree 真相 v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`05-editor-mainline`
+
+## 1. 问题定义
+
+文档页已经从 Rust `page-aggregate` 读取快照，但前端 `PageAggregateClientState` reducer 在标题或正文变化后仍会本地构建 page subtree projection，并把它作为 AI context 等链路的输入。
+
+## 2. 证据
+
+- [document-content.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx:144) 初始化 page aggregate client reducer。
+- [page-aggregate-client-state.ts](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/page-aggregate-client-state.ts:179) 到 [page-aggregate-client-state.ts](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/page-aggregate-client-state.ts:197) 本地构建 subtree projection。
+- [page-subtree.ts](/mnt/Data1T/mnote/wolai-frontend/src/lib/documents/page-subtree.ts:246) 仍保留 TS 本地 page tree builder。
+
+## 3. 影响
+
+- 文档页、AI context、Rust Page Aggregate 可能看到不同 page tree。
+- 前端本地派生逻辑会继续承载长期语义，违反 Page Aggregate 单一真源收口。
+- 后续 Debug 时很难判断页面结构到底来自 Rust 还是 TS builder。
+
+## 4. 建议修复
+
+- 明确 reducer 只能作为 UI 草稿态，不得生成长期 page tree projection。
+- AI context 应优先读取 Rust Page Aggregate 的稳定 projection。
+- 增加测试：本地编辑后 AI context 与 Rust 回读 projection 必须一致。
+
+## 5. 修复
+
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:227) `currentPageAiContextSnapshot` 不再在编辑器 DOM 与服务端 aggregate 不一致时构造 `local` page subtree；AI context 的 subtree 只来自 Rust Page Aggregate 的 `aggregate.tree.pageSubtree`。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:7448) 增加字符串合同测试，禁止 `pageSubtreeSource: 'local'` 与 `buildPageAiLocalSubtree(localBlocks)` 回到 AI context 主链。
+
+## 6. 验证
+
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web page_ai_context_uses_page_aggregate_subtree_as_single_truth -- --nocapture`
+  - 结果：1 passed
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web ssr::pages::layout::tests -- --nocapture`
+  - 结果：12 passed
@@ -0,0 +1,39 @@
+# 5-16 [done][bug] Sidebar preferred snapshot 中 query 可覆盖 live stream v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`05-editor-mainline`
+
+## 1. 问题定义
+
+Sidebar 同时启动 query/live/initial 与 tree stream，并通过 preferred snapshot 选择最终数据源。当 `query` 与 `tree_stream` 版本相同但内容不同，当前 freshness / syncKey 逻辑可能让 query 压过 live stream。
+
+## 2. 证据
+
+- [app-layout-shell.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/app-layout-shell.tsx:20) 同时使用 Sidebar data 与 tree stream。
+- [use-preferred-sidebar-snapshot.ts](/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/use-preferred-sidebar-snapshot.ts:32) 到 [use-preferred-sidebar-snapshot.ts](/mnt/Data1T/mnote/wolai-frontend/src/components/sidebar/use-preferred-sidebar-snapshot.ts:52) 进行 source 选择。
+
+## 3. 影响
+
+- Sidebar 仍存在 Convex live / HTTP / Rust stream 多链抢真相。
+- 同一版本但不同内容时，用户可能看到旧树或非 Rust stream 结果。
+- WS / SSE 收口后仍可能被 query source 覆盖。
+
+## 4. 建议修复
+
+- 明确唯一预期来源：当 Rust stream 可用时，应由 stream 成为主真相，query 仅初始化或 fallback。
+- 同版本不同内容时必须记录诊断事件，而不是静默按 freshness 选择。
+- 增加单测覆盖同版本冲突。
+
+## 5. 当前主链修复状态
+
+- 原证据指向的 `wolai-frontend/src/components/sidebar/use-preferred-sidebar-snapshot.ts` 已不在当前运行主链；当前仓库中该路径不存在，只在 `recycle/` 下保留历史副本。
+- 当前 3000 主壳由 Rust `SIDEBAR_TREE_JS` + `TREE_LIVE_CONTROLLER_JS` 消费 WS/SSE tree snapshot / delta，不再使用 retired React `usePreferredSidebarSnapshot` 选择器。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:7460) 增加防回归测试，断言当前 sidebar runtime 不包含 `usePreferredSidebarSnapshot`、`preferredSidebarSnapshot` 或 `liveSidebarTitle`。
+
+## 6. 验证
+
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web sidebar_tree_runtime_does_not_use_retired_query_preferred_snapshot_selector -- --nocapture`
+  - 结果：1 passed
@@ -0,0 +1,39 @@
+# 5-17 [done][bug] 文档页标题优先 liveSidebarTitle 而非 Page Aggregate head v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`05-editor-mainline`
+
+## 1. 问题定义
+
+文档页标题显示仍可能优先读取 `liveSidebarTitle`，而不是 Page Aggregate `head.title`。当 Sidebar 多源延迟或抢源时，文档页标题可能被 Sidebar snapshot 覆盖。
+
+## 2. 证据
+
+- [document-content.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx:159) 使用 live sidebar title 参与标题状态。
+- [page-aggregate-client-state.ts](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/page-aggregate-client-state.ts:144) 标题逻辑仍接受外部 live title。
+
+## 3. 影响
+
+- 文档页标题、Sidebar 标题、Page Aggregate head 可能短暂或长期不一致。
+- 标题保存后回读来源不唯一，影响面包屑、AI context、页面 chrome。
+- Page Aggregate 单一真源收口被 Sidebar 侧状态反向覆盖。
+
+## 4. 建议修复
+
+- 文档页自身标题应以 Page Aggregate head 为主，Sidebar title 只作为导航视图投影。
+- Sidebar title 与 Page Aggregate head 冲突时记录诊断并触发 resync。
+- 增加 smoke：改标题后 Sidebar、Breadcrumb、文档页标题同源一致。
+
+## 5. 当前主链修复状态
+
+- 原证据指向的 React `document-content.tsx` / `page-aggregate-client-state.ts` 当前不在运行主链；`wolai-frontend/src` 不存在，历史副本位于 `recycle/`。
+- 当前 Rust 文档壳初始标题来自 Page Aggregate `head.title`，`updatePaneChrome` 也从 `runtimeDescriptor.aggregate.head.title` 更新文档页 chrome。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:7460) 增加防回归测试，断言当前 sidebar runtime 不包含旧 `liveSidebarTitle` 入口。
+
+## 6. 验证
+
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web sidebar_tree_runtime_does_not_use_retired_query_preferred_snapshot_selector -- --nocapture`
+  - 结果：1 passed
@@ -0,0 +1,43 @@
+# 5-18 [done][bug] AI 写正文后本地 Page Aggregate content 可能不刷新 v1
+
+> 发现时间：2026-05-17
+>
+> 状态：`[done]`
+>
+> 关联主线：`05-editor-mainline`
+
+## 1. 问题定义
+
+页面 AI 写正文后，前端本地 Page Aggregate state 只更新 persisted meta，不保证同步正文快照。`editorBridge.replaceWithSnapshot` 在 editor host 内派发 runtime command，但没有直接回写 reducer content。
+
+## 2. 证据
+
+- [DocumentAiAgentPanel.runtime.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/DocumentAiAgentPanel.runtime.tsx:913) 附近处理 AI 写入后的前端状态。
+- [document-content.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/document-content.tsx:876) 附近接收 AI 结果。
+- [leptos-tiptap-island-editor-host.tsx](/mnt/Data1T/mnote/wolai-frontend/src/components/editor/leptos-tiptap-island-editor-host.tsx:772) `replaceWithSnapshot` 只通过 editor runtime command 更新 host。
+
+## 3. 影响
+
+- 用户连续两次问 AI 时，第二次 AI context 可能仍读旧 `pageClientState.content`。
+- 编辑器显示与 Page Aggregate reducer 状态不一致。
+- AI 写入验收如果只看编辑器 DOM，可能漏掉 context stale 问题。
+
+## 4. 建议修复
+
+- AI 写入成功后应触发 Page Aggregate 回读或统一 reducer content 更新。
+- AI context 应从最新 Rust Page Aggregate snapshot 读取，而不是依赖可能过期的本地 reducer。
+- 增加 smoke：AI 修改正文后不刷新页面连续再问一次 AI，断言第二次 context 包含新内容。
+
+## 5. 修复
+
+- [web_shell.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/web_shell.rs:1208) 文档 session 记录 `pageAggregateScriptId`，明确当前 pane 对应的 Page Aggregate JSON script。
+- [web_shell.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/web_shell.rs:1213) 新增 `syncPageAggregateScript`，在外部写入刷新得到新 aggregate 后同步 `__MNOTE_PAGE_AGGREGATE__`。
+- [web_shell.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/web_shell.rs:1624) `refreshSessionFromExternalChange` 更新 session `latestAggregate` 后立即同步 JSON script，使下一次页面 AI context 从最新 Rust Page Aggregate 快照读取。
+- [web_shell.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/routes/web_shell.rs:3085) 增加 shell 合同测试，防止 AI 写入刷新只更新 editor session 而不更新 Page Aggregate script 缓存。
+
+## 6. 验证
+
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web document_shell_returns_page_aggregate_snapshot -- --nocapture`
+  - 结果：1 passed
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web routes::web_shell::tests -- --nocapture`
+  - 结果：10 passed
@@ -0,0 +1,132 @@
+# 5-9-C12 [done][bug] 文档页顶栏左上角切换侧栏按钮无效 v1
+
+> 更新时间：2026-05-18（代码修复）
+>
+> 分类归属：
+> - `05-editor-mainline/done`
+> - 对应体验主线：`5-9 Wolai-aline continuous checklist`
+>
+> 关联文档：
+> - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-9-wolai-aline-continuous-checklist-v1.md`
+> - `/mnt/Data1T/mnote/design/05-editor-mainline/process/5-7-wolai-page-tree-main-editor-experience-restoration-v1.md`
+> - `/mnt/Data1T/mnote/design/04-tree-domain/done/4-2-sidebar-pagetree-filetree-product-interaction-contract-v1.md`
+
+## 1. 问题定义
+
+当前 `3000` 文档页顶部左上角的 `切换侧栏` 按钮可以被点击，但点击后左侧 sidebar 没有收起，再次点击也没有重新展开的状态变化。
+
+这不是页面树节点的展开/折叠问题，而是文档页壳层的 `sidebar shell toggle` 缺失。
+
+## 2. 归类理由
+
+本问题归到 `05-editor-mainline`，而不是 `04-tree-domain`，理由如下：
+
+- 问题入口位于文档页顶栏，不在 `page_tree/file_tree` 行内交互层。
+- 问题影响的是页面壳、顶栏和侧栏显隐体验，属于 `Wolai 页面树与主编辑器体验复刻` 主线。
+- `04-tree-domain` 更关注树 projection、row model、selection/focus、keyboard、DnD、tree command 等合同；本文问题不在这些运行时合同里。
+
+## 3. 真实现象
+
+复现路径：
+
+1. 打开 `http://127.0.0.1:3000/auth`
+2. 点击 `测试账号快速登录`
+3. 进入文档页后，点击顶栏左上角 `切换侧栏`
+4. 观察左侧 sidebar 是否收起
+5. 再点击一次，观察是否重新展开
+
+实际结果：
+
+- 第 1 次点击后，左侧 sidebar 仍然完整可见
+- 第 2 次点击后，左侧 sidebar 仍然完整可见
+- 页面 URL 不变
+- 浏览器 console 未出现报错
+- 关键 network 未出现与 toggle 对应的新请求
+
+期望结果：
+
+- 第 1 次点击应收起左侧 sidebar
+- 第 2 次点击应恢复展开
+- 行为应与 Wolai / 常规文档页壳的 sidebar toggle 一致
+
+## 4. 证据
+
+截图证据：
+
+- 切换前：`/mnt/Data1T/mnote/tmp/hermes-tester/manual-before-toggle.png`
+- 点击一次后：`/mnt/Data1T/mnote/tmp/hermes-tester/manual-after-toggle.png`
+- 点击两次后：`/mnt/Data1T/mnote/tmp/hermes-tester/manual-after-second-toggle.png`
+
+Hermes tester 首轮取证：
+
+- `/mnt/Data1T/mnote/tmp/hermes-tester/first-run/screenshots/01-auth-entry.png`
+- `/mnt/Data1T/mnote/tmp/hermes-tester/first-run/screenshots/02-after-quick-login.png`
+
+窄范围侧栏取证：
+
+- `/mnt/Data1T/mnote/tmp/hermes-tester/sidebar-run/01-auth.png`
+- `/mnt/Data1T/mnote/tmp/hermes-tester/sidebar-run/02-after-login-before-toggle.png`
+
+代码锚点：
+
+- 顶栏按钮渲染位于 `/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:3938`
+- 当前仅能找到按钮渲染与样式，未看到对应的显隐切换绑定：
+  - `/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:3938`
+  - `/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/styles.rs:1940`
+
+## 5. 当前判断
+
+当前更像是：
+
+- 顶栏按钮已经进入 SSR 页面壳
+- 但 `sidebar open/collapsed` 状态未接线
+- 或按钮没有绑定到实际的 sidebar toggle handler
+
+也就是说，这是一条“控件已渲染，但未驱动真实状态”的缺陷，而不是视觉误差。
+
+## 6. 建议完成方式
+
+完成本缺陷至少需要满足下面四条：
+
+1. 顶栏 `切换侧栏` 按钮绑定真实的 sidebar toggle 状态
+2. 第 1 次点击后 sidebar 收起
+3. 第 2 次点击后 sidebar 再展开
+4. 增补可回归 smoke，覆盖：
+   - 登录后点击 toggle
+   - 收起态存在明确 DOM/样式状态
+   - 再次点击后恢复展开
+
+建议验收同时包含：
+
+- 代码验证：相关 Rust SSR / 前端状态接线
+- 浏览器 smoke：真实点击与状态断言
+- 截图复核：收起前 / 收起后 / 再展开后三张图
+
+## 7. 流转条件
+
+当前状态：`done`
+
+只有在以下条件都满足后，本文才能移动到 `bugs/05-editor-mainline/done/`：
+
+1. 真实代码已修复
+2. smoke 已覆盖且通过
+3. 浏览器复测确认收起/展开都生效
+4. 证据路径已补齐到修复后的截图或日志
+
+## 8. 修复记录
+
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:67) 新增 `toggleWorkspaceSidebar`，点击后切换 shell 的 `data-mnote-sidebar-collapsed` 状态，并同步 `documentElement` 观测属性。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:6167) 全局 click handler 接入 `data-mnote-action="toggle-sidebar"`。
+- [layout.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/pages/layout.rs:7336) 顶栏菜单按钮补齐 `data-mnote-action="toggle-sidebar"`、`data-testid="wolai-sidebar-toggle"` 与 `aria-pressed`。
+- [styles.rs](/mnt/Data1T/mnote/rust/crates/mnote-web/src/ssr/styles.rs:224) `data-mnote-sidebar-collapsed="true"` 时隐藏 sidebar，让主编辑区占满空间。
+
+## 9. 验证
+
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web page_layout_sidebar_toggle_is_wired_to_shell_state -- --nocapture`
+  - 结果：1 passed
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web ssr::pages::layout::tests -- --nocapture`
+  - 结果：14 passed
+- `cargo test --manifest-path rust/Cargo.toml -p mnote-web ssr::styles::tests -- --nocapture`
+  - 结果：7 passed
+
+说明：本轮完成了代码接线与 SSR/CSS 合同验证；浏览器截图复核可在后续统一 smoke 中补充。