chore: document architecture gaps and add dev hot reload

- add npm dev:hot wrapper using cargo-watch and page reload polling - add mnote-web dev hot reload endpoint and coverage - record current architecture review and tracked bug findings across realtime, tree, editor, and AI runtimes Verification: - node scripts/task-dev-hot-plan-test.js - node --check scripts/dev-hot.js - cargo test -p mnote-web dev_hot -- --nocapture
2026-05-17 23:09:56 +08:00
parent ee0643041a
commit 3311bd0366
31 changed files with 1220 additions and 1 deletions
@@ -0,0 +1,33 @@
+# 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，尚未收口。
@@ -0,0 +1,32 @@
+# 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，尚未修复。
@@ -0,0 +1,32 @@
+# 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. 状态
+
+已确认标题来源仍有漂移风险，尚未修复。
@@ -0,0 +1,33 @@
+# 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 可能滞后，尚未修复。