deploy-ease-platform/backend/docs/backend-development-guide.md

后端开发指南

待开发接口清单

1. 工作流定义管理 (WorkflowDefinitionApiController)

1.1 保存工作流设计

POST /api/v1/workflow-definitions/{id}/design
Request: {
  nodes: [{
    id: string;
    type: string;
    position: { x: number; y: number };
    data: {
      name: string;
      description?: string;
      config: Record<string, any>;
    }
  }];
  edges: [{
    id: string;
    source: string;
    target: string;
    type: string;
    data?: {
      condition?: string;
    }
  }]
}
Response: {
  code: number;
  data: boolean;
  message: string;
}

1.2 获取工作流设计

GET /api/v1/workflow-definitions/{id}/design
Response: {
  code: number;
  data: {
    nodes: Node[];
    edges: Edge[];
  };
  message: string;
}

1.3 导入工作流定义

POST /api/v1/workflow-definitions/import
Request: FormData {
  file: File;  // JSON格式的工作流定义文件
}
Response: {
  code: number;
  data: WorkflowDefinitionDTO;
  message: string;
}

1.4 导出工作流定义

GET /api/v1/workflow-definitions/{id}/export
Response: File  // JSON格式的工作流定义文件

2. 工作流实例管理 (WorkflowInstanceApiController)

2.1 导出工作流实例

GET /api/v1/workflow-instances/export
Query Parameters:
  - startTime?: string  // 开始时间
  - endTime?: string    // 结束时间
  - status?: string     // 实例状态
  - keyword?: string    // 关键字搜索
Response: File  // Excel格式的工作流实例数据

3. 节点实例管理 (NodeInstanceApiController)

3.1 导出节点实例

GET /api/v1/node-instances/export
Query Parameters:
  - workflowInstanceId?: string  // 工作流实例ID
  - nodeType?: string           // 节点类型
  - status?: string            // 节点状态
  - startTime?: string         // 开始时间
  - endTime?: string           // 结束时间
Response: File  // Excel格式的节点实例数据

4. 节点类型管理 (NodeTypeApiController)

4.1 导出节点类型

GET /api/v1/node-types/export
Query Parameters:
  - category?: string  // 节点类型分类
  - enabled?: boolean  // 是否启用
Response: File  // Excel格式的节点类型数据

5. 工作流日志管理 (WorkflowLogApiController)

5.1 导出日志

GET /api/v1/workflow-logs/export
Query Parameters:
  - workflowInstanceId?: string  // 工作流实例ID
  - nodeId?: string            // 节点ID
  - level?: string            // 日志级别
  - startTime?: string        // 开始时间
  - endTime?: string          // 结束时间
Response: File  // Excel格式的日志数据

开发注意事项

1. 工作流设计数据存储

• 工作流设计数据应该存储在 workflow_definition 表的 design_data 字段中
• 数据格式为JSON字符串
• 需要实现JSON序列化和反序列化

2. 数据导出功能

• 使用 Apache POI 处理Excel文件
• 支持大数据量导出
• 添加导出进度提示
• 支持自定义导出字段

3. 数据验证

• 工作流设计数据的完整性验证
• 节点连接的有效性验证
• 配置数据的格式验证

4. 错误处理

• 添加详细的错误提示
• 记录操作日志
• 支持事务回滚

5. 性能优化

• 大数据量导出时使用分页
• 添加必要的索引
• 使用缓存优化查询性能

开发优先级建议

1. 工作流设计数据的保存和获取

   • 这是工作流设计器的核心功能
   • 前端需要这些接口来实现基本功能

2. 工作流设计的验证

   • 确保工作流设计的正确性
   • 避免错误的工作流定义被发布

3. 工作流定义的导入导出

   • 支持工作流定义的迁移
   • 方便工作流的备份和恢复

4. 各个模块的数据导出

   • 用于数据分析和备份
   • 相对优先级较低

测试要求

1. 单元测试

   • 测试各个Service层的核心方法
   • 验证数据处理逻辑的正确性

2. 集成测试

   • 测试API接口的功能
   • 验证数据库操作的正确性

3. 性能测试

   • 测试大数据量导出的性能
   • 验证并发处理能力