mnote/.codex/reasonix-tasks/results/design-governance-worker-b-04-tree.md

# Design Governance Report — Worker B: 04-tree-domain

> 生成时间: 2026-05-21  
> 范围: `design/04-tree-domain/process/` 全部 12 个 process 文档  
> 状态: 只读审查，未修改任何 `design/` 文件

---

## Executive Summary

审查 12 个 process 文档，建议分布：

| 状态 | 数量 | 文档 |
|------|------|------|
| archive-done | 6 | 4-27, 4-39, 4-40, 4-41, 4-42, 4-43 |
| keep-process | 5 | 4-28, 4-34, 4-38, 4-44, 4-45 |
| mark-process-reference | 1 | 4-23 |

**最高风险项**:
1. **4-45 checklist 完全未执行** — 4 项全部未勾选，Worker D 停留在计划阶段未产出任何变更
2. **4-34 local folder 子项仍无 no-refresh 证据** — Convex 侧已全部通过但 local folder 侧仍标 reload，这是 dual-browser 矩阵的唯一缺口
3. **4-44 仍有 3 个 browser smoke 未勾选** — Rust 代码改动已合入但 task430/task471 及新增 smoke 未通过
4. **4-28 React DOM focus 仍缺浏览器证据** — 核心 restore location 已实现但前端焦点行为未验证

---

## 逐文档审查

### 4-23 — Local / Cloud 显式桥接 P3 候选合同 v1

**建议状态：mark-process-reference**

- **证据**: 这是 P3 候选设计合同，定义了 `tree.bridge.import/export/publish/sync` 的 preview/execute 契约。文档无 checklist、无 code change、无 execution record。
- **归档/保留原因**: 这是一个**候选策略文档**，不是执行 checklist。P3 未排入当前 sprint，文档本身定义了清晰的 done gate（P0/P1/P2 smoke 全绿+preview UI 组件复用+rollback plan+浏览器 smoke）。作为长期架构参考保留比归档更有价值。
- **补充说明**: 文档质量高，边界定义清晰。建议在文档头部加注 "P3 Candidate — 未进入实现，参考保留"。

### 4-27 — Resource Lifecycle Command Cutover v1

**建议状态：archive-done**

- **证据**: 
  - Section 2 "已落地范围" 列出 7 个已实现条目：`bridge-runtime` 新增 4 个命令计划、`storage-convex-bridge` 映射、`wolai-frontend` `/api/media/batch` 和 `/api/media/purge` 迁移、`mnote-web` Rust 3000 兼容 alias。
  - Section 3 的 "未完成边界"（双浏览器 no-refresh、reveal/focus、projection delta）已由 4-34 和 4-28 覆盖。
  - Section 7 "剩余边界"（rename 仅覆盖附件、empty-trash 仍为批量合同、前端 Sidebar 仍走旧 URL）是有意保留的边界，非未完成任务。
  - Section 8 sub-stage（local_folder file_path resource lifecycle）已全部合入并通过：`tree.resource.archive/restore/purge` 进入 `.mnote/trash`, `trash-index.json`, `task437` smoke 通过。
  - 2026-05-15 验收测试全部：4 项 `cargo test` 通过，2 项 wolai-frontend 测试通过。
- **归档原因**: 核心命令切换已完成归档。未完成项已明确转移至后续文档（4-34/4-28）或是有意保留的边界（empty-trash 批量合同、rename 范围限制）。
- **补充说明**: 归档前建议在文件头部加注引用 `4-34`(dual browser)、`4-28`(reveal/focus) 和 `4-37`(trash modal) 作为后续入口。

### 4-28 — Trash Restore Location Reveal Focus v1

**建议状态：keep-process**

- **证据**:
  - **已落地**：`restore_parent_id`/`restore_sort_order` schema，`documents.softDelete` 快照写入，`documents.restore` 位置恢复与 fallback 逻辑，Sidebar 恢复后展开 focus。
  - **已验证**：4 个测试文件（32 items）通过，`task429` browser smoke 通过覆盖 restore_location/fallback/sort_order 无重复。
  - Section 5 "待补" 仍有 2 项未完成：React Sidebar Drawer 的恢复后 DOM focus 缺浏览器证据；双浏览器 no-refresh 归入阶段 8。
