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条全部通过,项目结构确认
This commit is contained in:
97
specs/001-label-backend-spec/contracts/extraction.md
Normal file
97
specs/001-label-backend-spec/contracts/extraction.md
Normal file
@@ -0,0 +1,97 @@
|
||||
# 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`: 驳回原因不能为空
|
||||
Reference in New Issue
Block a user