# 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, ...}}`