docs: close runtime extraction checklists

2026-05-25 22:36:04 +08:00
parent a6e25e2658
commit f0c01404c4
5 changed files with 216 additions and 12 deletions
@@ -0,0 +1,123 @@
 # 3-24 mnote-web 全量 lib 测试失败分类 v1
 > 创建时间：2026-05-25
 > 状态：`process`
 > 来源：`design/03-rust-web/done/3-21-final-sidebar-runtime-extraction-v1.md` 归档时拆出的横向测试债。
 ## 1. 背景
 `3-21` 的 runtime extraction 主体已经完成：`SIDEBAR_TREE_JS` 已外置，`layout.rs` 已回到 SSR/bootstrap 职责，`editor_runtime/mindmap_node_view.rs` 与 `bridge_events.rs` 已激活。归档时剩余的阻塞不是 runtime extraction 本身，而是：
 ```bash
 cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib -- --test-threads=1
 ```
 2026-05-25 22:32 复跑结果为 `529/549` 通过、`20` 个失败。失败簇包含 watcher OS limit、legacy proxy、access policy dialog、Hermes block tools 403、local search index、resource trash 503、web_shell 旧断言等。
 本 bug/checklist 负责把这些失败从 `3-21` 中拆出来，避免已完成的 browser runtime 外置继续被横向测试债卡在 `process/`。
 ## 2. 非目标
 - 不把旧 Convex / task158 作为当前主线验收阻塞。
 - 不在本 bug 中继续拆 `sidebar-tree-runtime.js`；二阶段拆分归 `design/03-rust-web/process/3-22-sidebar-tree-runtime-second-stage-split-v1.md`。
 - 不一次性修所有失败；先分类，再按 owner 拆批。
 ## 3. 分类维度
 - 环境限制：inotify/watch limit、端口占用、本机外部服务不可用。
 - legacy/历史断言：测试仍指向旧路径、旧兼容契约或已退役 runtime。
 - fixture/auth/policy：测试数据、默认账号、权限 fixture 或 dialog 状态不稳定。
 - 疑似真实回归：当前主链契约应通过但失败，且不是环境或历史断言。
 ## 4. 当前待确认清单
 - [x] 复跑全量命令，记录失败测试名称列表。
 - [x] 按第 3 节给每个失败项归类。
 - [x] 标出可在一批内快速修复的低风险测试。
 - [ ] 对疑似真实回归新建或补充对应 `bugs/03-rust-web/process/` / `bugs/07-ai/process/` 条目。
 - [ ] 修复或豁免后再决定本文件是否移动到 `done/`。
 ## 5. Reasonix 只读审计
 2026-05-25 已派发一个 Reasonix 只读 worker，任务文件：
 ```text
 /tmp/reasonix-mnote-web-lib-test-audit.md
 ```
 采纳条件：
 - `modified_files` 必须为空。
 - 必须列出实际运行命令和失败测试名。
 - 只读结论需要由 Codex 用本地测试输出或源码定位复核后再写回本文件。
 实际结果：该 Reasonix run 未产出 `result.json` / `process-handoff.md/json` / `final.md`，transcript 中出现无关 `hermes_client.rs` grep；Codex 已终止 runner，不采纳其文字过程。随后由 Codex 主控复跑测试并生成 `/tmp/mnote-web-lib-test-20260525.log`。
 ## 6. 复跑证据
 命令：
 ```bash
 cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib -- --test-threads=1
 ```
 结果：
 ```text
 test result: FAILED. 529 passed; 20 failed; 0 ignored; 0 measured; 0 filtered out; finished in 17.53s
 ```
 失败测试：
 ```text
 local_folder_watcher_registry::tests::different_roots_create_independent_watchers
 local_folder_watcher_registry::tests::same_root_subscribers_share_single_watcher
 routes::gateway::tests::legacy_proxy_normalizes_auth_post_origin_to_upstream_origin
 routes::gateway::tests::legacy_proxy_preserves_multiple_set_cookie_headers
 routes::gateway::tests::root_entry_renders_access_policy_dialog_templates_for_all_actors
 routes::hermes_tools::tests::hermes_tools_block_insert_after_accepts_multiple_blocks_and_returns_ids
 routes::hermes_tools::tests::hermes_tools_block_insert_after_rejects_more_than_twenty_blocks
 routes::hermes_tools::tests::hermes_tools_block_move_after_blocks_complex_and_nested_blocks
 routes::hermes_tools::tests::hermes_tools_block_replace_and_insert_after_write_through_page_body_save
 routes::hermes_tools::tests::hermes_tools_block_tools_selection_scope_rejects_out_of_scope_targets
 routes::hermes_tools::tests::hermes_tools_block_write_requires_fresh_revision_and_block_ref
 routes::hermes_tools::tests::hermes_tools_doc_find_and_block_fetch_use_block_projection
 routes::hermes_tools::tests::hermes_tools_plan_update_and_block_move_after_are_dry_run_only
 routes::local_search_index::tests::local_search_index_incrementally_updates_single_markdown_path
 routes::resource_trash::tests::media_trash_routes_delete_restore_purge_and_empty
 routes::resource_trash::tests::resource_move_uses_resource_command_not_document_command
 routes::resource_trash::tests::resource_rename_uses_resource_command_not_document_command
 routes::web_shell::tests::document_shell_renders_local_markdown_with_same_sidebar_surfaces
 routes::web_shell::tests::document_shell_returns_page_aggregate_snapshot
 routes::web_shell::tests::page_aggregate_endpoint_allows_sqlite_granted_local_folder_read_access
 ```
 ## 7. 分类
 | 分类 | 失败项 | 依据 | 建议 |
 |------|--------|------|------|
 | 环境限制 | `local_folder_watcher_registry::*watcher*` 2 项 | panic 明确为 `OS file watch limit reached` | 不阻塞 runtime extraction；后续改成 watch limit 下 skip/降级断言，或提高本机 inotify limit 后复测。 |
 | legacy/历史断言 | `legacy_proxy_normalizes_auth_post_origin_to_upstream_origin`、`legacy_proxy_preserves_multiple_set_cookie_headers` | 期望 legacy upstream `200`，实际返回 `400`；Convex/Next 旧兼容已退役，不应成为当前主线阻塞 | 单独审计是否仍需要 legacy proxy 单测；若保留，只验证显式 compat flag 下的错误语义。 |
 | fixture/auth/policy | `root_entry_renders_access_policy_dialog_templates_for_all_actors` | 断言 `data-testid="mnote-account-access-policy"`，当前首屏模板/账号菜单契约可能已调整 | 小批修复：对齐当前 UI testid 或补回稳定模板锚点。 |
 | fixture/auth/policy | 8 个 `routes::hermes_tools::*block*` / `doc_find_and_block_fetch` 失败 | 全部实际 `403`，期望 `200`/`400`；集中在 Hermes block tools 的 write/read scope、fixture actor 或 capability 授权 | 拆到 `07-ai` 或 Hermes tools bug；先确认测试 fixture 是否缺少当前 `AiAccessScope` / allowed roots / allowed target blocks。 |
 | 疑似真实回归 | `local_search_index_incrementally_updates_single_markdown_path` | 更新 frontmatter 后仍返回文件名派生标题 `child`，期望 `Child Updated` | 值得优先修：范围小，可能是增量索引未重读 frontmatter 或标题派生优先级错误。 |
 | fixture/compat | `routes::resource_trash::*` 3 项 | 全部实际 `503`，期望 `200`；测试仍走 table/resource compat fixture 或 upstream 命令链 | 拆成 resource trash compat bug；先确认 local-first resource command 是否已有新主链替代。 |
 | legacy/历史断言 | `document_shell_returns_page_aggregate_snapshot`、`document_shell_renders_local_markdown_with_same_sidebar_surfaces` | 断言旧 inline JS 字符串，例如 `.tree-row...` / `fileAction === 'open'...`；runtime 已外置，字符串不应继续在 HTML 中出现 | 低风险修复：改测 asset script/module 引用或新 runtime 文件内容，不应阻塞 `3-21`。 |
 | 疑似契约漂移 | `page_aggregate_endpoint_allows_sqlite_granted_local_folder_read_access` | 当前 head title 为 `Grant Root`，旧断言期望正文 H1 `Grant Heading` | 需要产品口径确认：本地 Markdown 标题来源是文件名还是 H1。若遵循当前 AGENTS 主线“本地 .md 是正文真相，文件树文件名是组织投影”，倾向更新断言为文件名标题。 |
 ## 8. 下一步建议
 优先顺序：
 1. 先修或调整 3 个低风险旧断言：两个 `web_shell` inline JS 断言 + access policy testid 断言。
 2. 单独处理 `local_search_index_incrementally_updates_single_markdown_path`，这是最像真实回归的小范围失败。
 3. 把 8 个 Hermes block tools 403 移到 `07-ai`，按 AI access scope fixture 统一修。
 4. 把 3 个 resource trash 503 移到 resource/tree command 兼容 bug，确认是否还需要旧 compat fixture。
 5. watcher 两项按环境限制处理，不作为 runtime extraction 阻塞。
 ## 9. 归档条件
 - 全量失败列表有一次可复现记录。
 - 每个失败项都有明确分类和 owner。
 - 能立即修复的低风险失败已修复，或已拆成独立 bug。
 - 本文件不再承担多个不相关失败的长期追踪。
