mnote/design/04-tree-domain/done/4-34-filetree-trash-dual-browser-no-refresh-v1.md

4-34 Filetree Trash Dual Browser No Refresh v1

状态：done 创建时间：2026-05-15 所属主线：04-tree-domain / VSCode Explorer 文件树与垃圾箱闭环 来源：design/10-review/07-vscode-explorer-filetree-trash-gap-review.md 阶段 8

1. 目标

补齐文件树与垃圾箱的双浏览器 no-refresh 回归：A 浏览器执行页面、附件、mindmap、table 的 create / archive / restore / purge / empty-trash，B 浏览器不刷新即可在 File Tree 与 Trash 工作台看到变化。

阶段 8 不以“单浏览器本地 optimistic update 成功”作为完成标准；refreshTree() 只能作为 A 浏览器本地兜底，不能作为 B 浏览器同步证据。

2. 验收矩阵

对象	create	archive	restore	purge	empty-trash	证据要求
页面 document	A 新建后 B File Tree 可见	A 删除后 B File Tree 消失、Trash 可见	A 恢复后 B File Tree 可见、Trash 消失	A 彻底删除后 B Trash 消失	A 清空页面垃圾箱后 B Trash 清空	记录 tree delta/resync 或 Convex live 来源
普通附件 file asset	A 创建/上传或 seed 后 B File Tree 可见	A 删除后 B File Tree 消失、Trash 可见	A 恢复后 B File Tree 可见、Trash 消失	A 彻底删除后 B Trash 消失	A 清空资源垃圾箱后 B Trash 清空	记录 tree.resource.* / compat alias 与实时来源
mindmap	A 新建 mindmap 后 B File Tree 可见	A 删除后 B File Tree 消失、Trash 可见	A 恢复后 B File Tree 可见、Trash 消失	A 彻底删除后 B Trash 消失	A 清空资源垃圾箱后 B Trash 清空	记录 mindmap route 仍为 compat alias
table	A 新建/seed table 后 B File Tree 可见	A 删除后 B File Tree 消失、Trash 可见	A 恢复后 B File Tree 可见、Trash 消失	A 彻底删除后 B Trash 消失	A 清空资源垃圾箱后 B Trash 清空	记录 table route 仍为 compat alias
local folder Markdown	外部创建 .md 后 page/file tree 可见	✅ task475 API archive（delete 后进入 .mnote/trash，trash-index 记录 local-md:*）	✅ task475 API restore（.md 回原路径，trash 文件消失，index 清理）	✅ task475 API purge（源路径与 trash 路径均不存在，index 清理）	✅ task474 UI empty-trash（清空页面垃圾箱，confirm dialog → refresh()，无导航）	task475 覆盖 loose Markdown API trash lifecycle；task474 覆盖 empty-trash UI；bundled Markdown 由 Rust 单测覆盖
local folder 非 md 资源	✅ task435 外部 create/rename/delete 无 reload	✅ task437 API archive + task464 UI trash	✅ task437 API restore + task473 UI restore no-refresh + focus/reveal	✅ task437 API purge + task464 UI purge	✅ task474 UI empty-trash（清空资源垃圾箱，confirm dialog → refresh()，无导航）	task435/437/464/473 覆盖；restore focus 缺口已关闭，见 task473；task474 覆盖 empty-trash UI

3. 分批执行

3.1 task432：页面生命周期双浏览器

先覆盖页面 document，因为它是 tree.node.* 主链：

• 使用测试账号或一次性用户登录两个 browser context。
• 使用隔离 workspace / 本轮测试前缀创建父页面与子页面。
• B 打开 3000 主入口文档页与 /trash?workspaceId=... 两个 tab，安装 tree event recorder。
• A 执行 create / archive / restore / purge / empty-trash。
• B 每一步不刷新页面，等待 File Tree / Trash DOM 更新，并记录是 tree:delta、tree:resync、EventSource snapshot 还是 Convex live 更新。

通过后才勾选阶段 8 的页面子项。

执行记录：

