Align resource tabs with workbench review

2026-05-20 19:04:05 +08:00
parent 4c62ea7e35
commit acf1305a7e
14 changed files with 964 additions and 13 deletions
@@ -0,0 +1,52 @@
+# 4-38 File Tree Resource Lifecycle 与 Open Target 收口 Checklist v1
+
+> 状态：process
+>
+> 日期：2026-05-20
+>
+> Owner：File Tree / local_folder executor / resource lifecycle
+
+## 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：
+  - [x] 支持 `local-file:<relativePath>`。
+  - [ ] 保留 `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。
+- [ ] 前端 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。
+- [ ] 浏览器 smoke 覆盖本地文件夹资源行单独删除后垃圾箱可见、恢复回原路径、永久删除清理索引。
+- [ ] 现有 `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` 通过。
+- 未完成：File Tree open target 合同扩展、前端 delete/bulk delete 全面 cutover、浏览器垃圾箱资源行全链 smoke。
+
+## 5. 非目标
+
+- 不做 Convex 云端完整文件系统 parity。
+- 不实现完整 undo/redo。
+- 不实现复杂 paste / drop 二进制上传矩阵。
@@ -0,0 +1,53 @@
+# 5-16 Editor Group 与 Resource Tab 安全收口 Checklist v1
+
+> 状态：process
+>
+> 日期：2026-05-20
+>
+> Owner：`mnote-web` 主编辑区 runtime / resource tab
+
+## 1. 目标
+
+把当前浏览器内存版 resource tab 收口为轻量 editor group 模型的第一阶段：不引入完整 VSCode 多 group，不改变 Page Aggregate 事实源，只解决打开、激活、关闭和脏资源防护的最小闭环。
+
+## 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`
+- 可新增一个聚焦 smoke，例如 `scripts/task460-resource-tab-close-dirty-smoke.js`
+
+## 3. Checklist
+
+- [ ] 定义轻量 `MainEditorTabEntry` / `mainEditorTabRegistry` 语义，至少包含 `id`、`kind`、`title`、`dirty`、`saving`、`hasExternalConflict`、`lastActiveAt`。
+- [x] 保持 page tab 为固定 tab，但 resource tab 激活/关闭应走同一套 registry 状态更新。
+- [x] `closeResourceTab` 关闭前检查 resource session：
+  - [x] `saving=true` 时禁止直接关闭或等待保存完成。
+  - [x] `hasExternalConflict=true` 时禁止静默关闭。
+  - [x] `dirty=true` 时触发保存或确认流程；不得直接释放 session。
+- [x] 关闭 active resource tab 后按 MRU 回到上一个 resource tab；没有可用 resource tab 时才回到 page tab。
+- [x] resource tab 激活时更新稳定 `aria-selected`、`tabindex` 和 panel hidden 状态。
+- [ ] 打开失败时保留 error placeholder tab，允许用户关闭或重试，不要留下半注册状态。
+
+## 4. 验收
+
+- [x] 打开两个 resource tab，切到第二个并关闭后，应回到第一个，而不是无条件回 page tab。
+- [x] 编辑 resource markdown 后立即点关闭，不应静默丢弃未保存内容。
+- [x] 保存中关闭不会释放 editor session。
+- [ ] 打开失败的 resource tab 有明确错误占位，并可关闭。
+- [x] 现有 `task457-main-editor-resource-tab-smoke.js` 继续通过。
+- [x] 新增 close dirty / MRU smoke 通过。
+
+## 4.1 本轮执行记录
+
+- 已合入：resource tab MRU、关闭 guard、`aria-selected` / `tabindex` 同步、关闭后回退到上一个 resource tab。
+- 已新增：`scripts/task460-resource-tab-close-dirty-smoke.js` 覆盖近期本地输入后的关闭阻止。
+- 未完成：正式 `MainEditorTabEntry` 模型、打开失败 placeholder tab。
+
+## 5. 非目标
+
+- 不实现完整 VSCode preview / pinned / sticky / drag reorder。
+- 不实现 tab 持久化恢复。
+- 不改变 secondary pane 布局。
+- 不把 `resourceTabRegistry` 移到后端持久状态。
@@ -0,0 +1,57 @@
+# 5-17 Resource Editor Kind 与 Smoke 矩阵 Checklist v1
+
+> 状态：process
+>
+> 日期：2026-05-20
+>
+> Owner：资源打开 resolver / Office / Markdown/Text/Code/Image/PDF smoke
+
+## 1. 目标
+
+把资源类型识别和打开策略从分散 if/else 收口为轻量 resolver，并补齐当前缺失的类型 smoke。默认目标是主编辑区 resource 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/ssr/styles.rs`
+- `rust/crates/mnote-web/src/routes/onlyoffice.rs`
+- `scripts/task457-main-editor-resource-tab-smoke.js`
+- `scripts/task459-local-markdown-attachment-tab-smoke.js`
+- 可新增 resource kind smoke
+
+## 3. Checklist
+
+- [ ] 定义轻量 resource editor resolver：
+  - [ ] 输入：`name`、`mimeType`、`href`、`assetId`、`rootUri`、`path`、`openTarget`。
+  - [ ] 输出：`editorKind`、`badgeKind`、`defaultOpenMode`、`editable`、`viewerUrl`。
+- [x] `.md` / `.markdown` / `.txt` / 常见 code 文件继续使用 tiptap resource editor。
+- [ ] Office 文件默认在主编辑区 tab 内 iframe 打开，显式新窗口仍可打开。
+- [x] PDF 使用独立 `pdf` badge kind，不再复用 ppt。
+- [x] image 使用 image badge kind 和 img viewer。
+- [x] unknown file 有明确 fallback：下载/新窗口/错误占位，不应无响应。
+- [ ] `active-tab`、`side`、`new-window` 三个 target 在同一 resolver 后执行，不再散落在 attachment capture 与 filetree click 中。
+
+## 4. Smoke 矩阵
+
+- [x] `.md` 上传/文件树点击 -> 主编辑区 tiptap tab，可编辑并写回资源文件。
+- [x] `.txt` -> 主编辑区 tiptap tab，可编辑并写回。
+- [x] `.json` 或 `.ts` -> 主编辑区 tiptap/code-like tab，可编辑并写回。
+- [ ] `.docx` -> 主编辑区 Office iframe，DocumentServer 可回源。
+- [ ] `.pptx` / `.xlsx` -> badge 颜色分别正确。
+- [x] `.pdf` -> 主编辑区 iframe，badge 为 pdf 独立颜色。
+- [x] image -> 主编辑区 img viewer。
+- [x] unknown binary -> 明确 fallback，不破坏 page tab 切换。
+
+## 4.1 本轮执行记录
+
+- 已合入：PDF 独立 badge kind、file fallback badge、resource kind smoke 覆盖 markdown/text/code/image/pdf 与未知类型不破坏 tab 回退。
+- 已验证：`scripts/task461-resource-kind-smoke.js` 与 `uploaded_attachment_rows_use_colored_file_badges` 通过。
+- 未完成：正式 resource editor resolver 抽象、Office DocumentServer 回源修复、`active-tab` / `side` / `new-window` 统一 resolver 后执行。
+
+## 5. 非目标
+
+- 不引入 Monaco / CodeMirror。
+- 不实现云端资源写回。
+- 不重构 OnlyOffice DocumentServer 部署。
+- 不改变 `.md` 资源仍用 tiptap 编辑的产品口径。
@@ -0,0 +1,101 @@
+# 12 Sidex / VSCode Workbench 对照审查 v1
+
+> 状态：process
+>
+> 日期：2026-05-20
+>
+> 范围：`reference-code/sidex-main` 对照 MNote 当前主编辑区、资源 tab、File Tree、资源生命周期和 smoke 覆盖。
+
+## 1. 审查方法
+
+本轮使用 CodeGraph 与只读 subagent 并行审查，优先对照 `/mnt/Data1T/mnote/reference-code/sidex-main`，因为该目录包含较完整的 VSCode workbench 源码。`reference-code/vscode` 当前更像裁剪版快照，只作为辅助证据。
+
+审查按功能切面展开：
+
+- Editor / tab：`EditorService.openEditor`、`EditorGroupModel`、`EditorGroupView`、`MultiEditorTabsControl`、`OpenEditorsView`。
+- Explorer / file actions：`ExplorerService`、`ExplorerView`、`fileActions`、`ResourceFileEdit` / `IBulkEditService`。
+- MNote 对应链路：`mnote-web` 的 `web_shell.rs`、`layout.rs`、`tree.rs`、`local_folder_source.rs`、`resource_trash.rs`、`onlyoffice.rs`、`leptos-tiptap-spike`。
+
+## 2. Sidex / VSCode 可借鉴模型
+
+- Explorer 打开文件不是按 UI 分支散落处理，而是统一交给 `IEditorService.openEditor({ resource, options }, ACTIVE_GROUP / SIDE_GROUP)`。
+- `EditorGroupModel` 是 tab/editor 列表真相层，维护 `editors`、`active`、`preview`、`sticky`、`transient`、MRU 和 selection，并发布 open / close / move / dirty / label 等模型事件。
+- `EditorTitleControl` / `MultiEditorTabsControl` 只是消费模型做渲染、滚动、reveal active、DnD、右键菜单和 tab action，不承载资源事实。
+- `OpenEditorsView` 监听 editor group model，与 active editor、visible editors、dirty/label 状态联动。
+- Explorer 文件生命周期通过 `ResourceFileEdit` + `IBulkEditService` 聚合执行，并处理 dirty working copy、readonly、trash / permanent delete、undo label、cancel 和失败 fallback。
+
+## 3. MNote 当前链路
+
+- 主文档页由 `document_page_shell` 生成，SSR 初始只有固定 page tab、resource tab host 和可选 secondary pane。
+- `resourceTabRegistry` 是浏览器内存 Map，`openResourceInActiveTab` 按 `objectIdentity` 去重并动态创建 tab/panel；关闭时直接 unmount、remove、delete。
+- 文件树点击在 `layout.rs` 中分发：document / markdown 页面走 `navigateToDocument`，asset 触发 `tree.asset.open`；local office 可进 resource tab，Convex office 仍可能新窗口，mindmap 走独立 object shell。
+- local_folder executor 已能处理 Markdown、目录、raw file 的 create / rename / copy / move / delete / restore / purge，但 filetree runtime 的打开目标模型和资源生命周期模型仍未完全对齐。
+- resource lifecycle 仍散在 tree command、resource_trash 兼容 route、layout 内联 JS 多条路径。
+
+## 4. P0 缺口
+
+### P0-1 统一 editor input / editor group / active editor 模型缺失
+
+MNote 当前 page、secondary pane、resource tab、mindmap shell、OnlyOffice 新窗口分别走不同状态链。`resourceTabRegistry` 只存在于页面内存，不能被 Sidebar、Open Editors、快捷键、持久化恢复或 watcher 统一消费。
+
+建议：先实现 MNote 轻量版 `EditorInput` / `EditorGroupState`，只覆盖 active group 内的 page/resource editor，不照搬 VSCode 完整 DI 和多 group grid。
+
+### P0-2 resource tab 关闭缺少 dirty / saving / conflict 防护
+
+`closeResourceTab` 直接释放 view/session 并移除 DOM，但同一文件中已经存在 `session.dirty`、`saving`、`hasExternalConflict` 等状态。关闭脏资源、保存中资源或外部冲突资源需要最小防护。
+
+建议：关闭前先检查 session 状态；脏资源优先触发保存或阻止关闭并给出确认；保存中/冲突状态不能静默释放。
+
+### P0-3 资源打开策略不一致
+
+local office 可进入主编辑区 tab，Convex office 仍可能新窗口；mindmap 总是 object shell；部分非本页 code/text attachment 会 `window.open`。这和“默认主编辑区 tab，显式新窗口例外”的当前目标不一致。
+
+建议：引入统一 `openResourceEditor(input, target)`，把 `active-tab`、`side`、`new-window` 作为显式目标，并把 resource kind 解析集中在 resolver。
+
+### P0-4 File Tree 打开目标与资源生命周期模型不对齐
+
+`filetree_runtime::OpenTarget` 只能表达 document / index / asset / asset-folder，不能完整表达 raw local file、directory、arbitrary resource；但 local_folder executor 已支持 raw file / directory lifecycle。
+
+建议：扩展 open target / resource identity 合同，至少能稳定表达 `local_file`、`directory`、`mindmap`、`table`、`office`、`image` 等资源类型。
+
+### P0-5 resource lifecycle 仍多入口分散
+
+资源删除/恢复/永久删除仍由 tree command、resource_trash route、layout 内联 JS 分流处理。云端 asset、mindmap、table、本地 raw file 的路径不完全统一，容易造成垃圾箱、刷新、tab 状态不同步。
+
+建议：继续推进 `tree.resource.*` cutover，旧 URL 只作为兼容 alias；前端也应逐步走统一 resource command client。
+
+## 5. P1 缺口
+
+- local_folder `move` 丢弃 `sortOrder`，拖拽排序与持久顺序语义不闭环。
+- resource tab active 状态只改 DOM，不同步 URL、sidebar active row、可恢复状态。
+- tab identity 混用 `objectIdentity / assetId / href / resource:file:<rootUri>:<path>`，需要 canonical resource identity。
+- mindmap 仍是独立 object shell，不是 main editor group 内的 editor kind。
+- secondary pane 与 main tab 是两套概念；长期应映射为 side target / side group 语义。
+- delete 缺少 dirty / readonly / undo / fallback 统一动作层。
+- paste / right-click paste 目标模型不完整；外部 drop 对二进制文件支持不足。
+- smoke 偏“资源存在 / 不闪烁”，缺少 editor workbench 语义断言。
+
+## 6. P2 缺口
+
+- tab strip 缺少键盘 roving tabindex、左右切换、关闭快捷键、MRU 回退。
+- tab overflow / reveal active / multi-row / context menu / close others 等能力较弱。
+- `.txt` / `.json` / `.ts` / PDF / image 等类型 smoke 矩阵不完整。
+- PDF badge 当前与 ppt 复用，资源类型与显示颜色语义应拆开。
+- File Tree 上下文菜单仍有英文和禁用项暴露实现缺口。
+- trash modal 与 resource command 仍是并行入口，需要继续收口到统一资源生命周期视图。
+
+## 7. 不建议照搬
+
+- 不照搬 Sidex / VSCode 的 DI service 容器。
+- 不照搬完整多 editor group grid；MNote 当前只需要 active tab + side target 的轻量模型。
+- 不照搬 Monaco / TextModel 作为 Markdown 文档事实源；MNote 主编辑仍是 tiptap / Page Aggregate / local Markdown。
+- 不照搬 Extension Host、ContextKey 全体系和完整 UndoRedoSource。
+- 不把参考项目 UI 层状态当成 MNote 的新事实源；MNote 的树、资源归属、生命周期仍以 Rust kernel / local-first 合同为准。
+
+## 8. 执行拆分
+
+本 review 拆分为三份执行 checklist：
+
+- `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`