Agentic BI — 04-05 可视化升级¶

React Flow 流程图集成¶

里程碑达成¶

2026-04-05 13:59: React Flow 流程图首次渲染成功 - ✅ Topic 节点可视化 - ✅ 连接线展示
- ✅ Spinner 状态显示 - ✅ Agentic BI 工作台可视化主链路打通

技术架构选择¶

React Flow + dagre 组合: - React Flow: 提供节点交互、视口控制、联动能力 - dagre: 适合 DAG/分层结构自动布局 - 符合场景: "分类 → 项目 → 主题/任务" 的层级关系

初始规模挑战¶

数据量级: 全量约 154 个节点 - Category 层: 项目分类节点 - Project 层: 具体项目节点
- Topic 层: 主题/任务节点 - 布局挑战: 垂直展开可达上万像素

布局渲染问题排查¶

视口适配失败¶

问题现象: fitView 无法将全图合理缩放进画布 - 即使 minZoom 降到 0.05，仍只能看到图的一角 - 切换到"进行中"筛选（14个节点）效果改善但仍不完全

节点堆叠问题发现¶

Dad 的关键观察: "都堆在了一起，很奇怪" - 将问题焦点从"视口缩放"转向"布局错误" - 18个节点只落在4个坐标位置，严重重叠

根因定位与修复¶

排查过程: 1. ✅ 检查 viewport: 缩放和可视范围足够 2. ✅ 检查节点 ID: 确认唯一性
3. ✅ 检查数据结构: 逻辑正常 4. 🔍 直接打印 dagre 计算结果: - 所有 Category 节点: (40, 1110) - 所有 Project 节点: (350, 1100) - 所有 Topic 节点: (700, 1170)

根本原因: getNodeSize 返回对象引用而非新对象

// 错误: 共享引用
const NODE_SIZE = {
  category: { width: 120, height: 50 },
  project: { width: 150, height: 60 },
  topic: { width: 200, height: 70 }
};

// dagre 内部修改该对象，导致布局异常
function getNodeSize(type) {
  return NODE_SIZE[type]; // 危险的引用共享
}

修复方案: 确保每次返回新的尺寸对象

function getNodeSize(type) {
  return { ...NODE_SIZE[type] }; // 安全的对象复制
}

修复效果¶

结果: 流程图渲染正确，三层结构清晰可见 - Category / Project / Topic 层次分明 - 节点分散布局合理 - 连接线关系明确

产品化交互优化¶

默认视图调整¶

bot 的产品决策: 将默认筛选从"全部"改为"进行中"

决策理由: - 全量 100+ 节点图过大、文字不可读 - "进行中"展示当前活跃任务，符合工作台操作场景 - 提升用户首次使用体验

可读性优化¶

同步改进: - 增大 topic 节点宽度，减少标题截断 - 调整 dagre 的 nodesep 等参数，缓解拥挤 - 优化节点文字大小和颜色对比

自动适配尝试¶

技术方案: - 引入 ReactFlowProvider - 增加 AutoFitView 子组件 - 监听节点变化自动触发 fitView

挑战: 触发时机可能早于节点真实完成布局，需要进一步调优

可视化设计理念¶

工作台思维¶

将 React Flow 定位为工作台主画布: - 不仅是数据展示，更是操作入口 - 支持节点交互和状态联动 - 为后续功能扩展预留接口

层级关系表达¶

三层架构可视化:

Category (业务分类)
    ↓
Project (具体项目) 
    ↓  
Topic (主题/任务)

每层具有不同的视觉权重和交互能力，符合用户的认知层次。

状态驱动设计¶

动态视图: - 筛选条件改变 → 节点集合变化 → 自动重新布局 - 项目状态更新 → 节点颜色变化 → 实时反映进展 - 用户交互 → 焦点切换 → 相关节点高亮

技术经验总结¶

dagre 布局陷阱¶

对象引用共享: 多个节点共享同一尺寸对象导致布局异常
布局时机: 需要确保数据准备完成后再执行布局计算
参数调优: nodesep, ranksep 等参数对视觉效果影响显著

React Flow 最佳实践¶

Provider 包装: 使用 ReactFlowProvider 确保功能完整
视口管理: fitView 需要配合 minZoom 等参数精确控制
性能考虑: 大量节点时考虑虚拟化或分页加载

可视化产品设计¶

默认视图: 首次使用应展示最有价值的子集，而非全量数据
渐进展示: 从概览到细节，支持逐步深入探索
状态反馈: 加载状态、错误状态、空数据状态都要有明确表达

后续发展方向¶

交互功能扩展¶

节点点击进入详情页
拖拽调整项目优先级
双击编辑节点信息
右键菜单操作

数据联动增强¶

与聊天界面的双向联动
节点状态与后端数据同步
实时更新和推送机制

视觉效果提升¶

节点图标和色彩系统
动画和过渡效果
响应式布局适配
主题和自定义样式

技术里程碑¶

时间	成就	技术价值
13:59	React Flow 首次渲染	可视化技术栈验证
14:01	发现节点堆叠问题	布局算法深入理解
14:08	对象引用问题修复	JavaScript 引用机制认知
产品化	默认视图优化	用户体验设计思维

这一天的工作将 Agentic BI 从纯聊天式工具升级为图形化工作台，标志着项目从功能实现向产品化体验的重要跃迁。React Flow 集成不仅解决了可视化需求，更为未来的工作流管理功能奠定了技术基础。