• 2026-05-15：task432-filetree-trash-page-dual-browser-no-refresh-smoke 已通过。A 浏览器对页面执行 create / archive / restore / purge / empty-trash；B 浏览器文件树与 /trash 均无需刷新可见更新，且全程无 framenavigated。事件来源记录为：create -> tree:resync，archive -> tree:delta remove_document，restore -> tree:delta upsert_document，purge -> tree:resync，empty-trash -> tree:resync。结果文件：tmp/task432-filetree-trash-page-dual-browser-no-refresh-smoke/result.json。
• 2026-05-15：清空页面垃圾箱的初次 smoke 暴露两层根因并已修正：Rust documents.emptyTrashByWorkspace 之前未写 tree.trash.documents.emptied domain event，Convex documents.emptyTrashByWorkspace validator 也未放行 streamDeltaHint/domainEventHint/domainEventPlan，导致 /trash 必须刷新才清空。两处已补齐并重新部署本地 Convex。

3.2 task433：普通附件生命周期双浏览器

覆盖普通 file asset：

• 优先复用 task428 / task427 的 API seed 方式，避免依赖上传文件选择器。
• archive / restore / purge 走 /api/media/batch 与 /api/media/purge 兼容 URL，但必须能在 artifact / response 中证明进入 tree.resource.archive/restore/purge。
• B 侧分别观察 File Tree 与 Trash 工作台。

执行记录：

• 2026-05-15：task433-filetree-trash-file-asset-dual-browser-no-refresh-smoke 已通过。A 浏览器对普通附件执行 upload / archive / restore / archive+purge / upload+archive+empty-trash；B 浏览器文件树与 /trash 均无需刷新可见更新，执行阶段无 framenavigated。事件来源记录为：upload -> tree:delta upsert_assets，archive -> tree:resync，restore -> tree:resync，purge -> tree:resync，empty-trash -> tree:resync。结果文件：tmp/task433-filetree-trash-file-asset-dual-browser-no-refresh-smoke/result.json。
• 2026-05-15：初次 smoke 暴露 tree.resource.archive/restore/purge legacy Convex 参数转换覆盖真实 Convex userId，导致 mediaAssets.patchById membership 检查失败；已修正 mnote-web transport，使资源 lifecycle 转换优先保留 args_json.userId。随后暴露 /api/media/empty-trash 不写 tree event，导致 B /trash 清空必须刷新；已补 tree.trash.media.emptied domain event 与 resync_required stream delta。
• 2026-05-15：验证 cargo test --manifest-path rust/Cargo.toml -p mnote-web convex_resource_lifecycle_args_keep_effective_user_id -- --nocapture、cargo test --manifest-path rust/Cargo.toml -p mnote-web media_trash_routes_delete_restore_purge_and_empty -- --nocapture 均通过。

3.3 task434：mindmap / table 生命周期双浏览器

覆盖仍处 compat alias 的 mindmap / table：

• mindmap 可复用现有 mindmap block / asset seed 方式。
• table 可复用 task427 的 table seed 与 purge query 方式。
• 本阶段不把 mindmap / table 宣称为正式 tree.resource.* cutover，只验证双浏览器可见性并保留 compat 边界。

执行记录：

• 2026-05-15：task434-filetree-trash-mindmap-table-dual-browser-no-refresh-smoke 已通过。A 浏览器对 mindmap 执行 create / archive / restore / archive+purge，对 table 执行 create / archive / restore / archive+purge，并对 mindmap + table 执行 create / archive / empty-trash；B 浏览器文件树与 /trash 均无需刷新可见更新，执行阶段无 framenavigated。结果文件：tmp/task434-filetree-trash-mindmap-table-dual-browser-no-refresh-smoke/result.json。
• 2026-05-15：为避免把 table 预置数据误标为 create 实时证据，Rust mnote-web 已新增 /api/tables/create 兼容入口，创建成功后记录 tree.resource.table.created domain event 与 resync_required stream delta。mindmap / table 的 delete / restore / purge / empty-trash compat route 也补齐 tree resync artifacts。
• 2026-05-15：事件来源记录为：mindmap create / archive / restore 主要触发 tree:delta resync_required，mindmap purge 触发 tree:resync；table create / archive / restore 主要触发 tree:delta resync_required，table purge / empty-trash 触发 tree:resync。
• 2026-05-15：验证 cargo test --manifest-path rust/Cargo.toml -p mnote-web trash_routes -- --nocapture --test-threads=1 与 node --check scripts/task434-filetree-trash-mindmap-table-dual-browser-no-refresh-smoke.js 均通过。

