# API 接口文档

## 1. 通用说明

### 1.1 接口规范

- 基础路径: `/api/v1`
- 请求方式: REST风格
- 数据格式: JSON
- 字符编码: UTF-8
- 时间格式: ISO8601 (YYYY-MM-DDTHH:mm:ss.SSSZ)

### 1.2 通用响应格式

```json
{
  "code": 0,           // 响应码，0表示成功，非0表示失败
  "message": "成功",    // 响应消息
  "data": {            // 响应数据
    // 具体数据结构
  }
}
```

### 1.3 通用查询参数

分页查询参数：
```json
{
  "page": 1,           // 页码，从1开始
  "size": 10,          // 每页大小
  "sort": ["id,desc"], // 排序字段，可选
  "keyword": "",       // 关键字搜索，可选
}
```

### 1.4 通用错误码

| 错误码 | 说明 | 处理建议 |
|--------|------|----------|
| 0 | 成功 | - |
| 1000 | 系统内部错误 | 联系管理员 |
| 1001 | 数据库操作失败 | 重试或联系管理员 |
| 1002 | 并发操作冲突 | 刷新后重试 |
| 2000 | 参数验证失败 | 检查参数 |
| 2001 | 数据不存在 | 检查参数 |
| 2002 | 数据已存在 | 检查参数 |

## 2. 工作流定义��口

### 2.1 创建工作流定义

**接口说明**：创建新的工作流定义

**请求路径**：POST /workflow-definitions

**请求参数**：
```json
{
  "code": "string",          // 工作流编码，必填，唯一
  "name": "string",          // 工作流名称，必填
  "description": "string",   // 描述，可选
  "nodeConfig": {            // 节点配置，必填
    "nodes": [{
      "id": "string",       // 节点ID
      "type": "string",     // 节点类型
      "name": "string",     // 节点名称
      "config": {           // 节点配置
        // 具体配置项根据节点类型定义
      }
    }]
  },
  "transitionConfig": {      // 流转配置，必填
    "transitions": [{
      "from": "string",     // 来源节点ID
      "to": "string",       // 目标节点ID
      "condition": "string" // 流转条件
    }]
  },
  "formDefinition": {        // 表单定义，必填
    // 表单配置项
  },
  "graphDefinition": {       // 图形定义，必填
    // 图形布局配置
  }
}
```

**响应数据**：
```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": "long",           // 工作流定义ID
    "code": "string",       // 工作流编码
    "name": "string",       // 工作流名称
    "description": "string", // 描述
    "version": 1,           // 版本号
    "status": "DRAFT",      // 状态：DRAFT-草稿、PUBLISHED-已发布、DISABLED-已禁用
    "enabled": true,        // 是否启用
    "nodeConfig": {},       // 节点配置
    "transitionConfig": {}, // 流转配置
    "formDefinition": {},   // 表单定义
    "graphDefinition": {},  // 图形定义
    "createTime": "string", // 创建时间
    "updateTime": "string"  // 更新时间
  }
}
```

### 2.2 更新工作流定义

**接口说明**：更新工作流定义，仅草稿状态可更新

**请求路径**：PUT /workflow-definitions/{id}

**路径参数**：
- id: 工作流定义ID

**请求参数**：同创建接口

**响应数据**：同创建接口

### 2.3 发布工作流定义

**接口说明**：发布工作流定义，使其可被使用

**请求路径**：POST /workflow-definitions/{id}/publish

**路径参数**：
- id: 工作流定义ID

**响应数据**：同创建接口

### 2.4 禁用工作流定义

**接口说明**：禁用工作流定义，禁止新建实例

**请求路径**：POST /workflow-definitions/{id}/disable

**路径参数**：
- id: 工作流定义ID

**响应数据**：同创建接口

### 2.5 启用工作流定义

**接口说明**：启用已��用的工作流定义

**请求路径**：POST /workflow-definitions/{id}/enable

