From 0e9e3e2b322f2ac52f986c48176ad006041a409d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E6=88=9A=E8=BE=B0=E5=85=88=E7=94=9F?= Date: Thu, 5 Dec 2024 14:37:23 +0800 Subject: [PATCH] =?UTF-8?q?=E5=A2=9E=E5=8A=A0=E5=B7=A5=E4=BD=9C=E6=B5=81?= =?UTF-8?q?=E4=BB=A3=E7=A0=81=E5=8F=AF=E6=AD=A3=E5=B8=B8=E5=90=AF=E5=8A=A8?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- backend/docs/backend-development-guide.md | 181 +++++++++++++++++++++- 1 file changed, 180 insertions(+), 1 deletion(-) diff --git a/backend/docs/backend-development-guide.md b/backend/docs/backend-development-guide.md index 0519ecba..c3d8cd81 100644 --- a/backend/docs/backend-development-guide.md +++ b/backend/docs/backend-development-guide.md @@ -1 +1,180 @@ - \ No newline at end of file +# 后端开发指南 + +## 待开发接口清单 + +### 1. 工作流定义管理 (WorkflowDefinitionApiController) + +#### 1.1 保存工作流设计 +```typescript +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; + } + }]; + edges: [{ + id: string; + source: string; + target: string; + type: string; + data?: { + condition?: string; + } + }] +} +Response: { + code: number; + data: boolean; + message: string; +} +``` + +#### 1.2 获取工作流设计 +```typescript +GET /api/v1/workflow-definitions/{id}/design +Response: { + code: number; + data: { + nodes: Node[]; + edges: Edge[]; + }; + message: string; +} +``` + +#### 1.3 导入工作流定义 +```typescript +POST /api/v1/workflow-definitions/import +Request: FormData { + file: File; // JSON格式的工作流定义文件 +} +Response: { + code: number; + data: WorkflowDefinitionDTO; + message: string; +} +``` + +#### 1.4 导出工作流定义 +```typescript +GET /api/v1/workflow-definitions/{id}/export +Response: File // JSON格式的工作流定义文件 +``` + +### 2. 工作流实例管理 (WorkflowInstanceApiController) + +#### 2.1 导出工作流实例 +```typescript +GET /api/v1/workflow-instances/export +Query Parameters: + - startTime?: string // 开始时间 + - endTime?: string // 结束时间 + - status?: string // 实例状态 + - keyword?: string // 关键字搜索 +Response: File // Excel格式的工作流实例数据 +``` + +### 3. 节点实例管理 (NodeInstanceApiController) + +#### 3.1 导出节点实例 +```typescript +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 导出节点类型 +```typescript +GET /api/v1/node-types/export +Query Parameters: + - category?: string // 节点类型分类 + - enabled?: boolean // 是否启用 +Response: File // Excel格式的节点类型数据 +``` + +### 5. 工作流日志管理 (WorkflowLogApiController) + +#### 5.1 导出日志 +```typescript +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. 性能测试 + - 测试大数据量导出的性能 + - 验证并发处理能力 \ No newline at end of file