Complete workbench P0 resource tab cutover

2026-05-20 20:13:24 +08:00
parent acf1305a7e
commit e0b0e70fb8
12 changed files with 1159 additions and 3 deletions
@@ -0,0 +1,54 @@
+# 4-39 FileTree Open Target 与 Resource Identity Checklist v1
+
+> 状态：process
+>
+> 日期：2026-05-20
+>
+> Owner：File Tree runtime / open target 合同
+
+## 1. 目标
+
+补齐 P0-4：扩展 `FileTreeOpenTarget` 和 runtime API，使 File Tree 能稳定表达 local raw file、directory、asset folder、office/image/pdf/code/mindmap/table 等资源身份，而不是只靠 UI 侧字符串分流。
+
+## 2. 允许修改范围
+
+- `rust/crates/mnote-web/src/tree_shell/filetree_runtime.rs`
+- `rust/crates/mnote-web/src/tree_shell/runtime_api.rs`
+- `rust/crates/mnote-web/src/routes/tree.rs`
+- `rust/crates/mnote-web/src/routes/local_folder_source.rs`
+- 相关 Rust 单测
+
+## 3. 禁止事项
+
+- 不改前端打开 UI 大流程；只输出更稳定的 open target / intent 合同。
+- 不做 resource lifecycle delete/restore/purge cutover；该项由 4-40 处理。
+- 不引入新的树真相层，Resource Tree / File Tree / Page Tree 口径保持不变。
+
+## 4. Checklist
+
+- [x] 扩展 `FileTreeOpenTarget` 或新增字段，能表达 `local_file`、`directory`、`asset_folder`、`office`、`image`、`pdf`、`code/text`、`mindmap`、`table`。
+- [x] open target 包含 canonical resource identity、resource kind、relative path、document id / parent id（若有）。
+- [x] `parse_open_target_from_row` 支持现有 row dataset，不破坏 document/index/asset-folder/asset。
+- [x] runtime API 序列化保持 camelCase，旧字段兼容。
+- [x] Rust 单测覆盖 local raw file、directory、office/image/pdf/code/mindmap/table open target。
+
+## 5. 验收
+
+- [x] `cargo test -p mnote-web filetree_runtime -- --test-threads=1`
+- [x] `cargo test -p mnote-web runtime_api -- --test-threads=1`
+- [x] `cargo test -p mnote-web tree_shell_filetree_mode_embeds_asset_state -- --test-threads=1`
+
+## 6. 本轮执行记录
+
+- 已完成：
+  - `FileTreeOpenTarget::Asset` 已补可选 `resourceKind`，并新增 `LocalFile` / `Directory` variant。
+  - `resolve_open_target` 支持 `local-file` / `directory` / `office` / `image` / `pdf` / `code` / `text` / `mindmap` / `table` row kind。
+  - 新增序列化合同测试，覆盖 resource kind、local file 中文路径、directory。
+- 未完成：
+  - 后续仍需把更多上游 row dataset 补齐真实 `rootUri`，当前 `LocalFile` / `Directory` variant 的 rootUri 仍为空字符串占位。
+- 风险：`FileTreeOpenTarget` schema 已扩展，需保留旧 `Asset` JSON 兼容；当前 `resourceKind=None` 时不序列化。
+
+## 7. 非目标
+
+- 不改变资源实际打开方式。
+- 不处理 OnlyOffice 回源。
@@ -0,0 +1,60 @@
+# 4-40 Resource Lifecycle Command Cutover 与垃圾箱 Smoke Checklist v1
+
+> 状态：process
+>
+> 日期：2026-05-20
+>
+> Owner：resource lifecycle / tree.resource.* / local trash smoke
+
+## 1. 目标
+
+补齐 P0-5：前端本地资源删除、恢复、永久删除优先走 `/api/tree/commands` 的 `tree.resource.*` 语义，并用浏览器 smoke 覆盖“资源行删除 -> 垃圾箱可见 -> 恢复 -> purge”的全链路。
+
+## 2. 允许修改范围
+
+- `rust/crates/mnote-web/src/ssr/pages/layout.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/routes/gateway.rs`
+- `scripts/task437-local-folder-asset-trash-lifecycle-smoke.js`
+- 可新增聚焦 smoke
+
+## 3. 禁止事项
+
+- 不删除旧兼容 resource_trash route；只让新主路径优先 tree command。
+- 不改变云端 Convex resource lifecycle 语义。
+- 不实现 undo/redo。
+
+## 4. Checklist
+
+- [ ] 前端 local resource delete/bulk delete 优先调用 `/api/tree/commands` archive/purge/restore。
+- [x] 旧 `/api/mindmap`、`/api/media`、`/api/tables` lifecycle route 保留为兼容 fallback。
+- [x] tree command response 保留 `canonicalCommand` / artifact / trash index 信息，前端可刷新对应行。
+- [x] 垃圾箱页面或 modal 能显示 local resource trash entry，并支持 restore/purge。
+- [x] 新增浏览器 smoke：本地文件夹页面上传或创建资源，单独删除资源，垃圾箱可见，恢复回原路径，再永久删除清理索引。
+- [x] smoke 隔离 tmp root，不复用历史云 workspace。
+
+## 5. 验收
+
+- [x] `node --check scripts/task437-local-folder-asset-trash-lifecycle-smoke.js`
+- [x] `node scripts/task437-local-folder-asset-trash-lifecycle-smoke.js`
+- [x] 新增 resource trash browser smoke 通过。
+- [x] `cargo test -p mnote-web resource_trash -- --test-threads=1`
+- [x] `cargo test -p mnote-web tree_command_local_folder -- --test-threads=1`
+
+## 6. 本轮执行记录
+
+- 已完成：
+  - `/api/tree/commands` 支持 local resource archive / restore / purge，并返回 `tree.resource.*` canonical command。
+  - local trash workbench 已从 `trash-index.json` 渲染 resource row，并通过 `/api/tree/commands` restore / purge。
+  - `scripts/task437-local-folder-asset-trash-lifecycle-smoke.js` 覆盖 API 级 delete / restore / purge。
+  - 新增 `scripts/task464-local-folder-resource-trash-ui-smoke.js`，覆盖真实垃圾箱页面 resource row 可见、UI 恢复、UI 彻底删除和索引清理。
+- 未完成：
+  - 前端 bulk delete 场景尚未覆盖 tree command。
+- 风险：无
+
+## 7. 非目标
+
+- 不做完整 trash undo。
+- 不做 Convex 云端 parity。
@@ -0,0 +1,60 @@
+# 5-18 Main Editor Tab State 与错误占位 Checklist v1
+
+> 状态：process
+>
+> 日期：2026-05-20
+>
+> Owner：主编辑区 tab runtime / `web_shell.rs`
+
+## 1. 目标
+
+补齐 P0-1 的最小轻量 editor group 状态：在不引入完整 VSCode 多 group 的前提下，让 page/resource tab 共享一个明确的浏览器内存状态模型，并补上 resource 打开失败时的错误占位 tab。
+
+## 2. 允许修改范围
+
+- `rust/crates/mnote-web/src/routes/web_shell.rs`
+- `rust/crates/mnote-web/src/ssr/pages/document.rs`
+- `rust/crates/mnote-web/src/ssr/styles.rs`
+- `scripts/task457-main-editor-resource-tab-smoke.js`
+- 可新增 `scripts/task462-resource-tab-error-placeholder-smoke.js`
+
+## 3. 禁止事项
+
+- 不引入完整 VSCode DI、多 editor group grid、preview/sticky 持久化。
+- 不改变 Page Aggregate 或 local Markdown 事实源。
+- 不修改 resource resolver、OnlyOffice、File Tree lifecycle；这些由其它 checklist 处理。
+
+## 4. Checklist
+
+- [x] 定义轻量 main editor tab 状态，至少能表达 `id`、`kind`、`title`、`dirty`、`saving`、`hasExternalConflict`、`lastActiveAt`、`status`。
+- [x] page tab 与 resource tab 激活统一通过同一状态更新入口。
+- [x] resource tab close guard 读取同一状态入口，避免散落检查。
+- [x] 打开 resource 失败时创建或保留 error placeholder tab。
+- [x] error placeholder tab 有明确错误 UI，可关闭，不留下半注册 panel/session。
+- [x] 更新 Rust 字符串 contract test，确保关键 runtime marker 存在。
+
+## 5. 验收
+
+- [x] `node --check scripts/task462-resource-tab-error-placeholder-smoke.js`
+- [x] `node scripts/task462-resource-tab-error-placeholder-smoke.js`
+- [x] `node scripts/task457-main-editor-resource-tab-smoke.js`
+- [x] `cargo test -p mnote-web web_shell -- --test-threads=1`
+
+## 6. 本轮执行记录
+
+- 已完成：
+  - `createResourceSession` 已补 `lastActiveAt`，resource session 继续持有 `dirty` / `saving` / `hasExternalConflict` / `status` 等关闭保护状态。
+  - page tab 与 resource tab 继续统一通过 `activateMainEditorTab` 激活，并在激活 resource tab 时更新 MRU 与 `lastActiveAt`。
+  - `closeResourceTab` 继续通过 `resourceTabCloseGuardReason` 读取关闭保护状态。
+  - `openResourceInActiveTab` 失败时保留 resource tab，并通过 `.mnote-resource-tab-error` 渲染可见错误占位。
+  - 新增 `scripts/task462-resource-tab-error-placeholder-smoke.js`，已验证失败资源会出现错误占位、可关闭、连续失败不会产生失控 tab。
+  - `web_shell.rs` 与 `styles.rs` 已补关键 runtime / CSS contract。
+- 未完成：
+  - `lastActiveAt` 时间戳尚未用于 tab 排序（当前 MRU 队列 `resourceTabMru` 控制切换顺序）。
+  - `dirty`/`saving`/`hasExternalConflict` 状态在 resource tab close guard 中读出但无 UI 确认弹窗（仅 console.warn + 禁止关闭）。
+- 风险：无
+
+## 7. 非目标
+
+- 不做 tab 持久化恢复。
+- 不做 tab 拖拽排序、context menu 或 close others。
@@ -0,0 +1,62 @@
+# 5-19 Resource Open Resolver 与 OnlyOffice 回源 Checklist v1
+
+> 状态：process
+>
+> 日期：2026-05-20
+>
+> Owner：资源打开 resolver / attachment capture / OnlyOffice URL 配置
+
+## 1. 目标
+
+补齐 P0-3：把资源类型识别、badge、默认打开目标、显式 `active-tab / side / new-window` 目标收口到轻量 resolver，并优先修复本地上传 `.docx` 在主编辑区 tab 内无法回源的问题。
+
+## 2. 允许修改范围
+
+- `rust/crates/mnote-web/src/routes/web_shell.rs`
+- `rust/crates/mnote-web/src/ssr/pages/layout.rs`
+- `rust/crates/mnote-web/src/routes/onlyoffice.rs`
+- `rust/crates/mnote-web/src/ssr/styles.rs`
+- `scripts/task457-main-editor-resource-tab-smoke.js`
+- `scripts/task461-resource-kind-smoke.js`
+- 可新增 OnlyOffice/resolver smoke
+
+## 3. 禁止事项
+
+- 不引入 Monaco / CodeMirror。
+- 不重构 OnlyOffice DocumentServer 部署。
+- 不改变 `.md` / `.txt` / code 资源继续用 tiptap resource editor 的口径。
+- 不处理 File Tree open target 合同；该项由 4-39 处理。
+
+## 4. Checklist
+
+- [x] 定义轻量 resource open resolver，输入包含 `name/mimeType/href/assetId/rootUri/path/openTarget`。
+- [x] resolver 输出 `editorKind/badgeKind/defaultOpenMode/editable/viewerUrl` 或等价结构。
+- [x] `tree.asset.open`、attachment click capture、显式 new-window 复用同一 resolver 判断。
+- [x] 默认打开目标为主编辑区 `active-tab`；`new-window` 显式保留；`side` 不回归。
+- [x] `.docx/.pptx/.xlsx` 默认进入主编辑区 Office iframe，显式 new-window 打开 `/onlyoffice`。
+- [x] OnlyOffice iframe 的 document URL 对 local-folder 文件使用 Rust 可访问的 `/api/local-folder/files/open` 或 `/api/onlyoffice/proxy` 回源 URL，避免 DocumentServer 访问浏览器不可达 URL。
+- [x] 如果本机 DocumentServer 不可用，smoke 至少断言 iframe config URL / document URL / callback URL 正确，不把外部服务不可用误判为 resolver 失败。
+
+## 5. 验收
+
+- [x] `node --check scripts/task457-main-editor-resource-tab-smoke.js && node --check scripts/task461-resource-kind-smoke.js`
+- [x] `node scripts/task457-main-editor-resource-tab-smoke.js`
+- [x] `node scripts/task461-resource-kind-smoke.js`
+- [x] 新增或更新 Office smoke，覆盖 `.docx` 主编辑区 tab iframe 与显式 new-window。
+- [x] `cargo test -p mnote-web onlyoffice -- --test-threads=1`
+
+## 6. 本轮执行记录
+
+- 已完成：
+  - `resolveResourceOpen` 已集中输出 `editorKind` / `badgeKind` / `defaultOpenMode` / `editable` / `viewerUrl` / `openTarget`。
+  - 本地 Office 资源默认进入主编辑区 iframe，显式 `new-window` 仍打开 `/onlyoffice`。
+  - `buildOnlyOfficeOpenUrl` 会把相对 `fileUrl` 绝对化，local-folder Office iframe 携带 `http://127.0.0.1:3000/api/local-folder/files/open?...` 这类 Rust 可访问回源 URL。
+  - 新增 `scripts/task463-onlyoffice-resolver-smoke.js`，已覆盖 `.docx/.pptx/.xlsx` badge、主编辑区 iframe、显式 new-window、OnlyOffice 页面脚本结构。
+- 未完成：
+  - 未验证真实外部 DocumentServer 协同编辑会话，只验证 MNote 侧 URL / iframe / proxy / callback 配置。
+- 风险：无
+
+## 7. 非目标
+
+- 不修复外部 DocumentServer 服务部署本身。
+- 不实现云端资源写回。
@@ -99,3 +99,10 @@ local office 可进入主编辑区 tab，Convex office 仍可能新窗口；mind
 - `design/05-editor-mainline/process/5-16-editor-group-resource-tab-safety-checklist-v1.md`
 - `design/04-tree-domain/process/4-38-filetree-resource-lifecycle-open-target-checklist-v1.md`
 - `design/05-editor-mainline/process/5-17-resource-editor-kind-and-smoke-matrix-checklist-v1.md`
+
+第二轮 P0 收口继续拆为四份独立 checklist：
+
+- `design/05-editor-mainline/process/5-18-main-editor-tab-state-and-error-placeholder-checklist-v1.md`
+- `design/05-editor-mainline/process/5-19-resource-open-resolver-and-onlyoffice-checklist-v1.md`
+- `design/04-tree-domain/process/4-39-filetree-open-target-resource-identity-checklist-v1.md`
+- `design/04-tree-domain/process/4-40-resource-lifecycle-command-cutover-smoke-checklist-v1.md`