**路径参数**：
- id: 工作流定义ID

**响应数据**：同创建接口

### 2.6 创建新版本

**接口说明**：基于现有工作流定义创建新版本

**请求路径**：POST /workflow-definitions/{id}/versions

**路径参数**：
- id: 工作流定义ID

**响应数据**：同创建接口

### 2.7 查询工作流定义列表

**接口说明**：分页查询工作流定义列表

**请求路径**：GET /workflow-definitions

**请求参数**：
```json
{
  "page": 1,           // 页码，从1开始
  "size": 10,          // 每页大小
  "sort": ["id,desc"], // 排序字段
  "keyword": "",       // 关键字搜索
  "status": "DRAFT",   // 状态过滤
  "enabled": true      // 是否启用
}
```

**响应数据**：
```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "content": [{      // 列表数据
      // 工作流定义数据，同创建接口
    }],
    "totalElements": 100, // 总记录数
    "totalPages": 10,    // 总页数
    "size": 10,         // 每页大小
    "number": 1         // 当前页码
  }
}
```

## 3. 工作流实例接口

### 3.1 创建工作流实例

**接口说明**：创建工作流实例

**请求路径**：POST /workflow-instances

**请求参数**：
```json
{
  "definitionId": "long",    // 工作流定义ID，必填
  "businessKey": "string",   // 业务标识，可选
  "variables": {             // 初始变量，可选
    "key": "value"
  }
}
```

**响应数据**：
```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "id": "long",           // 实例ID
    "definitionId": "long", // 定义ID
    "businessKey": "string",// 业务标识
    "status": "CREATED",    // 状态：CREATED-已创建、RUNNING-运行中、SUSPENDED-已暂停、COMPLETED-已完成、TERMINATED-已终止
    "startTime": "string",  // 开始时间
    "endTime": "string",    // 结束时间
    "variables": {},        // 变量
    "createTime": "string", // 创建时间
    "updateTime": "string"  // 更新时间
  }
}
```

### 3.2 启动工作流实例

**接口说明**：启动工作流实例

**请求路径**：POST /workflow-instances/{id}/start

**路径参数**：
- id: 实例ID

**响应数据**：同创建接口

### 3.3 暂停工作流实例

**接口说明**：暂停运行中的工作流实例

**请求路径**：POST /workflow-instances/{id}/suspend

**路径参数**：
- id: 实例ID

**响应数据**：同创建接口

### 3.4 恢复工作流实例

**接口说明**：恢复已暂停的工作流实例

**请求路径**：POST /workflow-instances/{id}/resume

**路径参数**：
- id: 实例ID

**响应数据**：同创建接口

### 3.5 终止工作流实例

**接口说明**：强制终止工作流实例

**请求路径**：POST /workflow-instances/{id}/terminate

**路径参数**：
- id: 实例ID

**响应数据**：同创建接口

### 3.6 查询工作流实例列表

**接口说明**：分页查询工作流实例列表

**请求路径**：GET /workflow-instances

**请求参数**：
```json
{
  "page": 1,           // 页码，从1开始
  "size": 10,          // 每页大小
  "sort": ["id,desc"], // 排序字段
  "keyword": "",       // 关键字搜索
  "status": "RUNNING", // 状态过滤
  "definitionId": "long", // 定义ID过滤
  "businessKey": "string" // 业务标识过滤
}
```

**响应数据**：
```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "content": [{      // 列表数据
      // 工作流实例数据，同创建接口
    }],
    "totalElements": 100, // 总记录数
    "totalPages": 10,    // 总页数
    "size": 10,         // 每页大小
    "number": 1         // 当前页码
  }
}
```

## 4. 节点实例接口

### 4.1 查询节点实例列表

**接口说明**：查询工作流实例的节点列表

**请求路径**：GET /workflow-instances/{instanceId}/nodes

**路径参数**：
- instanceId: 工作流实例ID

