qinglong/FLOWGRAM_INTEGRATION_STATUS.md

Flowgram 可视化工作流集成进度 (Flowgram Visual Workflow Integration Progress)

当前状态 (Current Status)

✅ 已完成 (Completed - Commit: fffc1e4)

1. 依赖安装 (Dependencies Installed)

   • @flowgram.ai/free-layout-editor@1.0.2
   • @flowgram.ai/core@1.0.2
   • @flowgram.ai/reactive@1.0.2

2. 数据模型更新 (Data Model Updates)

   • 添加 workflowGraph 字段到 Scenario 模型
   • 保留旧字段以保持向后兼容
   • 数据库迁移脚本已更新

3. API 层更新 (API Layer Updates)

   • triggerType 从必需改为可选
   • 添加 workflowGraph 参数支持
   • Create 和 Update 端点已更新

4. 前端基础 (Frontend Foundation)

   • 创建新的 flowgramModal.tsx 组件
   • 主页面更新使用新的模态框
   • 基础工作流结构定义

🔄 需要完成 (To Be Completed)

1. 完善 Flowgram 编辑器集成 (Complete Flowgram Editor Integration)

当前问题: Flowgram.ai 的详细 API 文档不完全公开。需要：

• 研究 Flowgram API 的正确使用方式
• 实现自定义节点渲染器
• 添加节点工具栏和配置面板

临时方案:

• 可以使用 React Flow 或其他开源流程图库作为替代
• 或等待 Flowgram 官方文档/示例

2. 自定义节点类型实现 (Custom Node Types)

需要实现以下节点类型：

// Trigger Nodes (触发器节点)
- TimeT riggerNode: 时间触发配置
- WebhookTriggerNode: Webhook 触发配置
- VariableTriggerNode: 变量监听配置
- TaskStatusTriggerNode: 任务状态触发
- SystemEventTriggerNode: 系统事件触发

// Condition Nodes (条件节点)
- ConditionNode: 条件判断配置
- LogicGateNode: AND/OR 逻辑门

// Action Nodes (动作节点)
- RunTaskNode: 运行任务配置
- SetVariableNode: 设置变量配置
- ExecuteCommandNode: 执行命令配置
- SendNotificationNode: 发送通知配置

// Control Flow Nodes (控制流节点)
- DelayNode: 延迟执行
- RetryNode: 重试策略
- CircuitBreakerNode: 熔断器

3. 节点配置面板 (Node Configuration Panels)

每个节点类型需要自己的配置表单：

• 双击节点打开配置面板
• 表单验证
• 实时预览

4. 后端执行引擎重写 (Backend Execution Engine Rewrite)

当前 ScenarioService.executeScenario() 是线性执行。需要：

// 新的图执行引擎
class GraphExecutor {
  async execute(workflowGraph: any, triggerData: any) {
    // 1. 查找入口节点（触发器节点）
    // 2. 遍历图结构
    // 3. 评估条件节点
    // 4. 执行动作节点
    // 5. 处理分支和合并
    // 6. 记录执行轨迹
  }
}

5. 工作流验证 (Workflow Validation)

• 检查是否有有效的触发器节点
• 验证节点连接的完整性
• 检测循环
• 验证节点配置

6. 测试和调试 (Testing & Debugging)

• 单元测试
• 集成测试
• UI 测试
• 性能测试

实现建议 (Implementation Recommendations)

方案 A: 完整 Flowgram 集成 (推荐如有文档)

如果能获取 Flowgram 完整文档和示例：

1. 参考官方示例实现自定义节点
2. 使用 Flowgram 的插件系统
3. 利用 Flowgram 的内置功能

方案 B: 使用 React Flow (备选方案)

如果 Flowgram 文档不足：

1. 使用 React Flow (reactflow npm package)
2. 成熟的文档和社区支持
3. 更容易实现自定义节点
4. 保持相同的数据结构

方案 C: 混合方案

1. 前端继续改进表单界面
2. 后端同时支持表单数据和图数据
3. 渐进式迁移

预估工作量 (Estimated Effort)

• 方案 A (Flowgram): 20-30 小时（假设有文档）
• 方案 B (React Flow): 15-20 小时
• 方案 C (渐进式): 10-15 小时初始，后续持续

下一步建议 (Next Steps Recommendations)

1. 立即: 确认是否有 Flowgram 官方文档或示例代码
2. 短期: 实现一个简单的节点（如触发器节点）作为 POC
3. 中期: 完成所有节点类型和配置面板
4. 长期: 重写执行引擎并测试

技术债务注意 (Technical Debt Notes)

• 旧的表单数据结构被标记为 deprecated 但仍保留
• 需要在未来版本中清理
• 数据库包含两套结构的字段

联系和协作 (Contact & Collaboration)

如需加速开发，建议：

1. 获取 Flowgram 官方支持或文档
2. 提供 Flowgram 集成的参考示例
3. 或考虑使用 React Flow 等替代方案