164 lines
4.5 KiB
Markdown
164 lines
4.5 KiB
Markdown
# 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 驱动字段映射树
|