# API 契约

## 通用响应格式

```json
{
    "code": 0,
    "message": "success",
    "data": { ... }
}
```

## 错误码

| 错误码 | HTTP Status | 说明 |
|-------|-------------|------|
| 0 | 200 | 成功 |
| 40001 | 400 | 参数校验失败 |
| 40301 | 403 | 权限不足 |
| 40401 | 404 | 工单不存在 |
| 40901 | 409 | 版本冲突（乐观锁） |
| 50001 | 500 | 服务器内部错误 |

## 工单核心接口

### POST /api/workflow/create

创建工单

**Request:**
```json
{
    "module_code": "rmdc-project-management",
    "workflow_type": "project_detail",
    "title": "项目信息填写-ProjectA",
    "description": "请填写项目详细信息",
    "priority": 3,
    "assignee_id": 123,
    "deadline": "2026-01-15T18:00:00Z",
    "business_payload": {
        "project_id": "proj-001"
    }
}
```

**Response:**
```json
{
    "code": 0,
    "message": "success",
    "data": {
        "workflow_id": "project-20260108100000-admin",
        "status": "created",
        "version": 1,
        "created_at": "2026-01-08T10:00:00Z"
    }
}
```

### POST /api/workflow/detail

获取工单详情

**Request:**
```json
{
    "workflow_id": "project-20260108100000-admin"
}
```

**Response:**
```json
{
    "code": 0,
    "message": "success",
    "data": {
        "id": "project-20260108100000-admin",
        "version": 2,
        "module_code": "rmdc-project-management",
        "workflow_type": "project_detail",
        "status": "in_progress",
        "title": "项目信息填写-ProjectA",
        "creator_id": 1,
        "creator_name": "超级管理员",
        "assignee_id": 123,
        "assignee_name": "张三",
        "current_step": 2,
        "total_steps": 3,
        "steps": [...],
        "history": [...],
        "business_payload": {...},
        "created_at": "2026-01-08T10:00:00Z",
        "updated_at": "2026-01-08T11:30:00Z"
    }
}
```

### POST /api/workflow/status

获取工单状态（轻量）

**Request:**
```json
{
    "workflow_id": "project-20260108100000-admin"
}
```

**Response:**
```json
{
    "code": 0,
    "data": {
        "workflow_id": "project-20260108100000-admin",
        "status": "in_progress",
        "version": 2,
        "updated_at": "2026-01-08T11:30:00Z"
    }
}
```

### POST /api/workflow/transition

状态转换

**Request:**
```json
{
    "workflow_id": "project-20260108100000-admin",
    "version": 2,
    "event": "complete",
    "remark": "项目信息填写完成，提交审核"
}
```

**Response:**
```json
{
    "code": 0,
    "message": "success",
    "data": {
        "workflow_id": "project-20260108100000-admin",
        "from_status": "in_progress",
        "to_status": "pending_review",
        "version": 3
    }
}
```

**版本冲突响应 (409):**
```json
{
    "code": 40901,
    "message": "版本冲突，工单已被其他人修改，请刷新后重试"
}
```

### POST /api/workflow/assign

分配处理人

**Request:**
```json
{
    "workflow_id": "project-20260108100000-admin",
    "version": 1,
    "assignee_id": 123,
    "remark": "分配给张三填写"
}
```

### POST /api/workflow/delegate

委派给他人

**Request:**
```json
{
    "workflow_id": "microservice-20260108150000-user",
    "version": 3,
    "delegate_to_id": 456,
    "remark": "委派给李四执行更新"
}
```

### POST /api/workflow/revoke

撤销工单

**Request:**
```json
{
    "workflow_id": "user-20260108090000-zhangsan",
    "version": 2,
    "confirm": true,
    "remark": "用户取消注册"
}
```

### POST /api/workflow/callback

业务模块回调

**Request:**
```json
{
    "workflow_id": "microservice-20260108150000-user",
    "callback_type": "execute_complete",
    "result": "success",
    "result_payload": {
        "execute_time": "2026-01-08T15:35:00Z",
        "new_pod_count": 3
    }
}
```

**callback_type 枚举:**
- `execute_start` - 开始执行
- `execute_complete` - 执行完成
- `execute_failed` - 执行失败
- `monitor_healthy` - 监控健康
- `monitor_unhealthy` - 监控异常
- `rollback_complete` - 回滚完成

## 工单列表与查询

### POST /api/workflow/list

工单列表（分页）

**Request:**
```json
{
    "page": 1,
    "page_size": 20,
    "workflow_type": "project_detail",
    "status": ["in_progress", "pending_review"],
    "creator_id": 1,
    "assignee_id": 123,
    "start_time": "2026-01-01T00:00:00Z",
    "end_time": "2026-01-31T23:59:59Z"
}
```

**Response:**
```json
{
    "code": 0,
    "data": {
        "total": 50,
        "page": 1,
        "page_size": 20,
        "list": [...]
    }
}
```

### POST /api/workflow/my/created

我发起的工单

### POST /api/workflow/my/assigned

分配给我的工单

### POST /api/workflow/my/pending

待我处理的工单

### POST /api/workflow/history

工单历史记录

**Request:**
```json
{
    "workflow_id": "project-20260108100000-admin"
}
```

**Response:**
```json
{
    "code": 0,
    "data": {
        "history": [
            {
                "id": 1,
                "from_status": "created",
                "to_status": "assigned",
                "event": "assign",
                "operator_name": "超级管理员",
                "remark": "分配给张三填写",
                "created_at": "2026-01-08T10:05:00Z"
            }
        ]
    }
}
```

### POST /api/workflow/diagram

获取工单流程图

**Request:**
```json
{
    "workflow_id": "project-20260108100000-admin"
}
```

**Response:**
```json
{
    "code": 0,
    "data": {
        "mermaid_code": "stateDiagram-v2\n    direction LR\n    [*] --> created: 创建项目\n    ...",
        "current_node": "pending_review",
        "nodes": [
            {
                "id": "created",
                "label": "创建项目",
                "status": "completed",
                "assignee": "超级管理员",
                "completed_at": "2026-01-08T10:00:00Z"
            },
            {
                "id": "in_progress",
                "label": "填写信息",
                "status": "completed",
                "assignee": "张三",
                "completed_at": "2026-01-08T14:00:00Z"
            },
            {
                "id": "pending_review",
                "label": "待审核",
                "status": "current",
                "assignee": "超级管理员"
            }
        ]
    }
}
```

## 权限管理接口（仅 SuperAdmin）

### POST /api/workflow/permission/grant

授予权限

### POST /api/workflow/permission/revoke

撤销权限

### POST /api/workflow/permission/list

权限列表