- **留存原因**: React Sidebar Drawer DOM focus 的浏览器证据未补。当前 3000 主壳 smoke 已覆盖 "恢复后无需刷新可见/reveal"，但 "DOM focus" 断言是 React Drawer 代码路径的独立验证。
- **补充说明**: React DOM focus 是一个较小的缺口，可考虑在下一轮补充一个 focused smoke 后归档。

### 4-34 — Filetree Trash Dual Browser No Refresh v1

**建议状态：keep-process**

- **证据**:
  - **Convex 侧全部通过**：task432(页面) + task433(附件) + task434(mindmap/table) 双浏览器 no-refresh smoke 全部通过且记录了事件来源。
  - task435(empty-trash 汇总) 作为 3.4 提及但**无独立执行记录**，不过其实已被 task432-434 的 empty-trash 子步骤覆盖。
  - **local folder 侧未完成**：3.5 task436 无执行记录。文档明确标注 "非 md 本地资源文件 watcher / trash / restore / purge 仍单列为待补"。
  - 完成标准要求 local folder 子项也通过 task436 或等价 smoke；当前状态标 reload，不能标 no-refresh。
- **留存原因**: local folder 双浏览器 no-refresh 仍然是明确缺口。同时 `resync_required` delta 事件合同需在后续新增资源 route 时补回归。
- **补充说明**: 建议将 Convex 侧已完成的部分在文档内打上标记（如 `[Convex ✓]`），只保留 local folder 暴露项作为未完成。

### 4-38 — FileTree Resource Lifecycle 与 Open Target 收口 Checklist v1

**建议状态：keep-process**

- **证据**:
  - 已勾选：`local-file:<relativePath>`、`resolve_local_raw_file_id`、`local-file` restore/purge 测试、local mindmap 单独删除入 trash index、local move `sortOrder` 返回 `_unsupportedFields`、Rust `cargo test` 通过。
  - **未勾选**：扩展 File Tree open target、保留 `local:asset:/local:node:` 兼容、前端 delete/bulk delete 优先走 `/api/tree/commands`、browser smoke 覆盖全链、task437 继续通过。
  - 执行记录确认 "未完成：File Tree open target 合同扩展、前端 delete/bulk delete 全面 cutover、浏览器垃圾箱资源行全链 smoke"。
- **留存原因**: 虽然核心 Rust 变更已合入，但 open target 扩展已有 4-39 承接，前端 cutover 和 browser smoke 尚未完成。需待这些子项完成后归档。
- **补充说明**: 建议在文档头部加注 "open target 合同由 4-39/4-42 覆盖；bulk delete 由 4-41 覆盖"。本文件的剩余项（前端 cutover + browser smoke）可浓缩后移至更轻量文档。

### 4-39 — FileTree Open Target 与 Resource Identity Checklist v1

**建议状态：archive-done**

- **证据**:
  - **全部 5 项 checklist 已勾选**：扩展 `FileTreeOpenTarget`（`LocalFile`/`Directory` variant + `resourceKind`）、open target 包含 canonical identity、`parse_open_target_from_row` 兼容旧格式、camelCase 序列化、Rust 单测通过。
  - **验收全部通过**：`cargo test -p mnote-web filetree_runtime`、`runtime_api`、`tree_shell_filetree_mode_embeds_asset_state` 全部通过。
- **归档原因**: Checklist 全部完成。唯一剩余项 "上游 row dataset 补齐 rootUri" 已由 4-42 承接。
- **补充说明**: 归档时建议在头部引用 4-42 作为 rootUri 补齐的后续文档。

### 4-40 — Resource Lifecycle Command Cutover 与垃圾箱 Smoke Checklist v1

**建议状态：archive-done**

- **证据**:
  - 从 7 项 checklist 中，6 项已勾选：旧 route 保留 fallback、command response 保留 artifact、trash workbench 显示 local resource、新增 browser smoke (task437 + task464)。
  - **唯一未勾选项**："前端 local resource delete/bulk delete 优先调用 `/api/tree/commands` archive/purge/restore" — 这已被 4-41 覆盖。
  - **验收全部通过**：`task437`、`task464` smoke 通过，`cargo test resource_trash` 和 `cargo test tree_command_local_folder` 通过。