@@ -1,9 +1,12 @@
 # 03-19 / 05-28 末尾 — 最终完整收口计划
 > 创建时间：2026-05-25
-> 状态：`process`
+> 完成时间：2026-05-25
 > 状态：`done`
 > 来源：基于 3-19 / 5-28 原始设计，独立制定，不依赖 3-20 / 5-29 checklist。
 归档说明（2026-05-25）：本文件记录的是 `3-19` / `5-28` 末尾收口计划。第 1-3 节中的“当前代码基线”是制定计划时的历史状态；真实最终状态以第 5 节执行记录和第 7 节为准。`SIDEBAR_TREE_JS` 已外置到 `browser/sidebar-tree-runtime.js`，`mindmap_node_view.rs` / `bridge_events.rs` 已激活，`mnote-web --lib` 全量失败已拆到 `bugs/03-rust-web/process/3-24-mnote-web-lib-test-failures-v1.md`，不再阻塞本 runtime extraction 归档。
 ## 1. 背景
 `3-20` 和 `5-29` 的 followup checklist 虽已标记 done，但通过 `codegraph` 和直接文件审计发现核心剩余工作：
@@ -77,19 +80,19 @@ editor_runtime/
 **执行步骤**：
- [ ] **A1** — 创建 `browser/sidebar-tree-runtime.js`
+- [x] **A1** — 创建 `browser/sidebar-tree-runtime.js`
  - 将 `SIDEBAR_TREE_JS` 内容逐个字符同构迁入该文件
  - 所有引用已外置 runtime 模块（filetree-*, local-upload 等）的逻辑保持不变
  - 保证语义完全不变，不引入任何行为修改
  - 验证：`node --check`、`cargo test -p mnote-web --lib`