3.4 task435：empty-trash 双浏览器汇总

在一次性 workspace 中执行页面垃圾箱与资源垃圾箱清空：

• A 清空页面垃圾箱后，B /trash 页面不刷新变为空。
• A 清空资源垃圾箱后，B /trash 页面资源区不刷新变为空。
• Convex query 断言对应对象不可再查询。

3.5 task436：local folder watcher 与本地资源生命周期

本阶段不混入 Convex 双浏览器矩阵，单独验证 local folder source：

• 打开 local folder page tree 与 filetree，记录初始 navigationEvents。
• 外部创建 .md，断言 page tree / filetree 可见，并记录是否由 /api/local-folder/events、/api/tree/local-folder-watch、reload 或手动刷新驱动。
• 外部重命名 .md，断言旧 row 消失、新 row 出现；当前打开文档若受影响，应出现刷新或冲突提示。
• 外部删除 .md，断言 page tree / filetree 中 row 消失；若当前打开该文档，应有明确状态提示。
• 外部创建 / 重命名 / 删除至少两类非 md 文件，例如 .txt 与 .png，断言 filetree 与真实文件系统一致，并记录是否发生 window.location.reload()。
• 对本地非 md 资源执行删除 / restore / purge；若 UI 仍禁用，记录为未完成能力，不得用 Markdown trash 代替。

当前只读审计结论：

• LocalFolderWatcherRegistry 使用 notify 递归监听 root，但事件发送前经过 is_markdown_path，只允许 .md/.markdown。
• /api/local-folder/events 订阅该 watcher，主要服务打开的本地 Markdown document session。
• 主 tree 的 local folder 模式不接 /api/tree/events，而是轮询 /api/tree/local-folder-watch（startLocalFolderSidebarWatch，1200ms 间隔）。revision 变化时调用 refreshLocalFolderSidebarSnapshot() 重渲染 filetree，不触发 window.location.reload()。Rust 单元测试 sidebar_tree_runtime_polls_local_folder_without_browser_reload 验证了 SSR template 中不含 reload 语句。
• trash workbench 的 local folder restore/purge 使用 refresh()（gateway.rs:1040-1060）：fetch + DOMParser 替换 workbench innerHTML，不触发浏览器导航。但 restore/purge 完成后不调用 refreshLocalFolderSidebarSnapshot()，filetree 更新依赖下次轮询触发。
• task163-local-folder-unified-tree-browser-smoke.js 已覆盖外部新增 Markdown、外部新增 / 删除 watcher-asset.txt 的可见性；task435-local-folder-watch-no-reload-smoke 已覆盖 Markdown 与非 md 外部 create/rename/delete 无 reload；非 md trash/restore/purge 已由 task437（API）和 task464（UI）覆盖；local folder Markdown 自身 trash lifecycle（archive/restore/purge through tree commands）已由 task475 覆盖（API-only：loose Markdown 的 delete → trash 进入/restore 恢复/purge 清理）。
• task435-local-folder-watch-no-reload-smoke 已通过：外部非 md 文件（.txt、.png）的 create / rename / delete 在 filetree 中无刷新可见更新，全程无 framenavigated。（结果：tmp/task435-local-folder-watch-no-reload-smoke/result.json）
• task437-local-folder-asset-trash-lifecycle-smoke 已通过（API-only）：tree.resource.archive / restore / purge 的 canonicalCommand 与文件系统一致性。（结果：tmp/task437-local-folder-asset-trash-lifecycle-smoke/result.json）
• task464-local-folder-resource-trash-ui-smoke 已通过（Browser UI）：trash 页中 delete→visible / restore→file restored / purge→file gone 完整 UI 流程。（结果：tmp/task464-local-folder-resource-trash-ui-smoke/result.json）
• task473-local-folder-trash-restore-no-refresh-focus-gap-smoke 新增并已由 Codex + Reasonix Browser Worker 实跑：验证 trash workbench 的 restore 操作为 fetch 型 refresh()（restoreNavFree.delta=0，不触发浏览器导航），restore 后 filetree 通过轮询显示恢复行（fileReappearsInFiletree=true）。2026-05-21/22 Codex 修复并复跑后，恢复行出现 focus 证据（data-active="true"），focus gap 已关闭。（结果：tmp/task473-local-folder-trash-restore-no-refresh-focus-gap-smoke/result.json；浏览器证据：tmp/reasonix-batch-a-browser-task473-2026-05-21/）
• task475-local-folder-markdown-trash-lifecycle-smoke 已通过（API-only）：验证 loose Markdown 页面在 /api/tree/commands 的 delete（archive）→ restore → 再次 delete → purge 完整生命周期，文件系统与 trash-index.json 一致性。当前实现中 loose Markdown 的 delete/restore/purge 响应不含 canonicalCommand 字段（与 trash_local_raw_file 不同）。bundled Markdown 未覆盖（bundle 涉及目录整体移动/恢复，由 Rust 单测 local_tree_command_manages_loose_markdown_like_regular_file 和 local_tree_command_delete_page_bundle_directory_uses_page_trash 覆盖）。（结果：tmp/task475-local-folder-markdown-trash-lifecycle-smoke/result.json）
• task474-local-folder-empty-trash-ui-smoke 新增：验证 local folder trash workbench 的清空页面垃圾箱（local-empty-documents）和清空资源垃圾箱（local-empty-resources）按钮操作。点击按钮后 accept confirm dialog，refresh() 以 fetch+DOMParser 替换 innerHTML，不触发浏览器导航；断言对应 trash row 消失、trash-index.json 对应 entry 清理、trash 文件删除。结果写入 tmp/task474-local-folder-empty-trash-ui-smoke/result.json。
• 2026-05-21：Codex 在最新临时 mnote-web http://127.0.0.1:3014 上复跑 task474 / task475 均通过；Reasonix Browser Worker 输出 tmp/reasonix-batch-a3-browser-task474-empty-trash-2026-05-21/，截图显示清空后页面与资源均为 0，两个清空按钮 disabled。

