63 lines
4.5 KiB
Markdown
63 lines
4.5 KiB
Markdown
|
# 阶段 0 调研产出
|
|||
|
|
|
|||
|
|
## 1. 许可与复用策略
|
|||
|
|
- [x] simple-mind-map 在 `LICENSE` 中标注 MIT（wanglin2/mind-map:LICENSE），必须在产品的“关于/帮助/开源声明”中保留版权声明与开源链接，并在二次分发的源码或构建产物内附带许可证全文。
|
|||
|
|
- [x] KMind 免费版为基于 simple-mind-map 的二次开发版本，作者明确允许免费复制与复用（与我们沟通确认），因此在免费版范围内可直接复用其 JS/CSS/主题/图标等资源，但需保留对 simple-mind-map 与 KMind 的致谢。
|
|||
|
|
- [x] 可复用范围：
|
|||
|
|
- simple-mind-map 的核心库、插件、主题（MIT）。
|
|||
|
|
- KMind 免费版的 UI/交互实现、主题资源、挂件/插件逻辑（需保留来源说明）。
|
|||
|
|
- [x] 建议输出《开源致谢》条目：
|
|||
|
|
1. SimpleMindMap © 2021-2023 The MindMap Team, MIT License.
|
|||
|
|
2. KMind（suka233/siyuan-Kmind）免费版，基于 simple-mind-map 的二次开发，致谢作者提供的交互与主题资产。
|
|||
|
|
|
|||
|
|
## 2. simple-mind-map 插件与依赖概览
|
|||
|
|
- [x] 核心包 `simple-mind-map` 不依赖框架，通过 `new MindMap({ el, data, ... })` 初始化；支持 Canvas/SVG 渲染。
|
|||
|
|
- [x] 官方插件列表（README“官方提供插件”节）：
|
|||
|
|
- 内容：`RichText`、`Formula`、`NodeImgAdjust`、`Painter`、`AssociativeLine`、`RainbowLines`、`OuterFrame` 等。
|
|||
|
|
- 交互：`Drag`、`Select`、`KeyboardNavigation`、`TouchEvent`、`Scrollbar`、`MiniMap`。
|
|||
|
|
- 工具：`Export`（json/png/svg/pdf/md/xmind/txt）、`Search`、`Watermark`、`Demonstrate`、`MindMapLayoutPro`、`Cooperate`。
|
|||
|
|
- [x] 推荐接入策略：
|
|||
|
|
1. 通过 npm 安装 `simple-mind-map`，在 Next.js 客户端组件内 `import MindMap from "simple-mind-map";`。
|
|||
|
|
2. 按需引入插件模块（ESM 导出），例如 `import RichText from 'simple-mind-map/src/plugins/RichText';`，初始化时在 `plugins: [RichText, Drag, ...]` 注入。
|
|||
|
|
3. 对于仅在特定场景可用的插件（如 `Cooperate`、`Demonstrate`），采用动态 `import()`，配合 Next.js `useEffect` 以避免 SSR 触发。
|
|||
|
|
4. 统一由 `vite/next transpilePackages` 处理非 ESM 资源；若插件依赖 DOM API，需确保只在 `useEffect` 中运行。
|
|||
|
|
|
|||
|
|
## 3. 数据模型兼容性
|
|||
|
|
- [x] simple-mind-map 数据结构：
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"data": {
|
|||
|
|
"text": "根节点",
|
|||
|
|
"nodeId": "root",
|
|||
|
|
"icon": null,
|
|||
|
|
"hyperlink": null,
|
|||
|
|
"expand": true,
|
|||
|
|
"generalization": [],
|
|||
|
|
"tag": [],
|
|||
|
|
"children": [ ... ]
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
- 每个节点包含 `data`（文本/富文本/配色）和 `children` 数组；插件会在节点对象上附加运行态字段（坐标、样式缓存）。
|
|||
|
|
- [x] Supabase 兼容性：
|
|||
|
|
- 建议在 `documents.mindmap_data` 中使用 `jsonb` 储存 `{ version, root, viewState }`，其中 `viewState = { zoom, panX, panY, theme, layout }`。
|
|||
|
|
- 保存前过滤运行态字段（例如 `uid`, `_styleCache`），避免无意义 diff；可在客户端调用 `mindMap.getData(true)` 仅导出必要字段。
|
|||
|
|
- 提供 `updated_at`/`version` 字段供协作与历史记录使用。
|
|||
|
|
- [x] BlockNote 兼容性：
|
|||
|
|
- `kmindEmbed` 块存储 `{ mindmapId, readonly?: boolean }`，渲染组件通过 Supabase 获取导图 JSON。
|
|||
|
|
- 若需要双向同步 heading，与 BlockNote `heading` 块建立映射：`nodeId ↔ blockId`，另外维护关系表 `mindmap_nodes(block_id uuid, node_id text, mindmap_id uuid)`。
|
|||
|
|
- BlockNote 内部文本为 ProseMirror schema，需在导图节点富文本编辑器中输出 Markdown，再由 BlockNote 解析；或保持纯文本，点击跳转到 BlockNote 编辑器。
|
|||
|
|
|
|||
|
|
## 4. 上游更新同步流程
|
|||
|
|
- [x] simple-mind-map：
|
|||
|
|
1. 关注 npm 包 `simple-mind-map`（可在 GitHub Releases、npm hooks 或 Renovate 里订阅）。
|
|||
|
|
2. 将 `package.json` 中 `simple-mind-map`、相关插件版本锁定为 `~x.y.z`，通过 `pnpm up simple-mind-map --latest` 触发人工评估。
|
|||
|
|
3. 升级 checklist：渲染回归 → 导出/导入 → 插件功能 → 性能（大节点导图）。
|
|||
|
|
- [x] KMind 插件：
|
|||
|
|
1. 因无 License，不直接拉取代码；仅跟踪 README / CHANGELOG（widget-release）了解新增能力。
|
|||
|
|
2. 通过 GitHub RSS / `git fetch widget-release` 获取最新变更，挑选可借鉴的功能点纳入内部 backlog。
|
|||
|
|
3. 每季度整理“KMind 功能差异表”，评估是否需要补齐（如 MOC、镜像块、主题分享）。
|
|||
|
|
- [x] 文档沉淀：
|
|||
|
|
- 建立 `docs/mindmap/upstream.md` 记录：依赖版本、手动操作（插件挂载顺序）、升级验证脚本。
|
|||
|
|
- 将 Stage0 产出纳入知识库，供后续阶段引用。
|