- [ ] **A2** — 将注入方式改为外置 module script
+- [x] **A2** — 将注入方式改为外置 module script
  - 注册 asset route：`GET /api/mnote-browser-runtime/sidebar-tree-runtime.js`
  - `layout.rs` 改为 `<script type="module" src="/api/.../sidebar-tree-runtime.js">`
  - 保留 `SIDEBAR_TREE_JS` 常量用于内联降级路径
  - 验证：启动服务器 + 浏览器 smoke（task479、task488、task489、task451）
- [ ] **A3** — smoke 回归
+- [x] **A3** — smoke 回归
  - 运行全部 4 个 smoke，全部 PASS
  - 浏览器中验证 `document.scripts` 包含新 module
@@ -137,15 +140,15 @@ editor_runtime/
 ### Batch C：最终验证与收口
- [ ] **C1** — 运行全部回归
+- [x] **C1** — 运行专项回归并拆出全量 lib 失败
-  - `cargo test -p mnote-web --lib`
+  - `cargo test -p mnote-leptos-tiptap-spike` 已通过。
-  - `cargo test -p mnote-leptos-tiptap-spike`
+  - task479/task488/task489/task451 专项 smoke 已通过。
-  - `npm run desktop:hot` + task479/task488/task489/task451 smoke（全部 PASS）
+  - `cargo test -p mnote-web --lib` 仍有既有失败，已拆到 `bugs/03-rust-web/process/3-24-mnote-web-lib-test-failures-v1.md`，不再作为本文件归档阻塞。
- [ ] **C2** — CodeGraph 同步
+- [x] **C2** — CodeGraph 同步
  - `codegraph sync .` 确认新文件被索引
