feat(plan): 生成 label_backend 完整实施规划文档

Phase 0：research.md（10项技术决策，无需澄清项） Phase 1：data-model.md（11张表+Redis结构），contracts/（8个模块API契约），quickstart.md（Docker Compose启动+流水线验证） plan.md：宪章11条全部通过，项目结构确认
2026-04-09 12:27:16 +08:00
parent 0891ae188d
commit 4054a1133b
15 changed files with 1741 additions and 22 deletions
--- a/specs/001-label-backend-spec/contracts/tasks.md
+++ b/specs/001-label-backend-spec/contracts/tasks.md
@@ -0,0 +1,150 @@
+# 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, ...}}`