# API 契约：提取阶段标注工作台

---

## GET /api/extraction/{taskId}

**权限**: ANNOTATOR（且为任务持有者）  
**描述**: 获取当前提取结果（含 AI 预标注候选，供人工编辑）

**响应** `200`:
```json
{
  "code": "SUCCESS",
  "data": {
    "taskId": 101,
    "sourceType": "TEXT",
    "sourceFilePath": "text/202604/50.txt",
    "isFinal": false,
    "resultJson": {
      "items": [
        {
          "subject": "北京",
          "predicate": "是...首都",
          "object": "中国",
          "sourceText": "北京是中国的首都",
          "startOffset": 0,
          "endOffset": 8
        }
      ]
    }
  }
}
```

---

## PUT /api/extraction/{taskId}

**权限**: ANNOTATOR（且为任务持有者）  
**描述**: 更新提取结果（**整体 JSONB 覆盖，PUT 语义，禁止局部 PATCH**）

**请求体**:
```json
{
  "items": [
    {
      "subject": "北京",
      "predicate": "是...首都",
      "object": "中国",
      "sourceText": "北京是中国的首都",
      "startOffset": 0,
      "endOffset": 8
    }
  ]
}
```

**响应** `200`: `{"code": "SUCCESS", "data": null}`  
**失败**: `400` `INVALID_JSON`: 提交的 JSON 格式不合法

---

## POST /api/extraction/{taskId}/submit

**权限**: ANNOTATOR（且为任务持有者）  
**描述**: 提交提取结果，任务状态 IN_PROGRESS → SUBMITTED，进入审批队列

**响应** `200`: `{"code": "SUCCESS", "data": null}`  
**失败**: `409` `INVALID_STATE`: 任务当前状态不允许提交

---

## POST /api/extraction/{taskId}/approve

**权限**: REVIEWER  
**描述**: 审批通过。**两阶段操作**：
1. 同步（同一事务）：`annotation_result.is_final = true`，任务状态 SUBMITTED → APPROVED，写任务历史
2. 异步（事务提交后）：AI 生成候选问答对 → 写 training_dataset → 创建 QA_GENERATION 任务 → source_data 状态推进

**响应** `200`: `{"code": "SUCCESS", "data": null}`  
**失败**:
- `403` `SELF_REVIEW_FORBIDDEN`: 不允许审批自己提交的任务
- `409` `INVALID_STATE`: 任务状态不为 SUBMITTED

---

## POST /api/extraction/{taskId}/reject

**权限**: REVIEWER  
**描述**: 驳回提取结果，任务状态 SUBMITTED → REJECTED，标注员可重领

**请求体**: `{"reason": "三元组边界不准确，请重新标注"}`  
**响应** `200`: `{"code": "SUCCESS", "data": null}`  
**失败**:
- `403` `SELF_REVIEW_FORBIDDEN`: 不允许驳回自己提交的任务
- `409` `INVALID_STATE`: 任务状态不为 SUBMITTED
- `400` `REASON_REQUIRED`: 驳回原因不能为空