4054a1133b
Phase 0：research.md（10项技术决策，无需澄清项） Phase 1：data-model.md（11张表+Redis结构），contracts/（8个模块API契约），quickstart.md（Docker Compose启动+流水线验证） plan.md：宪章11条全部通过，项目结构确认
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, ...}}`
|