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:
96
specs/001-label-backend-spec/contracts/source.md
Normal file
96
specs/001-label-backend-spec/contracts/source.md
Normal file
@@ -0,0 +1,96 @@
|
||||
# API 契约:资料管理
|
||||
|
||||
---
|
||||
|
||||
## POST /api/source/upload
|
||||
|
||||
**权限**: UPLOADER
|
||||
**描述**: 上传文件,创建 source_data 记录,文件字节流写入 RustFS
|
||||
|
||||
**请求**: `multipart/form-data`,字段:`file`(必填)、`dataType`(TEXT / IMAGE / VIDEO)
|
||||
|
||||
**响应** `201`:
|
||||
```json
|
||||
{
|
||||
"code": "SUCCESS",
|
||||
"data": {
|
||||
"id": 50,
|
||||
"fileName": "document.txt",
|
||||
"dataType": "TEXT",
|
||||
"fileSize": 204800,
|
||||
"status": "PENDING",
|
||||
"createdAt": "2026-04-09T10:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**失败**:
|
||||
- `400` `INVALID_TYPE`: 不支持的资料类型
|
||||
- `400` `FILE_EMPTY`: 文件为空
|
||||
|
||||
---
|
||||
|
||||
## GET /api/source/list
|
||||
|
||||
**权限**: UPLOADER
|
||||
**描述**: 分页查询资料列表。UPLOADER 只见自己上传的资料;ADMIN 见本公司全部资料
|
||||
|
||||
**查询参数**: `page`(默认 1)、`pageSize`(默认 20)、`dataType`(可选)、`status`(可选)
|
||||
|
||||
**响应** `200`:
|
||||
```json
|
||||
{
|
||||
"code": "SUCCESS",
|
||||
"data": {
|
||||
"items": [
|
||||
{
|
||||
"id": 50,
|
||||
"fileName": "document.txt",
|
||||
"dataType": "TEXT",
|
||||
"status": "PENDING",
|
||||
"uploaderId": 1,
|
||||
"createdAt": "2026-04-09T10:00:00"
|
||||
}
|
||||
],
|
||||
"total": 120,
|
||||
"page": 1,
|
||||
"pageSize": 20
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## GET /api/source/{id}
|
||||
|
||||
**权限**: UPLOADER
|
||||
**描述**: 查看资料详情,含 RustFS 预签名临时下载链接(有效期 15 分钟)
|
||||
|
||||
**响应** `200`:
|
||||
```json
|
||||
{
|
||||
"code": "SUCCESS",
|
||||
"data": {
|
||||
"id": 50,
|
||||
"dataType": "TEXT",
|
||||
"fileName": "document.txt",
|
||||
"fileSize": 204800,
|
||||
"status": "EXTRACTING",
|
||||
"presignedUrl": "https://rustfs.example.com/...",
|
||||
"parentSourceId": null,
|
||||
"createdAt": "2026-04-09T10:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DELETE /api/source/{id}
|
||||
|
||||
**权限**: ADMIN
|
||||
**描述**: 删除资料(同时删除 RustFS 文件及元数据)
|
||||
|
||||
**前置条件**: 资料状态为 PENDING(不允许删除已进入流水线的资料)
|
||||
|
||||
**响应** `204`: 无响应体
|
||||
**失败**: `409` `SOURCE_IN_PIPELINE`: 资料已进入标注流程,不可删除
|
||||
Reference in New Issue
Block a user