**请求参数**：
```json
{
  "status": "RUNNING" // 状态过滤，可选
}
```

**响应数据**：
```json
{
  "code": 0,
  "message": "成功",
  "data": [{
    "id": "long",           // 节点实例ID
    "workflowInstanceId": "long", // 工作流实例ID
    "nodeId": "string",     // 节点定义ID
    "nodeName": "string",   // 节点名称
    "nodeType": "string",   // 节点类型
    "status": "string",     // 状态：CREATED、RUNNING、COMPLETED、FAILED
    "startTime": "string",  // 开始时间
    "endTime": "string",    // 结束时间
    "output": "string",     // 输出结果
    "error": "string",      // 错误信息
    "createTime": "string", // 创建时间
    "updateTime": "string"  // 更新时间
  }]
}
```

## 5. 工作流变量接口

### 5.1 设置变量

**接口说明**：设置工作流实例变量

**请求路径**：POST /workflow-instances/{instanceId}/variables

**路径参数**：
- instanceId: 工作流实例ID

**请求参数**：
```json
{
  "name": "string",    // 变量名，必填
  "value": "object",   // 变量值，必��
  "scope": "GLOBAL"    // 作用域：GLOBAL-全局、NODE-节点，可选，默认GLOBAL
}
```

**响应数据**：
```json
{
  "code": 0,
  "message": "成功"
}
```

### 5.2 获取变量

**接口说明**：获取工作流实例变量

**请求路径**：GET /workflow-instances/{instanceId}/variables

**路径参数**：
- instanceId: 工作流实例ID

**请求参数**：
```json
{
  "scope": "GLOBAL" // 作用域过滤，可选
}
```

**响应数据**：
```json
{
  "code": 0,
  "message": "成功",
  "data": {
    "variableName": "variableValue"
  }
}
```

## 6. 工作流日志接口

### 6.1 查询日志列表

**接口说明**：查询工作流实例日志

**请求路径**：GET /workflow-instances/{instanceId}/logs

**路径参数**：
- instanceId: 工作流实例ID

**请求参数**：
```json
{
  "nodeId": "string",  // 节点ID过滤，可选
  "level": "INFO",     // 日志级别过滤：DEBUG、INFO、WARN、ERROR，可选
  "startTime": "string", // 开始时间过滤，可选
  "endTime": "string"   // 结束时间过滤，可选
}
```

**响应数据**：
```json
{
  "code": 0,
  "message": "成功",
  "data": [{
    "id": "long",           // 日志ID
    "workflowInstanceId": "long", // 工作流实例ID
    "nodeId": "string",     // 节点ID
    "level": "string",      // 日志级别
    "content": "string",    // 日志内容
    "detail": "string",     // 详细信息
    "createTime": "string"  // 创建时间
  }]
}
```

## 7. 节点类型接口

### 7.1 查询节点类型列表

**接口说明**：查询可用的节点类型列表

**请求路径**：GET /node-types

**请求参数**：
```json
{
  "enabled": true,     // 是否启用过滤，可选
  "category": "TASK"   // 类型分类过滤：TASK、EVENT、GATEWAY，可选
}
```

**响应数据**：
```json
{
  "code": 0,
  "message": "成功",
  "data": [{
    "id": "long",           // 节点类型ID
    "code": "string",       // 节点类型编码
    "name": "string",       // 节点类型名称
    "category": "string",   // 分类
    "description": "string", // 描述
    "enabled": true,        // 是否启用
    "icon": "string",       // 图标
    "color": "string",      // 颜色
    "executors": [{         // 执行器列表（仅TASK类型）
      "code": "string",     // 执行器编码
      "name": "string",     // 执行器名称
      "description": "string", // 描述
      "configSchema": {}    // 配置模式
    }],
    "createTime": "string", // 创建时间
    "updateTime": "string"  // 更新时间
  }]
}
```

### 7.2 获取节点执行器列表