- **归档原因**: 文档定义的 smoke 覆盖率目标已完成。前端 cutover 的剩余项已由 4-41 清晰承接。

### 4-41 — FileTree Bulk Resource Command Cutover Checklist v1

**建议状态：archive-done**

- **证据**:
  - **全部 6 项 checklist 已勾选**：local file asset/mindmap/table bulk delete 使用 tree command、成功后刷新 snapshot/trash、失败保留错误、smoke 覆盖不同 resource kind。
  - **验收全部通过**：`task464`、`task471` smoke 通过，`cargo test sidebar_filetree_local_table_bulk_delete_uses_tree_command` 和 `tree_command_local_folder` 通过。
- **归档原因**: Checklist 已全部完成。云端 table 保留旧 fallback 是有意保留的边界（已勾选禁止事项）。

### 4-42 — FileTree Open Target RootUri Contract Checklist v1

**建议状态：archive-done**

- **证据**:
  - **全部 5 项 checklist 已勾选**：`FileTreeRuntimeEnvironment.rootUri`、`resolve_open_target` 使用 rootUri、SSR state 传入 rootUri、反序列化兼容缺失 rootUri、Rust 单测覆盖。
  - **验收全部通过**：3 项 `cargo test` 全部通过。
- **归档原因**: 文档定义的 rootUri 合同已全部实现。这是 P0-4 的收尾文档，已经完成其使命。

### 4-43 — Local Folder Sort Order Persistence Checklist v1

**建议状态：archive-done**

- **证据**:
  - **全部 6 项 checklist 已勾选**：`.mnote/file-order.json` 持久化、move sortOrder 写入、projection 消费排序记录、rename/archive/restore 后清理悬挂项、Rust 合同测试、browser smoke。
  - **验收全部通过**：`cargo test local_tree_command_move_with_sort_order` 和 `tree_command_local_folder` 通过，`task472` smoke 通过。
- **归档原因**: 完整的端到端实现。`_unsupportedFields.sortOrder` 退役记录清晰。

### 4-44 — FileTree Action Layer Paste / Drop / Delete Checklist v1

**建议状态：keep-process**

- **证据**:
  - **Rust 代码已合入**：`recordFileTreeAction`/`recordFileTreeActionStatus`、右键 `paste-into` 使用菜单触发 row、`layout.rs` readonly 阻断（data 属性标记 + alert fallback）、paste/drop preflight。
  - **验收 2/5 已勾选**：`cargo test -p mnote-web layout` 和 `tree_command_local_folder` 通过。
  - **3 项验收未勾选**：`node scripts/task430-vscode-explorer-stage7-smoke.js`、`node scripts/task471-local-folder-bulk-resource-trash-smoke.js`、新增 `task47*-filetree-action-layer-smoke.js`。
- **留存原因**: Rust 侧变更已合入但 browser smoke 验证未通过。task471 的语义断言依赖 environment preparation（4-45 也依赖同一个环境）。无法在不验证 smoke 的情况下确认动作层行为正确。
- **补充说明**: task430 的 workspace bootstrap 问题（4-45 提及）是前置阻塞项。建议先修复 task430 前置条件，再补全 4-44 的 smoke 验收。

### 4-45 — FileTree / Open Editors Lifecycle Link Checklist v1

**建议状态：keep-process**

- **证据**:
  - **全部 4 项 checklist 未勾选**：
    1. "跑或修复 task430 / task471 的可复现前置条件" — 未完成
    2. "明确哪些 smoke 已过、哪些因环境阻塞" — 未完成
    3. "补充 open editor / filetree active row / lifecycle 状态断言建议" — 未完成
    4. "更新 4-44 checklist 执行记录" — 未完成
  - 执行记录仅包含 Worker D 的讨论和计划，没有实际变更。
