# 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
```json
{
  "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 }
```json
{
  "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
```json
{
  "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 }
```json
{
  "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
```json
{
  "id": "task_001",
  "name": "审批",
  "assignee": "user@example.com",
  "processInstanceId": "f6a...",
  "variables": { "approved": null, "comment": null }
}
```

3) 获取任务表单
- GET /api/tasks/{taskId}/form
- 200 响应: TaskForm
```json
{
  "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: 服务器错误  

错误响应示例：
```json
{ "code": "VALIDATION_ERROR", "message": "name 不能为空", "details": { "field": "name" } }
```

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