mnote/design/04-tree-domain/done/4-38-filetree-resource-lifecycle-open-target-checklist-v1.md

4-38 File Tree Resource Lifecycle 与 Open Target 收口 Checklist v1

状态：done

日期：2026-05-20

Owner：File Tree / local_folder executor / resource lifecycle

归档时间：2026-05-21

归档说明：本文的原始未完成项已被后续 4-39 / 4-40 / 4-41 / 4-44 / 4-45 拆分并完成。本文保留为资源 lifecycle 与 open target 收口的追认记录，不再作为活跃 process 入口。

1. 目标

对齐 Sidex Explorer 的“资源模型 + open target + lifecycle command”闭环，先修 MNote 当前最影响 local-first 的缺口：raw local file / directory / resource open target 表达不足、local-file: 删除进入垃圾箱不稳定、资源生命周期多入口分散。

2. 允许修改范围

• rust/crates/mnote-web/src/tree_shell/filetree_runtime.rs
• rust/crates/mnote-web/src/routes/tree.rs
• rust/crates/mnote-web/src/routes/local_folder_source.rs
• rust/crates/mnote-web/src/routes/resource_trash.rs
• rust/crates/mnote-web/src/ssr/pages/layout.rs
• 相关 Rust 单测与本地文件夹 smoke

3. Checklist

• 扩展或补强 File Tree open target，能表达 local raw file、directory、asset folder、mindmap/table/office/image 等资源身份。
• 统一 local resource identity：
  • 支持 local-file:<relativePath>。
  • 保留 local:asset: / local:node: 兼容。
  • 规范化 root-relative UTF-8 path，不允许 root escape。
• resolve_local_raw_file_id 支持真实 projection 暴露的 local-file:，并补 restore/purge 查找兼容测试。
• 本地单独删除 mindmap / office / 普通附件资源时必须进入 .mnote/trash-index.json，不绕过 local trash。
• 前端 delete/bulk delete 对 local resource 优先走 /api/tree/commands 的统一 archive/purge/restore 语义，旧 resource URL 只作为兼容 fallback。
• local_folder move 若传入 sortOrder，不得静默丢弃；至少返回明确 unsupported，或实现稳定排序记录。

4. 验收

• Rust 测试覆盖 local-file:Page/资源.ext delete / restore / purge。
• Rust 测试覆盖本地 mindmap 文件单独删除进入 trash index。
• 浏览器 smoke 覆盖本地文件夹资源行单独删除后垃圾箱可见、恢复回原路径、永久删除清理索引。
• 现有 task437-local-folder-asset-trash-lifecycle-smoke.js 继续通过。
• cargo test -p mnote-web local_folder 相关测试通过。

4.1 本轮执行记录

• 已合入：local-file:<relativePath> 中文路径资源 delete / restore / purge 覆盖，local move sortOrder 返回 _unsupportedFields.sortOrder，避免静默吞字段。
• 已验证：相关 Rust targeted tests 与完整 cargo test -p mnote-web -- --test-threads=1 通过。
• 后续覆盖：
  • 4-39 完成 FileTree open target 与 Resource Identity 收口。
  • 4-40 完成 Resource Lifecycle Command Cutover 与 trash smoke 收口。
  • 4-41 完成 FileTree bulk resource command cutover。
  • 4-44 / 4-45 完成 action layer 与 open editors lifecycle link 收口。
• 2026-05-21 复核：
  • node --check scripts/task437-local-folder-asset-trash-lifecycle-smoke.js && node scripts/task437-local-folder-asset-trash-lifecycle-smoke.js 通过。
  • node --check scripts/task464-local-folder-resource-trash-ui-smoke.js && node scripts/task464-local-folder-resource-trash-ui-smoke.js 通过。
  • node --check scripts/task473-local-folder-trash-restore-no-refresh-focus-gap-smoke.js && node scripts/task473-local-folder-trash-restore-no-refresh-focus-gap-smoke.js 通过。
  • node --check scripts/task474-local-folder-empty-trash-ui-smoke.js && node scripts/task474-local-folder-empty-trash-ui-smoke.js 通过。
• 未完成项：无。本文不再作为活跃入口；若后续发现新的 resource lifecycle bug，应在 bugs/04-tree-domain/process/ 新建缺陷，而不是重开本文。

5. 非目标

• 不做 Convex 云端完整文件系统 parity。
• 不实现完整 undo/redo。
• 不实现复杂 paste / drop 二进制上传矩阵。