mnote/design/mindYZ-stage0.md

阶段 0 调研产出

1. 许可与复用策略

• simple-mind-map 在 LICENSE 中标注 MIT（wanglin2/mind-map:LICENSE），必须在产品的“关于/帮助/开源声明”中保留版权声明与开源链接，并在二次分发的源码或构建产物内附带许可证全文。
• KMind 免费版为基于 simple-mind-map 的二次开发版本，作者明确允许免费复制与复用（与我们沟通确认），因此在免费版范围内可直接复用其 JS/CSS/主题/图标等资源，但需保留对 simple-mind-map 与 KMind 的致谢。
• 可复用范围：
  • simple-mind-map 的核心库、插件、主题（MIT）。
  • KMind 免费版的 UI/交互实现、主题资源、挂件/插件逻辑（需保留来源说明）。
• 建议输出《开源致谢》条目：
  1. SimpleMindMap © 2021-2023 The MindMap Team, MIT License.
  2. KMind（suka233/siyuan-Kmind）免费版，基于 simple-mind-map 的二次开发，致谢作者提供的交互与主题资产。

2. simple-mind-map 插件与依赖概览

• 核心包 simple-mind-map 不依赖框架，通过 new MindMap({ el, data, ... }) 初始化；支持 Canvas/SVG 渲染。
• 官方插件列表（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。
• 推荐接入策略：
  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. 数据模型兼容性

• simple-mind-map 数据结构：

  {
    "data": {
      "text": "根节点",
      "nodeId": "root",
      "icon": null,
      "hyperlink": null,
      "expand": true,
      "generalization": [],
      "tag": [],
      "children": [ ... ]
    }
  }
  

  • 每个节点包含 data（文本/富文本/配色）和 children 数组；插件会在节点对象上附加运行态字段（坐标、样式缓存）。
• Supabase 兼容性：
  • 建议在 documents.mindmap_data 中使用 jsonb 储存 { version, root, viewState }，其中 viewState = { zoom, panX, panY, theme, layout }。
  • 保存前过滤运行态字段（例如 uid, _styleCache），避免无意义 diff；可在客户端调用 mindMap.getData(true) 仅导出必要字段。
  • 提供 updated_at/version 字段供协作与历史记录使用。
• 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. 上游更新同步流程

• 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：渲染回归 → 导出/导入 → 插件功能 → 性能（大节点导图）。
• KMind 插件：
  1. 因无 License，不直接拉取代码；仅跟踪 README / CHANGELOG（widget-release）了解新增能力。
  2. 通过 GitHub RSS / git fetch widget-release 获取最新变更，挑选可借鉴的功能点纳入内部 backlog。
  3. 每季度整理“KMind 功能差异表”，评估是否需要补齐（如 MOC、镜像块、主题分享）。
• 文档沉淀：
  • 建立 docs/mindmap/upstream.md 记录：依赖版本、手动操作（插件挂载顺序）、升级验证脚本。
  • 将 Stage0 产出纳入知识库，供后续阶段引用。