- **留存原因**: 这是一份非常新的文档（2026-05-21），所有项都未验证。它不是高复杂度文档，但需要解决 task430 workspace bootstrap 前置问题后才能推进。如果 task430 环境问题没有阻碍，可在 1-2 小时内完成所有 4 项。
- **补充说明**: 这是一份"接通型"文档 — 它的主要目标是让 4-44 的 smoke 验证可复现，以及让 open editor state 可观测。建议优先修 task430 workspace bootstrap，这同时解除 4-44 和 4-45 的阻塞。

---

## 交叉依赖分析

```text
4-23 ──→ P3 候选，不依赖其他文档
4-27 ──→ 核心 cutover，4-34/4-28 承接其尾项
4-28 ──→ 依赖 4-27 的 restore 命令，React DOM focus 单列为待补
4-34 ──→ Convex 侧依赖 4-27 的命令，local folder 侧为独立待补
4-38 ──→ open target 子项由 4-39/4-42 完成；bulk delete 由 4-41 完成
4-39 ──→ rootUri 子项由 4-42 完成 [已归档]
4-40 ──→ bulk delete 子项由 4-41 完成 [已归档]
4-41 ──→ 独立完成 [已归档]
4-42 ──→ 独立完成 [已归档]
4-43 ──→ 独立完成 [已归档]
4-44 ──→ 依赖 task430 workspace bootstrap（同 4-45 阻塞项）
4-45 ──→ 依赖 task430 workspace bootstrap
```

## 全局风险排序

| 风险 | 文档 | 描述 | 影响 |
|------|------|------|------|
| 🔴 高 | 4-45 | 4 项 checklist 全部未勾选，Worker D 无产出 | open editor lifecycle 状态不可观测 |
| 🔴 高 | 4-34 | local folder 双浏览器 no-refresh 未解决 | 唯一未完成的 dual-browser 缺口 |
| 🟡 中 | 4-44 | 3 个 browser smoke 未通过 | action layer 代码合入但未经验证 |
| 🟡 中 | 4-28 | React DOM focus 无浏览器证据 | location restore 已实现但焦点行为未确认 |
| 🟢 低 | 4-38 | 前端 cutover 代码未完成但已有 4-39/4-41 覆盖 | 信息过期风险，非功能缺口 |
| 🟢 低 | 4-23 | P3 候选，从未进入实现 | 无实际风险 |

---

## 建议归档路径（非执行）

以下仅作为人工决策参考，本次报告**未移动任何文件**：

| 文档 | 建议目标 | 前提条件 |
|------|----------|----------|
| 4-27 | `done/` | 添加引用 4-34/4-28 的头部注释 |
| 4-39 | `done/` | 添加引用 4-42 的头部注释 |
| 4-40 | `done/` | 无 |
| 4-41 | `done/` | 无 |
| 4-42 | `done/` | 无 |
| 4-43 | `done/` | 无 |
| 4-23 | `process/` 保留 | 添加 "P3 Candidate" 头注 |
| 4-28 | `process/` 保留 | React DOM focus smoke 通过后归档 |
| 4-34 | `process/` 保留 | task436 或等价 local folder no-refresh 证据通过后归档 |
| 4-38 | `process/` 保留 | 剩余前端 cutover + UI smoke 通过后归档 |
| 4-44 | `process/` 保留 | 3 个 smoke 全部通过后归档 |
| 4-45 | `process/` 保留 | 所有 4 项 checklist 完成后归档 |

---

## 报告说明

**路径**: `.codex/reasonix-tasks/results/design-governance-worker-b-04-tree.md`

**只读约束**: 本文只创建了报告文件，未移动、修改或删除任何 `design/` 文件。上述归档/移动建议需由人工或后续 Worker 执行。

**验证命令**:
```bash
# 确认报告文件存在
find .codex/reasonix-tasks/results/ -name '*worker-b*'

# 确认未修改任何设计文件
cd /mnt/Data1T/mnote && git diff --stat design/

# 复现 Rust 验收（抽样）
cargo test --manifest-path rust/Cargo.toml -p mnote-web filetree_runtime -- --test-threads=1
cargo test --manifest-path rust/Cargo.toml -p mnote-web tree_command_local_folder -- --test-threads=1

# 检查 smoke 脚本语法
node --check scripts/task430-vscode-explorer-stage7-smoke.js
node --check scripts/task471-local-folder-bulk-resource-trash-smoke.js
```