mnote/design/old/08-legacy-rust-kernel/done/mindmap-onlyoffice-boundary.md

[recycle] Mindmap 与 OnlyOffice 当前边界说明

更新时间：2026-04-14

主仓：/mnt/Data1T/mnote

1. Mindmap 当前主链

1.1 主组件与嵌入链路

• 主组件：/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocks/MindmapBlock.tsx
• BlockNote 注册入口：/mnt/Data1T/mnote/wolai-frontend/src/components/editor/schema.ts
• 独立全屏页：/mnt/Data1T/mnote/wolai-frontend/src/app/mindmap/[docId]/[mindmapId]/page.tsx

当前事实：

• MindmapBlockView 同时服务文档内嵌块与独立全屏页。
• 独立页通过 editorStub 复用同一组件，不额外复制第二套思维导图主壳。
• 文档内嵌与独立页共用同一套工具栏、侧栏、导航器、缩略图与上下文菜单子组件。

1.2 数据入口与 ops 边界

• 本地读写入口：/mnt/Data1T/mnote/wolai-frontend/src/lib/mindmap/mindmapLocalStore.ts
• 节点操作入口：/mnt/Data1T/mnote/wolai-frontend/src/lib/mindmap/mindmapOps.ts
• 页面 API：
  • /mnt/Data1T/mnote/wolai-frontend/src/app/api/mindmap/[docId]/route.ts
  • /mnt/Data1T/mnote/wolai-frontend/src/app/api/mindmap/[docId]/[mindmapId]/route.ts

当前拆分：

• 前端交互状态保留在 MindmapBlock.tsx 及其子组件内。
• 本体数据读写由 mindmapLocalStore.ts 提供本地文件落盘兼容接口。
• 节点增删改、引用、注释、链接等操作由 mindmapOps.ts 统一描述为 MindmapOp。
• 页面 API 当前通过 Convex api.mindmaps.* 承接 get/put/restore/purge，保留现有前端形态不变。
• 当前 Mindmap API 已补统一元信息口径：
  • pageId = documentId
  • attachmentId = mindmapId
  • workspaceId 统一来自页面归属工作区
  • requestId/traceId 统一从请求头透传或在路由侧兜底生成

1.3 后续 adapter 目标

后续若进入 Rust adapter，只抽象以下边界，不复制历史仓 UI：

• 节点树结构
• 节点引用 refs
• 节点操作日志 MindmapOp
• mindmap 与 page/block 的绑定关系

2. OnlyOffice 当前主链

2.1 页面与 API 边界

• 页面入口：
  • /mnt/Data1T/mnote/wolai-frontend/src/app/onlyoffice/page.tsx
  • /mnt/Data1T/mnote/wolai-frontend/src/app/onlyoffice/OnlyOfficeClientPage.tsx
• 页面侧面板：
  • /mnt/Data1T/mnote/wolai-frontend/src/components/onlyoffice/OnlyOfficeAiAgentPanel.tsx
• API 边界：
  • /mnt/Data1T/mnote/wolai-frontend/src/app/api/onlyoffice/sign/route.ts
  • /mnt/Data1T/mnote/wolai-frontend/src/app/api/onlyoffice/proxy/route.ts
  • /mnt/Data1T/mnote/wolai-frontend/src/app/api/onlyoffice/callback/route.ts
  • /mnt/Data1T/mnote/wolai-frontend/src/app/api/onlyoffice/forcesave/route.ts

当前拆分：

• page.tsx 负责页面级早期 DOM 补丁与容器加载。
• OnlyOfficeClientPage.tsx 负责编辑器初始化、内部请求改写、代理地址适配与 callback URL 组装。
• sign 负责 JWT 签名。
• proxy 负责同源代理与回源 URL 安全限制。
• callback 负责保存回写存储。
• forcesave 负责触发文档服务器强制保存。

2.2 与正文和附件的关系

• Office 文件入口仍来自 MediaBlock：/mnt/Data1T/mnote/wolai-frontend/src/components/editor/blocks/MediaBlock.tsx
• 正文里只保留附件块与跳转入口，不在 BlockNote 内直接运行 OnlyOffice 编辑器。
• OnlyOffice 编辑器继续在独立 /onlyoffice 页面运行。
• 当前 OnlyOffice 已稳定使用：
  • documentId 作为页面业务标识
  • assetId 作为附件业务标识
  • 页面归属仍由文档/附件在 Convex 中的 workspace_id 与 document_id 决定

2.5 与 Mindmap 对齐后的共享标识口径

• 页面标识：
  • Mindmap 使用 pageId/documentId
  • OnlyOffice 使用 documentId
• 附件标识：
  • Mindmap 使用 attachmentId/mindmapId
  • OnlyOffice 使用 assetId
• 页面归属：
  • 两者都以 Convex 中的 workspace_id + document_id 作为最终归属真相
• 追踪字段：
  • Mindmap API 已返回 requestId/traceId
  • OnlyOffice 页面当前通过查询参数与调试上下文持有 assetId/documentId/userId，后续若接入统一 Rust adapter，继续沿用同一页面/附件口径

2.3 静态资源边界

• 根目录静态资源保留在 /mnt/Data1T/mnote/src/components/onlyoffice/
• 当前已确认存在：
  • onlyoffice-web-apps/
  • onlyoffice-plugins/
  • onlyoffice-data/

这些目录继续保留为运行所需静态资源、插件和数据目录，不做迁移式替换。

2.4 后续 adapter 目标

后续若进入 Rust adapter，只抽象以下边界：

• 对象解析与附件定位
• 签名生成
• callback 写回
• forcesave 触发
• 代理回源请求

3. 历史仓禁止误复制范围

以下历史仓路径只作为参考，不进入主仓主线：

• /mnt/Data1T/mnote-rust/app/documents/[id]/mindmap/page.tsx
• /mnt/Data1T/mnote-rust/app/documents/[id]/office/page.tsx
• /mnt/Data1T/mnote-rust/components/sidebar/sidebar.tsx
• /mnt/Data1T/mnote-rust/app/page.tsx
• /mnt/Data1T/mnote-rust/app/onlyoffice/page.tsx

约束：

• 不复制第二套对象页壳。
• 不复制第二套 sidebar 壳。
• adapter-onlyoffice、adapter-mindmap 继续作为后置实现项，而不是本阶段直接迁入主线。