108 lines
6.6 KiB
Markdown
108 lines
6.6 KiB
Markdown
|
# Office local-first 预览、编辑与插件噪音缺口审查 v1
|
|||
|
|
|
|||
|
|
## 背景
|
|||
|
|
|
|||
|
|
本轮只审查 OnlyOffice 与 MNote local-first 工作区之间的三个接口缺口：
|
|||
|
|
|
|||
|
|
1. `/api/media/sign` 对 local-folder asset 返回 404。
|
|||
|
|
2. Office 附件默认只读，但需要三点菜单提供“使用编辑模式打开”。
|
|||
|
|
3. OnlyOffice 自定义 annotation 插件存在 404 / pageerror 噪音。
|
|||
|
|
|
|||
|
|
上一轮浏览器验证已经确认：中文 docx 上传后可在 resource tab 中只读打开，`errorCode=-18` 的 WebSocket 连接问题已通过 doc key 安全化和 `/onlyoffice-server` 反代修复。因此本轮不把“只读预览可见”重新定义为失败。
|
|||
|
|
|
|||
|
|
## 官方依据
|
|||
|
|
|
|||
|
|
Context7 查询 `/onlyoffice/api.onlyoffice.com` 得到的关键口径：
|
|||
|
|
|
|||
|
|
- `editorConfig.mode` 支持 `"view"` / `"edit"`，只是初始化编辑器模式。
|
|||
|
|
- 保存必须配置 `editorConfig.callbackUrl`，后端在 callback `status === 2` 或 `status === 6` 时下载 `body.url` 并写回文件，成功返回 `{ "error": 0 }`。
|
|||
|
|
- `onRequestEditRights` 是 view 模式切 edit 的官方事件；触发后集成方必须以 edit mode 重新初始化编辑器。
|
|||
|
|
- 插件通过 `editorConfig.plugins.autostart` 和 `editorConfig.plugins.pluginsData` 连接；annotation / custom assistant 类插件 404 属于可选插件加载链路，不等于主文档渲染失败。
|
|||
|
|
|
|||
|
|
## 代码现状
|
|||
|
|
|
|||
|
|
- `rust/crates/mnote-web/src/routes/media.rs` 的 `/api/media/sign` 当前只服务 Convex media asset，内部查询 `mediaAssets:getById` / `mediaAssets:refreshUrl`。local-folder asset 形如 `local:asset:<path>`，不在 Convex media 表中，所以返回 404 是现状契约不匹配。
|
|||
|
|
- `rust/crates/mnote-web/src/routes/onlyoffice.rs` 的 `/onlyoffice` 页面在 `resolveAssetUrlAndKey()` 中只要有 `assetId` 就请求 `/api/media/sign`；失败后静默保留传入的 `fileUrl`。这就是“当前 view 模式不阻断打开”的原因。
|
|||
|
|
- local-folder Office 预览已经可以直接使用 `/api/local-folder/files/open?rootUri=...&path=...` 作为 `fileUrl`，不需要经过 `/api/media/sign`。
|
|||
|
|
- `/api/onlyoffice/callback` 当前仍代理 legacy Next writeback。对 local-folder 的 `status 2/6 -> 下载 body.url -> 原文件覆盖写回 -> watcher 同步` 没有完整闭环。
|
|||
|
|
- `layout.rs` 中正文附件菜单已有 `new-window`，但没有“使用编辑模式打开”。部分路径当前会默认生成 `mode=edit`，这与“默认只读、显式编辑”的产品口径不一致。
|
|||
|
|
- annotation 插件 404 / pageerror 暂未证明会影响文档渲染；当前更像是 OnlyOffice 静态插件包或自定义插件配置缺失导致的 console 噪音。
|
|||
|
|
|
|||
|
|
## 根因判断
|
|||
|
|
|
|||
|
|
### 1. `/api/media/sign` local-folder 404
|
|||
|
|
|
|||
|
|
根因不是权限失效，而是端点 ownership 错位：`/api/media/sign` 是历史 Convex media asset 签名端点，local-folder 文件已经有 local open route，二者不应混用。
|
|||
|
|
|
|||
|
|
P0 目标不是让 `/api/media/sign` 接管所有本地文件，而是让 OnlyOffice local 路径不再无意义请求该端点，避免误导日志和后续测试。
|
|||
|
|
|
|||
|
|
### 2. 编辑模式入口
|
|||
|
|
|
|||
|
|
OnlyOffice `mode=edit` 并不等于 MNote 已支持保存。没有 callback 写回闭环时，直接默认编辑会制造“看似能改、实际不能保存”的假功能。
|
|||
|
|
|
|||
|
|
P0 目标：
|
|||
|
|
|
|||
|
|
- 默认打开仍为 `view`。
|
|||
|
|
- 菜单提供“使用编辑模式打开”入口。
|
|||
|
|
- 编辑入口必须带 guard：清楚标记为实验能力，或在 local-folder writeback 未闭环时阻止/提示。
|
|||
|
|
|
|||
|
|
P1 目标才是实现 local-folder callback 写回。
|
|||
|
|
|
|||
|
|
### 3. annotation 插件 404 / pageerror
|
|||
|
|
|
|||
|
|
插件链路属于可选增强。若配置了 autostart / pluginsData 但静态资源不存在，会产生 404 或 pageerror。只要正文渲染和 OnlyOffice 主 WebSocket 正常，这不是打开失败。
|
|||
|
|
|
|||
|
|
P0 目标：
|
|||
|
|
|
|||
|
|
- 不把可选插件 404 当成 Office 打开失败。
|
|||
|
|
- 不让缺失插件反复污染测试结论。
|
|||
|
|
- 若当前 MNote 并未真正依赖 annotation 插件，则应禁用 autostart 或明确过滤为 non-critical。
|
|||
|
|
|
|||
|
|
## Checklist 拆分
|
|||
|
|
|
|||
|
|
- `5-34-local-folder-media-sign-office-url-contract-v1.md`
|
|||
|
|
- P0：OnlyOffice local-folder 打开不再请求 `/api/media/sign`。
|
|||
|
|
- P1：补回归测试，确认 local asset 仍可只读打开。
|
|||
|
|
|
|||
|
|
- `5-35-office-edit-mode-menu-and-guard-v1.md`
|
|||
|
|
- P0：正文附件与文件树资源菜单增加“使用编辑模式打开”。
|
|||
|
|
- P0：默认打开保持只读。
|
|||
|
|
- P0：若保存闭环未完成，编辑入口必须有 guard / 实验标记。
|
|||
|
|
|
|||
|
|
- `5-36-onlyoffice-local-edit-save-callback-contract-v1.md`
|
|||
|
|
- P1：设计或实现 local-folder callback 写回。
|
|||
|
|
- P1：覆盖 status 2/6、下载 URL rewrite、路径权限、冲突保护。
|
|||
|
|
|
|||
|
|
- `5-37-onlyoffice-annotation-plugin-noise-policy-v1.md`
|
|||
|
|
- P0：定位 annotation 404 来源。
|
|||
|
|
- P0：禁用无效 autostart / pluginsData 或把该类错误降级为 non-critical 测试噪音。
|
|||
|
|
|
|||
|
|
## 不做事项
|
|||
|
|
|
|||
|
|
- 不默认以 edit 模式打开 Office。
|
|||
|
|
- 不在没有保存闭环时承诺“Office 可编辑保存”。
|
|||
|
|
- 不把 local-folder 文件任意暴露给 `/api/media/sign`，除非经过 rootUri / workspace / allowed roots 校验。
|
|||
|
|
- 不把 annotation 插件 404 等同于主文档渲染失败。
|
|||
|
|
|
|||
|
|
## 验收要求
|
|||
|
|
|
|||
|
|
- `cargo test -p mnote-web -- --test-threads=1`
|
|||
|
|
- `codegraph sync .` 后确认索引健康。
|
|||
|
|
- Reasonix clean browser 测试：全新 browser context，登录测试账号，上传 `/home/lix/Downloads/重庆发展特殊化妆品可行性报告_政府汇报版.docx`，打开默认只读，截图确认内容可见；打开三点菜单确认编辑入口；点击编辑入口后截图和日志证明行为符合 guard / edit URL 预期。
|
|||
|
|
- Codex 必须复核 Reasonix 的 `result.json` 和截图，再自行做一次浏览器截图核查。
|
|||
|
|
|
|||
|
|
## 当前执行结论
|
|||
|
|
|
|||
|
|
- P0 已处理：
|
|||
|
|
- local-folder Office 打开跳过 `/api/media/sign`，继续使用 `/api/local-folder/files/open`。
|
|||
|
|
- Office 默认打开为 `mode=view`。
|
|||
|
|
- 菜单提供“使用编辑模式打开”，进入前有实验 guard。
|
|||
|
|
- 已存在 Office resource tab 从 view 切 edit 会刷新同一 iframe URL，不再只激活旧 tab。
|
|||
|
|
- annotation/custom assistant 插件 404 已归类为 non-critical noise，不作为主文档打开失败。
|
|||
|
|
- P1 仍保留：
|
|||
|
|
- local-folder Office edit/save callback 写回闭环未实现，编辑模式仍不能承诺保存到原文件。
|
|||
|
|
- `onRequestEditRights` 事件重新初始化 edit URL 未实现。
|
|||
|
|
- 浏览器证据：
|
|||
|
|
- Reasonix：`tmp/reasonix-office-view-edit-plugin-2026-05-21/result.json` 与截图。
|
|||
|
|
- Codex：`tmp/codex-office-view-edit-plugin-2026-05-21/result.json`、`01-office-view-mode.png`、`02-office-edit-mode.png`。
|