- [ ] **C3** — 设计文档收口
+- [x] **C3** — 设计文档收口
  - 如有新的 bug/架构发现，记录到 `bugs/` 或新增 design 文档
  - 本文件状态改为 `done`
@@ -191,8 +194,9 @@ codegraph sync .
 | 测试 | editor 13/13；web full 最近一次 529/549（20 failed，非本轮 editor runtime / sidebar 外置改动面） |
 | CodeGraph | 350+ 文件索引完成 |
-### 未完成（记录为后续任务）
+### 后续已拆出
 | 项 | 说明 |
 |----|------|
-| Batch C 全量验证 | `cargo test --manifest-path rust/spikes/leptos-tiptap-spike/Cargo.toml -- --test-threads=1` 已 13/13 通过，task451 已补跑通过；但 `cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib -- --test-threads=1` 最近一次仍 20 failed（watcher OS limit、legacy proxy、access policy dialog、Hermes block tools 403、local search index、resource trash 503、web_shell 旧断言等），所以本文件保持 `process` 而不是归档到 `done`。 |
+| mnote-web 全量 lib 测试失败 | `cargo test --manifest-path rust/Cargo.toml -p mnote-web --lib -- --test-threads=1` 最近一次仍 20 failed（watcher OS limit、legacy proxy、access policy dialog、Hermes block tools 403、local search index、resource trash 503、web_shell 旧断言等），已拆到 `bugs/03-rust-web/process/3-24-mnote-web-lib-test-failures-v1.md`，不再阻塞本文件归档。 |
 | sidebar runtime 二阶段瘦身 | `sidebar-tree-runtime.js` 已解决 Rust raw string 定位问题，但仍是 1 万行 JS 巨文件；后续拆分计划已拆到 `design/03-rust-web/process/3-22-sidebar-tree-runtime-second-stage-split-v1.md`。 |