通过后才允许在 10-review 中把 local folder 阶段 8 子项勾选；如果仍发生 reload，只能标为“reload 型刷新可见”，不能标为 no-refresh。

4. 实时来源记录

每个 smoke 结果必须记录：

• B 浏览器是否接到 /api/tree/events。
• B 浏览器是否接到 tree:snapshot、tree:delta、tree:resync。
• B 侧 DOM 更新是否发生在无 reload / 无 framenavigated 的前提下。
• 是否依赖了 A 浏览器本地 refreshTree()；如果依赖，只能作为 A 本地补偿，不计入 B 实时证据。

5. 当前边界

• 3000 常驻进程可能是旧 mnote-web 二进制；修改 Rust 后做 smoke 时必须重启 3000，或用新编译的临时 3001 并在结果中明确记录。
• 资源生命周期中，普通附件 file asset 已进入正式 tree.resource.*；mindmap / table 仍是 compat route，阶段 8 只验证 no-refresh，不改变 cutover 口径。
• local folder Markdown watcher 只有部分历史覆盖，且主 tree filetree 当前是 revision polling；非 md 本地资源文件 watcher / trash / restore / purge 已由 task435（外部 create/rename/delete）、task437（API trash lifecycle）、task464（trash UI）、task473（restore no-refresh + focus/reveal）分项覆盖；local folder empty-trash UI（md 页面 + 非 md 资源）已由 task474 覆盖；local folder Markdown loose page trash lifecycle 已由 task475（API）覆盖；bundled Markdown 由 Rust 单测覆盖，尚未编写独立 smoke。
• resync_required delta 不是数据替换本身，必须伴随后续 snapshot / resync 或客户端主动拉取 snapshot；后续新增资源 route 时必须补事件合同回归。

6. 完成标准

• design/10-review/07-vscode-explorer-filetree-trash-gap-review.md 阶段 8 的 Convex 页面、普通附件、mindmap、table checklist 全部有对应 smoke 证据。
• local folder 子项必须有 task435/437/464/473/474/475 或等价 smoke 证据；若仍发生 reload，保持未完成 no-refresh 状态。restore focus 已由 task473 关闭，不再视为 blocker。
• 每个 smoke 结果写入 tmp/task43*-*/result.json，并在 10-review 中记录命令、对象、实时来源和剩余边界。
• 不再用单浏览器 no-refresh、API purge 成功或 Convex query 成功替代双浏览器 UI no-refresh。