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:
87
specs/001-label-backend-spec/contracts/video.md
Normal file
87
specs/001-label-backend-spec/contracts/video.md
Normal file
@@ -0,0 +1,87 @@
|
||||
# API 契约:视频处理
|
||||
|
||||
---
|
||||
|
||||
## POST /api/video/process
|
||||
|
||||
**权限**: ADMIN
|
||||
**描述**: 为已上传的视频资料创建异步处理任务
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"sourceId": 50,
|
||||
"jobType": "FRAME_EXTRACT",
|
||||
"params": {
|
||||
"frameInterval": 30,
|
||||
"mode": "FRAME"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
jobType 可选值:`FRAME_EXTRACT`(帧提取)、`VIDEO_TO_TEXT`(片段转文字)
|
||||
|
||||
**响应** `201`:
|
||||
```json
|
||||
{
|
||||
"code": "SUCCESS",
|
||||
"data": {
|
||||
"jobId": 200,
|
||||
"sourceId": 50,
|
||||
"jobType": "FRAME_EXTRACT",
|
||||
"status": "PENDING"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /api/video/jobs/{jobId}
|
||||
|
||||
**权限**: ADMIN
|
||||
**描述**: 查询视频处理任务状态
|
||||
|
||||
**响应** `200`:
|
||||
```json
|
||||
{
|
||||
"code": "SUCCESS",
|
||||
"data": {
|
||||
"id": 200,
|
||||
"status": "RUNNING",
|
||||
"processedUnits": 15,
|
||||
"totalUnits": 50,
|
||||
"retryCount": 0,
|
||||
"errorMessage": null,
|
||||
"startedAt": "2026-04-09T10:05:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## POST /api/video/jobs/{jobId}/reset
|
||||
|
||||
**权限**: ADMIN
|
||||
**描述**: 手动重置 FAILED 状态的任务为 PENDING,允许重新触发(FAILED → PENDING 不在自动状态机中)
|
||||
|
||||
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
||||
**失败**: `409` `INVALID_STATE`: 任务状态不为 FAILED
|
||||
|
||||
---
|
||||
|
||||
## POST /api/video/callback(内部接口)
|
||||
|
||||
**权限**: AI 服务内部调用(IP 白名单 / 服务密钥)
|
||||
**描述**: AI 服务回调,通知视频处理结果(幂等:重复成功回调静默忽略)
|
||||
|
||||
**请求体**:
|
||||
```json
|
||||
{
|
||||
"jobId": 200,
|
||||
"success": true,
|
||||
"outputPath": "frames/50/",
|
||||
"errorMessage": null
|
||||
}
|
||||
```
|
||||
|
||||
**响应** `200`: `{"code": "SUCCESS", "data": null}`
|
||||
Reference in New Issue
Block a user