151 lines
3.3 KiB
Markdown
151 lines
3.3 KiB
Markdown
|
# API 契约：任务管理
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## GET /api/tasks/pool
|
|||
|
|
|
|||
|
|
**权限**: ANNOTATOR
|
|||
|
|
**描述**: 查看可领取任务池。角色过滤规则：
|
|||
|
|
- ANNOTATOR：仅返回 EXTRACTION 阶段、status=UNCLAIMED 的任务
|
|||
|
|
- REVIEWER/ADMIN：仅返回 SUBMITTED 状态（待审批队列）的任务
|
|||
|
|
|
|||
|
|
**查询参数**: `page`（默认 1）、`pageSize`（默认 20）
|
|||
|
|
|
|||
|
|
**响应** `200`:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": "SUCCESS",
|
|||
|
|
"data": {
|
|||
|
|
"items": [
|
|||
|
|
{
|
|||
|
|
"id": 101,
|
|||
|
|
"sourceId": 50,
|
|||
|
|
"sourceType": "TEXT",
|
|||
|
|
"phase": "EXTRACTION",
|
|||
|
|
"status": "UNCLAIMED",
|
|||
|
|
"createdAt": "2026-04-09T10:00:00"
|
|||
|
|
}
|
|||
|
|
],
|
|||
|
|
"total": 30,
|
|||
|
|
"page": 1,
|
|||
|
|
"pageSize": 20
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## GET /api/tasks/pending-review
|
|||
|
|
|
|||
|
|
**权限**: REVIEWER
|
|||
|
|
**描述**: REVIEWER 专属审批入口，查看 status=SUBMITTED 的任务列表
|
|||
|
|
|
|||
|
|
**查询参数**: `page`、`pageSize`、`phase`（可选，EXTRACTION / QA_GENERATION）
|
|||
|
|
|
|||
|
|
**响应**: 同 `/api/tasks/pool` 结构
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## POST /api/tasks/{id}/claim
|
|||
|
|
|
|||
|
|
**权限**: ANNOTATOR
|
|||
|
|
**描述**: 领取任务（双重并发保障：Redis SET NX + DB 乐观约束）
|
|||
|
|
|
|||
|
|
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
|||
|
|
**失败**:
|
|||
|
|
- `409` `TASK_CLAIMED`: 任务已被他人领取
|
|||
|
|
- `404` `TASK_NOT_FOUND`: 任务不存在
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## POST /api/tasks/{id}/unclaim
|
|||
|
|
|
|||
|
|
**权限**: ANNOTATOR（且为任务持有者）
|
|||
|
|
**描述**: 放弃任务，退回任务池（status: IN_PROGRESS → UNCLAIMED）
|
|||
|
|
|
|||
|
|
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
|||
|
|
**失败**: `403` `NOT_TASK_OWNER`: 非任务持有者
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## GET /api/tasks/mine
|
|||
|
|
|
|||
|
|
**权限**: ANNOTATOR
|
|||
|
|
**描述**: 查询当前用户领取的任务（含 IN_PROGRESS、SUBMITTED、REJECTED 三种状态）
|
|||
|
|
|
|||
|
|
**查询参数**: `page`、`pageSize`、`status`（可选过滤）
|
|||
|
|
|
|||
|
|
**响应**: 同任务列表结构，含 `rejectReason` 字段（REJECTED 状态时非空）
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## POST /api/tasks/{id}/reclaim
|
|||
|
|
|
|||
|
|
**权限**: ANNOTATOR
|
|||
|
|
**描述**: 重领被驳回的任务（status 必须为 REJECTED 且 claimedBy = 当前用户，流转 REJECTED → IN_PROGRESS）
|
|||
|
|
|
|||
|
|
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
|||
|
|
**失败**:
|
|||
|
|
- `403` `NOT_TASK_OWNER`: 非原持有者
|
|||
|
|
- `409` `INVALID_STATE`: 任务状态不为 REJECTED
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## GET /api/tasks/{id}
|
|||
|
|
|
|||
|
|
**权限**: ANNOTATOR
|
|||
|
|
**描述**: 查看任务详情（含驳回原因、历史记录摘要）
|
|||
|
|
|
|||
|
|
**响应** `200`:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"code": "SUCCESS",
|
|||
|
|
"data": {
|
|||
|
|
"id": 101,
|
|||
|
|
"sourceId": 50,
|
|||
|
|
"phase": "EXTRACTION",
|
|||
|
|
"status": "IN_PROGRESS",
|
|||
|
|
"claimedBy": 1,
|
|||
|
|
"claimedAt": "2026-04-09T10:05:00",
|
|||
|
|
"rejectReason": null,
|
|||
|
|
"historyCount": 2
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## GET /api/tasks
|
|||
|
|
|
|||
|
|
**权限**: ADMIN
|
|||
|
|
**描述**: 查询全部任务（支持过滤，分页）
|
|||
|
|
|
|||
|
|
**查询参数**: `page`、`pageSize`、`phase`、`status`、`claimedBy`、`sourceId`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## PUT /api/tasks/{id}/reassign
|
|||
|
|
|
|||
|
|
**权限**: ADMIN
|
|||
|
|
**描述**: 强制转移任务归属（status 保持 IN_PROGRESS，仅 claimedBy 变更）
|
|||
|
|
|
|||
|
|
**请求体**: `{"newOwnerId": 5, "reason": "原持有者长期未操作"}`
|
|||
|
|
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
|||
|
|
|
|||
|
|
---
|
|||
|
|
|
|||
|
|
## POST /api/tasks
|
|||
|
|
|
|||
|
|
**权限**: ADMIN
|
|||
|
|
**描述**: 为指定资料创建 EXTRACTION 任务
|
|||
|
|
|
|||
|
|
**请求体**:
|
|||
|
|
```json
|
|||
|
|
{
|
|||
|
|
"sourceId": 50,
|
|||
|
|
"taskType": "AI_ASSISTED",
|
|||
|
|
"aiModel": "glm-4"
|
|||
|
|
}
|
|||
|
|
```
|
|||
|
|
**响应** `201`: `{"code": "SUCCESS", "data": {"id": 101, ...}}`
|