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

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

## 4. 验收

- [x] Rust 测试覆盖 `local-file:Page/资源.ext` delete / restore / purge。
- [x] Rust 测试覆盖本地 mindmap 文件单独删除进入 trash index。
- [x] 浏览器 smoke 覆盖本地文件夹资源行单独删除后垃圾箱可见、恢复回原路径、永久删除清理索引。
- [x] 现有 `task437-local-folder-asset-trash-lifecycle-smoke.js` 继续通过。
- [x] `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 二进制上传矩阵。