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` 继续作为后置实现项，而不是本阶段直接迁入主线。