# 后端开发指南

## 待开发接口清单

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

#### 1.1 更新工作流定义
```typescript
PUT /api/v1/workflow-definitions/{id}
Request: {
  // 基本信息
  code: string;        // 工作流编码
  name: string;        // 工作流名称
  description: string; // 工作流描述
  version: number;     // 版本号
  
  // 设计数据
  design?: {
    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: WorkflowDefinitionDTO;
  message: string;
}
```

#### 1.2 导入工作流定义（待实现）
```typescript
POST /api/v1/workflow-definitions/import
Request: FormData {
  file: File;  // JSON格式的工作流定义文件
}
Response: {
  code: number;
  data: WorkflowDefinitionDTO;
  message: string;
}
```

#### 1.3 导出工作流定义（待实现）
```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. 性能测试
   - 测试大数据量导出的性能
   - 验证并发处理能力