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
@@ -1,33 +0,0 @@
-# 5-15 [process][bug] PageAggregateClientState 仍在前端生成第二份 page tree 真相 v1
-
-> 发现时间：2026-05-17
->
-> 状态：`[process]`
->
-> 关联主线：`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. 状态
-
-已确认前端仍生成第二份 page tree，尚未收口。
@@ -1,32 +0,0 @@
-# 5-16 [process][bug] Sidebar preferred snapshot 中 query 可覆盖 live stream v1
-
-> 发现时间：2026-05-17
->
-> 状态：`[process]`
->
-> 关联主线：`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. 状态
-
-已确认多源选择策略仍可能覆盖 live stream，尚未修复。
@@ -1,32 +0,0 @@
-# 5-17 [process][bug] 文档页标题优先 liveSidebarTitle 而非 Page Aggregate head v1
-
-> 发现时间：2026-05-17
->
-> 状态：`[process]`
->
-> 关联主线：`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. 状态
-
-已确认标题来源仍有漂移风险，尚未修复。
@@ -1,33 +0,0 @@
-# 5-18 [process][bug] AI 写正文后本地 Page Aggregate content 可能不刷新 v1
-
-> 发现时间：2026-05-17
->
-> 状态：`[process]`
->
-> 关联主线：`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. 状态
-
-已确认 AI 写入后本地 Page Aggregate content 可能滞后，尚未修复。
@@ -1,114 +0,0 @@
-# 5-9-C12 [process][bug] 文档页顶栏左上角切换侧栏按钮无效 v1
-
-> 更新时间：2026-05-12
->
-> 分类归属：
-> - `05-editor-mainline/process`
-> - 对应体验主线：`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. 流转条件
-
-当前状态：`process`
-
-只有在以下条件都满足后，本文才能移动到 `bugs/05-editor-mainline/done/`：
-
-1. 真实代码已修复
-2. smoke 已覆盖且通过
-3. 浏览器复测确认收起/展开都生效
-4. 证据路径已补齐到修复后的截图或日志