flowable-devops/docs/05-API契约.md

API 契约（前后端统一）

版本: v1.0
鉴权: 预留 Bearer Token（可选），前端 axios 已支持 Authorization 头；MVP 可不启用严格鉴权。

通用规范

• Content-Type: application/json; charset=utf-8
• 分页参数（如适用）: page(默认1), size(默认10)
• 错误响应: { "code": string, "message": string, "details"?: any }

一、工作流（/api/workflows）

1. 创建工作流

• POST /api/workflows
• Body: WorkflowDefinition（见 04-数据模型设计.md），id 可由后端生成
• 200 响应: WorkflowDefinition（包含持久化后的 id）

2. 更新工作流

• PUT /api/workflows/{id}
• Body: WorkflowDefinition
• 200 响应: WorkflowDefinition

3. 获取工作流详情

• GET /api/workflows/{id}
• 200 响应: WorkflowDefinition

4. 获取工作流列表

• GET /api/workflows?status=active|draft|archived&page=1&size=10
• 200 响应: { "items": WorkflowDefinition[], "page": number, "size": number, "total": number }

5. 删除工作流

• DELETE /api/workflows/{id}
• 204 响应: 无

6. 执行工作流（MVP 同步执行）

• POST /api/workflows/{id}/execute
• Body: { "input": object }
• 200 响应: WorkflowExecutionResult

{
  "workflowId": "wf_001",
  "processInstanceId": "f6a...",
  "status": "completed",   
  "output": { "result": "..." },
  "nodes": {
    "n1": { "status": "success", "input": {...}, "output": {...}, "startTime": "...", "endTime": "..." },
    "n2": { "status": "success", "input": {...}, "output": {...} }
  },
  "startedAt": "2025-01-01T10:00:00Z",
  "endedAt": "2025-01-01T10:00:02Z"
}

7. 获取执行记录

• GET /api/workflows/{id}/executions?page=1&size=10
• 200 响应: { "items": WorkflowExecutionRecord[], "page": number, "size": number, "total": number }

{
  "id": "exe_001",
  "workflowDefinitionId": "wf_001",
  "processInstanceId": "f6a...",
  "status": "completed",   
  "triggerType": "manual",
  "triggeredBy": "user@example.com",
  "startedAt": "2025-01-01T10:00:00Z",
  "endedAt": "2025-01-01T10:00:02Z"
}

8. 获取执行详情

• GET /api/workflows/executions/{executionId}
• 200 响应: WorkflowExecutionDetail

{
  "id": "exe_001",
  "workflowDefinitionId": "wf_001",
  "processInstanceId": "f6a...",
  "status": "completed",
  "input": { "userId": 1 },
  "nodes": {
    "n1": { "status": "success", "input": {...}, "output": {...} },
    "n2": { "status": "success", "input": {...}, "output": {...} }
  },
  "startedAt": "2025-01-01T10:00:00Z",
  "endedAt": "2025-01-01T10:00:02Z",
  "error": null
}

二、节点类型（/api/node-types）

1. 获取全部节点类型

• GET /api/node-types
• 200 响应: NodeTypeMetadata[]（见 04-数据模型设计.md）

2. 获取单个节点类型

• GET /api/node-types/{typeId}
• 200 响应: NodeTypeMetadata

3. 按分类查询

• GET /api/node-types/category/{category}
• 200 响应: NodeTypeMetadata[]

三、审批任务（/api/tasks）

1. 获取待办任务

• GET /api/tasks?assignee=user@example.com&page=1&size=10
• 200 响应: { "items": TaskInfo[], "page": number, "size": number, "total": number }

{
  "id": "task_001",
  "name": "审批",
  "assignee": "user@example.com",
  "processInstanceId": "f6a...",
  "createdAt": "2025-01-01T10:00:00Z",
  "dueDate": null
}

2. 获取任务详情

• GET /api/tasks/{taskId}
• 200 响应: TaskDetail

{
  "id": "task_001",
  "name": "审批",
  "assignee": "user@example.com",
  "processInstanceId": "f6a...",
  "variables": { "approved": null, "comment": null }
}

3. 获取任务表单

• GET /api/tasks/{taskId}/form
• 200 响应: TaskForm

{
  "taskId": "task_001",
  "fields": [
    {"id": "approved", "label": "同意?", "type": "boolean", "required": true},
    {"id": "comment", "label": "意见", "type": "string", "required": false}
  ]
}

4. 完成任务

• POST /api/tasks/{taskId}/complete
• Body: { "variables": object }
• 200 响应: 无（或 { "status": "ok" }）

四、错误模型

• HTTP 400: 参数/校验错误
• HTTP 401: 未授权（如启用鉴权）
• HTTP 404: 资源不存在
• HTTP 409: 冲突（如重名/状态冲突）
• HTTP 500: 服务器错误

错误响应示例：

{ "code": "VALIDATION_ERROR", "message": "name 不能为空", "details": { "field": "name" } }

五、字段/表达式一致性

• 前端提交的所有表达式采用完整 ${...} 字符串；后端按 JUEL 解析
• WorkflowEdge.condition 在转换层映射到 BPMN 的 conditionExpression
• NodeTypeMetadata.fields 与前端表单渲染一一对应；outputSchema 驱动字段映射树