**接口说明**：获取指定节点类型支持的执行器列表

**请求路径**：GET /node-types/{code}/executors

**路径参数**：
- code: 节点类型编码

**响应数据**：
```json
{
  "code": 0,
  "message": "成功",
  "data": [{
    "code": "string",      // 执行器编码
    "name": "string",      // 执行器名称
    "description": "string", // 描述
    "configSchema": {      // 配置模式
      "type": "object",
      "properties": {
        // 具体配置项定义
      },
      "required": []       // 必填项
    }
  }]
}
```

## 8. 错误码说明

### 8.1 系统错误 (1xxx)
- 1000: 系统内部错误
- 1001: 数据库操作失败
- 1002: 并发操作冲突

### 8.2 通用业务错误 (2xxx)
- 2000: 参数验证失败
- 2001: 数据不存在
- 2002: 数据已存在

### 8.3 工作流定义错误 (3xxx)
- 3000: 工作流定义不存在
- 3001: 工作流编码已存在
- 3002: 工作流定义非草稿状态
- 3003: 工作流定义未发布
- 3004: 工作流定义已禁用
- 3005: 节点配置无效
- 3006: 流转配置无效
- 3007: 表单配置无效

### 8.4 工作流实例错误 (4xxx)
- 4000: 工作流实例不存在
- 4001: 工作流实例状态无效
- 4002: 工作流实例已终止
- 4003: 节点实例不存在
- 4004: 变量类型无效

## 9. 数据结构说明

### 9.1 工作流状态

```typescript
enum WorkflowStatus {
  DRAFT = "DRAFT",         // 草稿
  PUBLISHED = "PUBLISHED", // 已发布
  DISABLED = "DISABLED"    // 已禁用
}
```

### 9.2 实例状态

```typescript
enum InstanceStatus {
  CREATED = "CREATED",     // 已创建
  RUNNING = "RUNNING",     // 运行中
  SUSPENDED = "SUSPENDED", // 已暂停
  COMPLETED = "COMPLETED", // 已完成
  TERMINATED = "TERMINATED"// 已终止
}
```

### 9.3 节点状态

```typescript
enum NodeStatus {
  CREATED = "CREATED",     // 已创建
  RUNNING = "RUNNING",     // 运行中
  COMPLETED = "COMPLETED", // 已完成
  FAILED = "FAILED"        // 失败
}
```

### 9.4 日志级别

```typescript
enum LogLevel {
  DEBUG = "DEBUG",
  INFO = "INFO",
  WARN = "WARN",
  ERROR = "ERROR"
}
```

### 9.5 变量作用域

```typescript
enum VariableScope {
  GLOBAL = "GLOBAL",       // 全局变量
  NODE = "NODE"           // 节点变量
}
```

## 10. 最佳实践

### 10.1 工作流设计

1. 工作流定义创建流程：
   - 创建草稿
   - 配置节点和流转
   - 验证配置
   - 发布使用

2. 节点类型选择：
   - 根据业务场景选择合适的节点类型
   - 配置合适的执行器
   - 设置必要的变量

### 10.2 实例管理

1. 实例生命周期管理：
   - 创建 -> 启动 -> 运行 -> 完成
   - 必要时可暂停或终止
   - 记录关键节点日志

2. 变量使用：
   - 合理使用变量作用域
   - 及时清理无用变量
   - 注意变量类型匹配

### 10.3 错误处理

1. 异常处理：
   - 捕获所有可能的错误码
   - 提供友好的错误提示
   - 记录详细的错误日志

2. 重试机制：
   - 对非致命错误进行重试
   - 设置合理的重试间隔
   - 限制最大重试次数

### 10.4 性能优化

1. 查询优化：
   - 合理使用分页
   - 避免大量数据查询
   - 使用合适的查询条件

2. 缓存使用：
   - 缓存常用数据
   - 及时更新缓存
   - 避免缓存穿透