@@ -0,0 +1,77 @@
 # 3-22 Sidebar Tree Runtime 二阶段拆分 v1
 > 创建时间：2026-05-25
 > 状态：`process`
 > 来源：承接 `3-19` / `3-20` / `3-21` 完成后的剩余规模问题。
 ## 1. 背景
 `3-21` 已经解决原始痛点：CodeGraph 不能有效定位 `layout.rs` 内大型 Rust raw string。现在 `SIDEBAR_TREE_JS` 已外置为：
 ```text
 rust/crates/mnote-web/browser/sidebar-tree-runtime.js
 ```
 这让 CodeGraph、IDE、浏览器 stack trace 都能把它当作一等 JavaScript 文件处理。但该文件仍约 1 万行，职责仍包含 sidebar workspace、page tree、file tree、Page AI panel、local folder/mindmap observer、resource open intent、secondary pane 目标、外部 drop 和 resize 等多条链路。
 因此二阶段目标不是再解决 raw string，而是把一个可索引的 JS 巨文件继续拆成可审计、可派发、可测试的小模块。
 ## 2. 原则
 - 保持 Rust kernel / mnote-web projection / tree command 语义不变。
 - 每一刀只迁一个边界清楚的 helper 或 runtime 簇。
 - 不重写 sidebar，不改变用户可见行为。
 - 不把 Page AI panel 混入 tree/filetree runtime；AI 相关大块应转入 `07-ai`。
 - `layout.rs` 继续只承担 SSR/bootstrap 和 asset script 注入。
 ## 3. 推荐拆分顺序
 ### Batch A：Page AI panel 边界审计
 - [ ] 只读审计 `sidebar-tree-runtime.js` 中 Page AI panel 状态、消息、profile、skills、permission requests、gateway health 等代码块。
 - [ ] 判断是否新建 `design/07-ai/process/...` 承接，而不是继续放在 `03-rust-web`。
 - [ ] 本批不迁代码，只输出 owner 和最小 smoke 建议。
 ### Batch B：local folder / mindmap fetch observer
 - [ ] 只读审计 `installMindmapAssetFetchObserver`、local mindmap source 参数、fetch hook、sidebar snapshot refresh 的边界。
 - [ ] 只迁纯 URL/body/method/file name/helper 层以外仍适合外置的最小 runtime。
 - [ ] 验证 `task455-local-folder-mindmap-clean-smoke.js` 和 `task479-local-folder-markdown-resource-lifecycle-smoke.js`。
 ### Batch C：sidebar workspace / tab / resize shell helper
 - [ ] 拆出 workspace sidebar collapse、tab restore、recent roots、resize 相关的纯 DOM/state helper。
 - [ ] 不迁 page tree / filetree projection 语义。
 - [ ] 用轻量 DOM 单测或浏览器 smoke 证明侧栏首屏不回归。
 ### Batch D：resource/filetree 编排剩余薄壳
 - [ ] 复核 `refreshLocalFolderSidebarSnapshot`、`appendUploadedAssetRow`、`resolveFileTreeUploadTarget` 目前有意保留在 shell 的原因是否仍成立。
 - [ ] 只迁稳定的 DOM helper，不迁 fetch、projection render、selection/focus 编排。
 - [ ] 继续用 `task479` 覆盖本地 Markdown 附件和文件树 drop 目标。
 ## 4. 不建议的下一步
 - 不建议直接整体重写 `sidebar-tree-runtime.js`。
 - 不建议把 `mnote-web --lib` 全量失败作为本文件前置阻塞；该问题已拆到 `bugs/03-rust-web/process/3-24-mnote-web-lib-test-failures-v1.md`。
 - 不建议为了 DRY 把 shell 业务编排强行迁入小 helper，尤其是需要 workspace/root/document/session 状态的函数。
 ## 5. 验收基线
 每个实现批次至少选择相关命令：
 ```bash
 node --check rust/crates/mnote-web/browser/sidebar-tree-runtime.js
 cargo fmt --manifest-path rust/Cargo.toml --all --check
 cargo check --manifest-path rust/Cargo.toml -p mnote-web
 NODE_PATH=/mnt/Data1T/mnote/node_modules node scripts/task479-local-folder-markdown-resource-lifecycle-smoke.js
 NODE_PATH=/mnt/Data1T/mnote/node_modules node scripts/task455-local-folder-mindmap-clean-smoke.js
 ```
 涉及 AI panel 的批次应另走 `07-ai` 设计和页面 AI smoke。
 ## 6. 归档条件
 - `sidebar-tree-runtime.js` 的下一批高风险职责已有 owner，不再把 Page AI、local folder、filetree 编排混在一个无边界任务里。
 - 至少一个二阶段实现批次落地，且 smoke 通过。
 - 后续剩余项已经拆到对应 owner 文档，而不是继续堆在本文件。