doc:提供外部API接口文档

文档/对外提供API接口文档/标注平台（外部）API接口文档.md

@@ -0,0 +1,504 @@
+# 标注平台对外 API 接口文档
+
+> 版本：v1.0
+> 更新日期：2026-05-20
+> 基础 URL：`http://{host}:{port}`（部署后由标注平台提供具体地址）
+
+---
+
+## 1. 快速开始
+
+### 1.1 接入流程
+
+1. 向标注平台申请接入，获取 `app_id` 和 `app_secret`
+2. 使用签名算法获取 Access Token
+3. 携带 Token 调用业务接口
+
+### 1.2 所有接口统一前缀
+
+```
+/api/v1/open
+```
+
+### 1.3 统一响应格式
+
+所有接口返回如下 JSON 结构：
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": { ... }
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `code` | int | 业务状态码，`0` 表示成功，非 `0` 表示失败 |
+| `message` | string | 提示信息 |
+| `data` | object | 业务数据，失败时为 `null` |
+
+---
+
+## 2. 认证机制
+
+### 2.1 凭证说明
+
+接入标注平台后，会分配一对凭证：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `app_id` | string | 应用唯一标识 |
+| `app_secret` | string | 应用密钥，**仅在创建时展示一次，请妥善保存** |
+
+### 2.2 签名算法
+
+每次请求获取 Token 时，需使用 HMAC-SHA256 对请求参数签名：
+
+```
+signature = HMAC-SHA256(
+    key = app_secret,
+    message = app_id + timestamp + nonce
+)
+```
+
+参数说明：
+
+| 参数 | 说明 |
+|------|------|
+| `timestamp` | 当前 Unix 时间戳（秒），与服务器时间差不能超过 5 分钟 |
+| `nonce` | 16 位随机字符串，每次请求不同，用于防重放 |
+| `signature` | 十六进制编码的签名结果 |
+
+---
+
+## 3. 接口列表
+
+| 序号 | 方法 | 路径 | 说明 | 认证方式 |
+|------|------|------|------|----------|
+| 1 | POST | `/api/v1/open/auth/token` | 获取 Access Token | API Key 签名 |
+| 2 | POST | `/api/v1/open/auth/refresh` | 刷新 Access Token | Bearer Token |
+| 3 | GET | `/api/v1/open/projects` | 查询项目列表 | Bearer Token |
+| 4 | GET | `/api/v1/open/projects/{project_id}` | 查询项目详情 | Bearer Token |
+| 5 | POST | `/api/v1/open/projects/{project_id}/datasets/download` | 数据集下载 | Bearer Token |
+| 6 | GET | `/api/v1/open/datasets/downloads/{download_token}` | 获取下载文件 | Bearer Token |
+
+---
+
+## 4. 接口详情
+
+### 4.1 获取 Access Token
+
+**请求**
+
+```
+POST /api/v1/open/auth/token
+```
+
+**请求头**
+
+| Header | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| `X-Api-Key` | string | 是 | 申请的 `app_id` |
+| `X-Signature` | string | 是 | HMAC-SHA256 签名（十六进制） |
+| `X-Timestamp` | string | 是 | Unix 时间戳（秒） |
+| `X-Nonce` | string | 是 | 16 位随机字符串 |
+
+**请求体**：无
+
+**响应示例**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "access_token": "eyJhbGciOiJIUzI1NiIs...",
+    "token_type": "Bearer",
+    "expires_in": 7200
+  }
+}
+```
+
+**错误码**
+
+| HTTP 状态码 | error_code | 说明 |
+|-------------|-----------|------|
+| 401 | INVALID_API_KEY | app_id 不存在 |
+| 401 | APP_DISABLED | 应用已被禁用 |
+| 401 | INVALID_SIGNATURE | 签名验证失败 |
+| 401 | TIMESTAMP_EXPIRED | 时间戳过期（超过 5 分钟） |
+| 401 | NONCE_USED | Nonce 已被使用 |
+
+---
+
+### 4.2 刷新 Access Token
+
+**请求**
+
+```
+POST /api/v1/open/auth/refresh
+```
+
+**请求头**
+
+| Header | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| `Authorization` | string | 是 | `Bearer {access_token}` |
+
+**请求体**：无
+
+**响应示例**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "access_token": "eyJhbGciOiJIUzI1NiIs...",
+    "token_type": "Bearer",
+    "expires_in": 7200
+  }
+}
+```
+
+---
+
+### 4.3 查询项目列表
+
+**请求**
+
+```
+GET /api/v1/open/projects
+```
+
+**请求头**
+
+| Header | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| `Authorization` | string | 是 | `Bearer {access_token}` |
+
+**查询参数**
+
+| 参数 | 类型 | 必录 | 说明 |
+|------|------|------|------|
+| `name` | string | 否 | 项目名称（模糊匹配） |
+| `type` | string | 否 | 项目类型：`image`（图片）/ `text`（文本） |
+| `status` | string | 否 | 项目状态筛选 |
+| `page` | int | 否 | 页码，默认 1 |
+| `page_size` | int | 否 | 每页数量，默认 20，最大 100 |
+
+**响应示例**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "items": [
+      {
+        "project_id": "proj_abc123def456",
+        "project_name": "商品图片分类标注",
+        "description": "对电商平台商品图片进行分类标注",
+        "project_type": "image",
+        "task_type": "image_classification",
+        "status": "in_progress",
+        "created_by": "admin",
+        "created_at": "2026-05-10T10:30:00",
+        "updated_at": "2026-05-15T14:20:00",
+        "task_count": 500,
+        "completed_task_count": 350
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "page_size": 20,
+    "total_pages": 1,
+    "has_next": false,
+    "has_prev": false
+  }
+}
+```
+
+**字段说明**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `project_id` | string | 项目唯一标识 |
+| `project_name` | string | 项目名称 |
+| `description` | string | 项目描述 |
+| `project_type` | string | 项目类型：`image`（图片）/ `text`（文本） |
+| `task_type` | string | 具体任务类型（见下方映射表） |
+| `status` | string | 项目状态：`draft` / `configuring` / `ready` / `in_progress` / `completed` |
+| `created_by` | string | 项目创建人用户名 |
+| `created_at` | string | 创建时间（ISO 8601） |
+| `updated_at` | string | 最后更新时间（ISO 8601） |
+| `task_count` | int | 总任务数 |
+| `completed_task_count` | int | 已完成任务数 |
+
+**任务类型映射表**
+
+| `task_type` | `project_type` | 说明 |
+|-------------|---------------|------|
+| `text_classification` | `text` | 文本分类 |
+| `ner` | `text` | 命名实体识别 |
+| `image_classification` | `image` | 图片分类 |
+| `object_detection` | `image` | 目标检测 |
+| `polygon` | `image` | 多边形标注 |
+
+---
+
+### 4.4 查询项目详情
+
+**请求**
+
+```
+GET /api/v1/open/projects/{project_id}
+```
+
+**路径参数**
+
+| 参数 | 类型 | 必录 | 说明 |
+|------|------|------|------|
+| `project_id` | string | 是 | 项目 ID |
+
+**请求头**
+
+| Header | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| `Authorization` | string | 是 | `Bearer {access_token}` |
+
+**响应示例**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "project_id": "proj_abc123def456",
+    "project_name": "商品图片分类标注",
+    "description": "对电商平台商品图片进行分类标注",
+    "project_type": "image",
+    "task_type": "image_classification",
+    "status": "in_progress",
+    "created_by": "admin",
+    "created_at": "2026-05-10T10:30:00",
+    "updated_at": "2026-05-15T14:20:00",
+    "task_count": 500,
+    "completed_task_count": 350,
+    "assigned_task_count": 500,
+    "completion_percentage": 70.0
+  }
+}
+```
+
+**错误码**
+
+| HTTP 状态码 | error_code | 说明 |
+|-------------|-----------|------|
+| 404 | PROJECT_NOT_FOUND | 项目不存在 |
+
+---
+
+### 4.5 数据集下载
+
+**请求**
+
+```
+POST /api/v1/open/projects/{project_id}/datasets/download
+```
+
+**路径参数**
+
+| 参数 | 类型 | 必录 | 说明 |
+|------|------|------|------|
+| `project_id` | string | 是 | 项目 ID |
+
+**请求头**
+
+| Header | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| `Authorization` | string | 是 | `Bearer {access_token}` |
+
+**请求体**
+
+| 参数 | 类型 | 必录 | 说明 |
+|------|------|------|------|
+| `format` | string | 是 | 数据集格式（见下方格式说明） |
+| `completed_only` | boolean | 否 | 是否只导出已完成的任务，默认 `true` |
+
+**支持的数据集格式**
+
+| `format` 值 | 数据类型 | 格式说明 |
+|-------------|---------|---------|
+| `alpaca` | 文本 | Alpaca 指令微调格式 |
+| `sharegpt` | 文本 | ShareGPT 对话格式 |
+| `json` | 图片 | 平台原生 JSON 格式 |
+| `csv` | 图片 | CSV 表格格式 |
+| `coco` | 图片 | COCO 目标检测格式 |
+| `yolo` | 图片 | YOLO 目标检测格式 |
+| `pascal_voc` | 图片 | PascalVOC XML 格式 |
+
+**请求示例**
+
+```json
+{
+  "format": "coco",
+  "completed_only": true
+}
+```
+
+**响应示例**
+
+```json
+{
+  "code": 0,
+  "message": "success",
+  "data": {
+    "project_id": "proj_abc123def456",
+    "format": "coco",
+    "total_exported": 350,
+    "file_url": "/api/v1/open/datasets/downloads/dl_abc123",
+    "file_name": "proj_abc123def456_coco_20260517_143000.json",
+    "file_size": 2048576,
+    "expires_at": "2026-05-17T16:30:00",
+    "status": "completed"
+  }
+}
+```
+
+**字段说明**
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `project_id` | string | 项目 ID |
+| `format` | string | 导出格式 |
+| `total_exported` | int | 导出的任务数量 |
+| `file_url` | string | 文件下载链接（相对路径，需拼接基础 URL） |
+| `file_name` | string | 文件名 |
+| `file_size` | int | 文件大小（字节） |
+| `expires_at` | string | 下载链接过期时间（ISO 8601），2 小时后过期 |
+| `status` | string | 导出状态：`completed` / `failed` |
+
+**错误码**
+
+| HTTP 状态码 | error_code | 说明 |
+|-------------|-----------|------|
+| 400 | INVALID_FORMAT | 不支持的导出格式 |
+| 400 | FORMAT_NOT_COMPATIBLE | 格式与项目类型不兼容 |
+| 404 | PROJECT_NOT_FOUND | 项目不存在 |
+| 404 | NO_DATA_AVAILABLE | 项目中没有可导出的数据 |
+| 500 | EXPORT_FAILED | 导出失败 |
+
+---
+
+### 4.6 获取下载文件
+
+**请求**
+
+```
+GET /api/v1/open/datasets/downloads/{download_token}
+```
+
+拿到 4.5 接口返回的 `file_url` 后，调用此接口下载实际文件。
+
+**路径参数**
+
+| 参数 | 类型 | 必录 | 说明 |
+|------|------|------|------|
+| `download_token` | string | 是 | 下载令牌（从 4.5 接口返回的 `file_url` 中提取） |
+
+**请求头**
+
+| Header | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| `Authorization` | string | 是 | `Bearer {access_token}` |
+
+**响应**
+
+- `Content-Type`: `application/octet-stream` 或对应格式的 MIME type
+- `Content-Disposition`: `attachment; filename="..."`
+- 响应体为实际文件内容
+
+**错误码**
+
+| HTTP 状态码 | error_code | 说明 |
+|-------------|-----------|------|
+| 410 | DOWNLOAD_EXPIRED | 下载链接已过期 |
+| 404 | NOT_FOUND | 下载资源不存在 |
+
+---
+
+## 5. 错误码汇总
+
+### 5.1 通用错误码
+
+| code | error_code | HTTP 状态码 | 说明 |
+|------|-----------|------------|------|
+| 0 | SUCCESS | 200 | 请求成功 |
+| 1000 | INTERNAL_ERROR | 500 | 服务器内部错误 |
+| 1001 | INVALID_REQUEST | 400 | 请求参数无效 |
+| 1002 | UNAUTHORIZED | 401 | 未认证或认证过期 |
+
+### 5.2 认证错误码
+
+| code | error_code | HTTP 状态码 | 说明 |
+|------|-----------|------------|------|
+| 2001 | INVALID_API_KEY | 401 | app_id 不存在 |
+| 2002 | APP_DISABLED | 401 | 应用已被禁用 |
+| 2003 | INVALID_SIGNATURE | 401 | 签名验证失败 |
+| 2004 | TIMESTAMP_EXPIRED | 401 | 时间戳过期 |
+| 2005 | NONCE_USED | 401 | Nonce 已被使用 |
+| 2006 | TOKEN_EXPIRED | 401 | Access Token 已过期 |
+| 2007 | TOKEN_INVALID | 401 | Access Token 无效 |
+
+### 5.3 业务错误码
+
+| code | error_code | HTTP 状态码 | 说明 |
+|------|-----------|------------|------|
+| 3001 | PROJECT_NOT_FOUND | 404 | 项目不存在 |
+| 3002 | INVALID_FORMAT | 400 | 不支持的导出格式 |
+| 3003 | FORMAT_NOT_COMPATIBLE | 400 | 格式与项目类型不兼容 |
+| 3004 | NO_DATA_AVAILABLE | 404 | 项目中没有可导出的数据 |
+| 3005 | EXPORT_FAILED | 500 | 导出失败 |
+| 3006 | DOWNLOAD_EXPIRED | 410 | 下载链接已过期 |
+
+---
+
+## 6. 调用示例
+
+### 6.1 curl 示例
+
+```bash
+# 1. 获取 Token
+curl -X POST http://localhost:8003/api/v1/open/auth/token \
+  -H "X-Api-Key: app_id_xxx" \
+  -H "X-Signature: abc123..." \
+  -H "X-Timestamp: 1716000000" \
+  -H "X-Nonce: a1b2c3d4e5f6g7h8"
+
+# 2. 查询项目列表
+curl -X GET "http://localhost:8003/api/v1/open/projects?page=1&page_size=20" \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
+
+# 3. 下载数据集
+curl -X POST http://localhost:8003/api/v1/open/projects/proj_xxx/datasets/download \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
+  -H "Content-Type: application/json" \
+  -d '{"format": "coco", "completed_only": true}'
+
+# 4. 下载文件
+curl -X GET http://localhost:8003/api/v1/open/datasets/downloads/dl_abc123 \
+  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
+```
+
+---
+
+
+## 7. 注意事项
+
+1. **Token 有效期**：Access Token 默认 2 小时过期，过期后需重新通过签名获取
+2. **下载链接有效期**：数据集下载接口返回的 `file_url` 2 小时后过期，请及时下载
+3. **Nonce 唯一性**：每次请求的 `nonce` 必须不同，重复使用会被拒绝
+4. **时间同步**：请求时间戳与服务器时间差不能超过 5 分钟，请确保客户端时钟准确
+5. **格式兼容**：文本项目只能使用 `alpaca` / `sharegpt` 格式，图片项目只能使用 `json` / `csv` / `coco` / `yolo` / `pascal_voc` 格式