docs(v0.13.8): 知识体系画布设计规格（React Flow 节点画布）

Author: Aparencia

docs/superpowers/specs/2026-08-24-v0.13.8-knowledge-canvas-design.md

@@ -0,0 +1,282 @@
+# v0.13.8 设计规格：知识体系画布（React Flow 节点式无限画布）
+
+> 状态：**已批准**（2026-08-24，用户裁决方案2——React Flow 标注画布）
+> 关联：[v0.13 系列文档](../../versions/v0.13.md) · [ADR-024](../../adr/ADR-024-knowledge-system-layer.md) · [v0.13.7 上手路径](../../archive/2026-08-24/2026-08-24-v0.13.7-knowledge-system-onboarding-design.md)（[ ] 已归档）
+> 范围：v0.13.8——知识体系画布视图。**不含** v0.13.4 审计 UI、v0.13.5 书籍、REQ-029 力导向图。
+
+## 一、问题定义
+
+知识体系层当前只提供**树视图**一种结构展示方式（KnowledgeTreeView），节点以递归缩进列表排列。随着体系节点增多（> 10 个问题 + 概念/模型引用），树视图的局限性开始显现：
+
+1. **空间限制**：一级节点超过 5 个后纵向滚动沉重；子节点折叠在一层里看不见。
+2. **概念/模型游离**：概念和模型不在树中——它们在独立标签页里，用户无法在"看结构"的同时看到哪些节点关联了哪些概念。
+3. **整体感缺失**：树视图只展示问题轴，概念/模型/决策日志各占独立标签页——用户无法一眼看到体系全貌。
+4. **无法自由组织**：用户想按自己的认知习惯排布节点（重要的放中间、相关的放近处），树视图不允许——父子关系决定位置。
+
+**设计目标**：给用户一张可以自由排布知识节点的无限画布——不取代树视图，而是提供互补的"鸟瞰"视角。
+
+## 二、设计约束（核心纪律）
+
+本功能受且仅受以下纪律约束：
+
+1. **不是图可视化（REQ-029 P3 维持）**：画布不是力导向图。节点位置由用户拖拽决定，首次打开时以辐射布局计算初始位置——算法只在首次生效，用户拖走位置就不再改变。
+2. **不取代树视图**：画布与树视图共存。用户通过标签页栏的「画布」项或树视图内的浮钮切换。
+3. **零破坏既有数据**：canvas_x/y 列无值不影响树视图和既有命令。
+4. **连线只反映既有关系**：画布连线源于 knowledge_nodes.parent_id 和 knowledge_links。用户不能画线即建引用。
+5. **不做全屏白板模式**：画布在体系页中栏渲染，不是独立页面。
+
+## 三、技术选型
+
+**React Flow v12**（@xyflow/react）
+
+| 维度 | React Flow | 理由 |
+|------|-----------|------|
+| 无限画布 | pan/zoom 开箱即用 | 零自研 |
+| 自定义节点 | React 组件 | 可复用现有知识卡片 UI |
+| 连线 | smoothstep/bezier | parent_id 映射为边 |
+| 性能 | 虚拟化渲染（视口外不渲染） | 百节点级流畅 |
+| 框选/拖拽 | 内置 | 用户排布体验 |
+| minimap | 内置 MiniMap 组件 | 全局导航 |
+| 控制面板 | 内置 Controls 组件 | 缩放/适配/锁定 |
+| 包体积 | ~95KB gzip | 可接受 |
+
+对比方案：
+- 自研 DOM 画布：无虚拟化，~50 节点后抖。弃用。
+- 自研 Canvas：千节点级但 React 组件桥接复杂。弃用（成本高且收益过剩——知识体系节点数上限预计 < 200）。
+
+## 四、架构设计
+
+### 4.1 页面结构
+
+```
+KnowledgePage
+├── 左栏：体系列表（不变）
+├── 中栏：
+│   ├── [树视图] 标签（不变）—— KnowledgeTreeView
+│   │   └── 树视图顶部新增浮动「画布」按钮（切换 middleView）
+│   ├── [概念] 标签（不变）—— 概念列表
+│   ├── [模型] 标签（不变）—— 模型列表
+│   ├── [决策] 标签（不变）—— 决策日志
+│   ├── [画布] 标签（新增）—— KnowledgeCanvasView
+│   │   └── ReactFlow（无限画布）
+│   │       ├── CanvasNodeQuestion（自定义节点）
+│   │       ├── CanvasNodeConcept（自定义节点）
+│   │       ├── CanvasNodeModel（自定义节点）
+│   │       ├── edges（parent_id 映射）
+│   │       ├── MiniMap
+│   │       └── Controls
+│   └── 浮动工具栏（添加节点/适配视图/刷新布局）
+└── 右栏：详情面板（不变）
+```
+
+**切换交互**：用户选择了树视图内嵌切换 + 标签页栏并存。
+- 树视图顶部新增小号「画布」图标按钮，点击切到 middleView="canvas"
+- 画布视图顶部保留「树视图」返回按钮，点击切回 middleView="tree"
+- 同时标签页栏（概念/模型/决策日志/画布）保持可见，语义一致
+- 切换回树视图时折叠/展开状态和滚动位置保持（组件不退场）
+
+### 4.2 组件设计
+
+#### KnowledgeCanvasView（新增，~200 行）
+
+```
+Props:
+  systemId: number
+  nodes: KnowledgeNode[]
+  concepts: KnowledgeConcept[]
+  models: KnowledgeModel[]
+  links: KnowledgeLink[]
+  selectedNodeId: number | null
+  onSelectNode: (id: number) => void
+  onChanged: () => void
+
+职责:
+  1. nodes/concepts/models → React Flow 节点（Node[]）
+  2. parent_id → React Flow 边（Edge[]）
+  3. 首次切换时计算辐射布局初始位置
+  4. 拖拽结束 → invoke("update_node_canvas_position")
+  5. 节点点击 → onSelectNode（与树视图选中联动）
+  6. 切换回树视图时选中态保持一致
+```
+
+#### CanvasNodeQuestion（~60 行）
+
+React Flow 自定义节点。渲染单个知识问题。
+
+```
+┌────────────────────┐
+│ ❓ 照片为什么发灰  │
+│ 曝光三角 · 安全快门│  ← 关联概念徽标（若有）
+│ ◇ 黄金时刻法则     │  ← 关联模型徽标（若有）
+│ 📋 2 条笔记        │  ← 引用计数
+└────────────────────┘
+```
+
+- 宽度固定 220px，高度自适应
+- 标题区：类型图标 + 文本（省略号，最大 2 行）
+- 底部概念/模型/引用徽标行（复用 SystemBadge 风格）
+
+#### CanvasNodeConcept（~50 行）
+
+```
+┌──────────────────────┐
+│ 🧬 曝光三角          │
+│ 本质：光圈/快门/ISO  │
+│ ● 活跃               │
+└──────────────────────┘
+```
+
+- 宽度固定 180px
+- 概念名 + 本质摘要（1 行）+ 状态指示符
+
+#### CanvasNodeModel（~45 行）
+
+```
+┌──────────────────────┐
+│ ⚙ 黄金时刻法则        │
+│ 日出日落前后 1 小时   │
+│ 🏷 摄影               │
+└──────────────────────┘
+```
+
+- 宽度固定 180px
+- 模型名 + 主张摘录（1 行）+ 学科标签
+
+### 4.3 数据流
+
+```
+父级 (KnowledgePage)
+  │
+  ├─ 加载 systems → nodes/concepts/models/links（复用 loadSystemDetail）
+  │
+  └─ middleView === "canvas"
+       └─ KnowledgeCanvasView
+             │
+             ├─ React Flow 初始化
+             │   ├─ nodes: 辐射布局（首次）or 已存 canvas_x/y
+             │   ├─ edges: parent_id → Edge[]
+             │   └─ 渲染自定义节点
+             │
+             ├─ onNodeDragStop → debounce → invoke("update_node_canvas_position")
+             │   └─ { nodeId, canvasX, canvasY }
+             │
+             ├─ onNodeClick → onSelectNode(nodeId) → 右栏详情面板更新
+             │
+             └─ onFitView → React Flow fitView()
+```
+
+### 4.4 辐射布局算法
+
+用户选择了辐射布局——核心问题在圆心，子节点向外辐射。
+
+```
+算法：BFS 辐射布局（首次切到画布时触发 + 用户点"自动排列"时重新计算）
+
+输入：nodes（按 parent_id 组织）
+输出：Map<nodeId, {x, y}>
+
+术语：
+  - 层级（ring）：圆心为 ring 0，向外每层 +1
+  - BBox：问题节点 220x80px、概念节点 180x70px、模型节点 180x70px
+  - 环半径：圆心到该环中心线的距离，ring 1 = 220px，每环 +200px
+
+步骤：
+  1. 找出 parentId === null 的根节点组
+  2. ring 0（圆心）：无明确核心问题时第一个根在 (0, 0)；
+     有 coreQuestion 且有关联节点时，coreQuestion 虚拟节点在圆心
+  3. ring 1：根节点的直接子节点，均匀分布在环半径上
+     角度步长 = 360° / ring 1 节点数
+  4. ring 2+：子节点均匀分布在父节点方向扇区内
+     规则：子节点角度 = 父节点角度 ± spread
+     spread = 60° / (子节点数 + 1)
+  5. parentId 找不到父节点 → 最外环随机角度（兜底）
+  6. 碰撞检测：放置前检查 BBox 重叠 → 沿角度外推 +50px，最多 2 次后到下一环
+```
+
+> **纪律**：只计算一次。用户拖拽后位置不再参与算法。
+> 用户想重置布局可点"自动排列"按钮（触发全部重新计算，覆盖已存位置）。
+
+### 4.5 切换交互
+
+用户在头脑风暴中选择了"树视图内嵌切换"。具体交互设计：
+
+- KnowledgeTreeView 顶部新增一个图标按钮「🎨 画布」（小号，无色边框，hover 时变色）
+- 点击后 middleView 从 "tree" 切到 "canvas"
+- KnowledgeCanvasView 顶部新增返回按钮「← 树视图」
+- 标签页栏（概念/模型/决策日志/画布）中的「画布」项保持可用——两种入口互通
+- 切换回树视图时折叠展开状态保持（该状态由 KnowledgeTreeView 内部管理，组件不卸载）
+- 切换回画布时视口位置恢复（canvas_x/y + canvas_state 中的 viewport 信息）
+
+### 4.6 DB 变更
+
+```
+-- 节点画布位置（幂等 ensure_column）
+ALTER TABLE knowledge_nodes ADD COLUMN canvas_x REAL;
+ALTER TABLE knowledge_nodes ADD COLUMN canvas_y REAL;
+
+-- 体系画布状态表（视口位置恢复）
+CREATE TABLE IF NOT EXISTS knowledge_canvas_states (
+  system_id INTEGER PRIMARY KEY REFERENCES knowledge_systems(id),
+  viewport_x REAL DEFAULT 0,
+  viewport_y REAL DEFAULT 0,
+  zoom REAL DEFAULT 1.0
+);
+```
+
+**命令增量**（3 条新命令）：
+
+| 命令 | 入参 | 返回值 | 说明 |
+|------|------|--------|------|
+| update_node_canvas_position | nodeId, canvasX, canvasY | bool | 保存节点拖拽位置（防抖后调用） |
+| batch_initialize_canvas_positions | systemId, positions: [{nodeId, x, y}] | bool | 批量写入初始辐射位置 |
+| save_canvas_viewport | systemId, viewportX, viewportY, zoom | bool | 保存画布视口（切回时恢复） |
+
+## 五、与既有模式的冲突与兼容
+
+| 既有事实 | 画布如何兼容 |
+|---------|-------------|
+| knowledge_nodes 无 canvas_x/y | 默认为 null → 首次打开触发 batch_initialize |
+| 树视图选中节点高亮 | 画布选中同一节点：高亮画布节点 + 右栏不变（shared selectedNodeId） |
+| 概念/模型在独立标签页 | 画布上的概念/模型节点 = 浮动参照，新建仍需走概念/模型标签页 |
+| 树视图不支持概念/模型混排 | 画布同时显示问题+概念+模型（按类型区分颜色/图标） |
+| testid 驱动的测试模式 | 辐射布局算法纯函数可测；React Flow 渲染跳过 jsdom（见 §六） |
+
+## 六、测试策略
+
+- **KnowledgeTreeView 既有测试不变**——画布不影响树视图。
+- **辐射布局算法**：纯函数 layoutRadial(nodes) → 单测断言中心节点在 (0,0)、子节点均匀分布。零 React 依赖。
+- **KnowledgeCanvasView**：仅测数据转换（nodes → React Flow nodes/edges）。React Flow 渲染用 e2e 或跳过。
+- **命令单元测试**：Rust 侧 commands_knowledge 新增 canvas_x/y 写入与读取测试。
+
+## 七、UI 缩放体验
+
+- 画布缩放与节点文本挂钩：zoom > 0.7 显示完整内容，0.4~0.7 仅标题，< 0.4 缩略卡片（仅图标+节点名缩写）
+- 右键菜单（远期）：节点右键 → 编辑/删除/添加子节点
+
+## 八、性能预算
+
+| 场景 | 节点数 | 帧率目标 | 首开时间 |
+|------|--------|---------|---------|
+| 小体系 | < 20 | 60fps | < 500ms |
+| 中型体系 | 20-50 | 30-60fps | < 1s |
+| 大型体系 | 50-100 | 30fps | < 1.5s |
+| 超大型 | > 100 | >= 24fps | < 2s |
+
+React Flow 虚拟化在此数据量级下应无瓶颈。
+
+## 九、不做清单（本版）
+
+- 画布上新建/编辑节点（只做展示+拖拽）
+- 手动连线（用户不能画新边）
+- 节点颜色/标签自定义
+- 画布导出为图片
+- 框选批量移动（React Flow 内置但本版暂不暴露）
+- 移动端触控适配
+- AI 建议布局
+
+## 十、参考
+
+- ADR-024 知识体系层（方案 B）——有界体系通过、自由双链/图谱仍出局
+- v0.13.1 知识体系基建规格（[ ] 已归档）
+- 知识体系设计理念（§四 为什么不算"知识图谱回归"）
+- React Flow 官方文档：https://reactflow.dev/