样本中心API接口设计

项目/API接口定义/样本中心提供API接口文档.md

@@ -0,0 +1,644 @@
+# 样本中心对外API接口文档
+
+## 1. 概述
+
+### 1.1 文档目的
+本文档定义样本中心对外提供的API接口规范，供外部系统（如采集系统）接入使用。
+
+### 1.2 基础信息
+| 项目 | 说明 |
+|------|------|
+| Base URL | `https://{host}/api/v1` |
+| 数据格式 | JSON |
+| 字符编码 | UTF-8 |
+| 认证方式 | Bearer Token |
+
+---
+
+## 2. 认证与鉴权
+
+### 2.1 Token 设计方案
+
+采用 **API Key + Secret 签名机制**，外部系统通过以下方式获取访问 Token：
+
+#### 2.1.1 凭证分配
+每个接入系统在样本中心注册后，分配一对凭证：
+- `app_id`：应用唯一标识
+- `app_secret`：应用密钥（仅初始化时展示一次，需妥善保存）
+
+#### 2.1.2 获取访问令牌
+
+**POST /api/v1/auth/token**
+
+| 项目 | 说明 |
+|------|------|
+| Content-Type | application/json |
+
+**请求参数：**
+
+| 参数名 | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| app_id | string | 是 | 应用标识 |
+| app_secret | string | 是 | 应用密钥 |
+
+**请求示例：**
+```json
+{
+  "app_id": "collect_system_001",
+  "app_secret": "sk_xxxxxxxxxxxxxxxx"
+}
+```
+
+**响应参数：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| access_token | string | 访问令牌 |
+| expires_in | integer | 过期时间（秒），默认 7200 |
+| token_type | string | 令牌类型，固定 "Bearer" |
+
+**响应示例：**
+```json
+{
+  "code": "000000",
+  "message": "success",
+  "data": {
+    "access_token": "eyJhbGciOiJIUzI1NiIs...",
+    "expires_in": 7200,
+    "token_type": "Bearer"
+  }
+}
+```
+
+#### 2.1.3 Token 使用
+所有业务接口需在 HTTP Header 中携带 Token：
+```
+Authorization: Bearer {access_token}
+X-App-Id: {app_id}
+```
+
+#### 2.1.4 Token 管理规则
+- Token 有效期 2 小时，过期后需重新获取
+- 支持多 Token 并存，新 Token 获取不影响旧 Token 使用
+- 单 app_id 同时最多持有 3 个有效 Token
+- Token 被吊销后即时失效
+
+---
+
+## 3. 统一响应格式
+
+所有接口返回统一的 JSON 结构：
+
+```json
+{
+  "code": "000000",
+  "message": "success",
+  "data": { ... },
+  "request_id": "req_xxxxxxxxxxxxxxxx"
+}
+```
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| code | string | 状态码，"000000" 表示成功，非 "000000" 表示失败 |
+| message | string | 提示信息 |
+| data | object/array/null | 业务数据 |
+| request_id | string | 请求追踪 ID |
+
+### 3.1 错误码定义
+
+| 错误码 | 说明 |
+|--------|------|
+| 000000 | 成功 |
+| 000400 | 请求参数错误 |
+| 000401 | 认证失败（Token 无效/过期） |
+| 000403 | 权限不足 |
+| 000404 | 资源不存在 |
+| 000429 | 请求频率超限 |
+| 000500 | 服务端内部错误 |
+| 001001 | 知识库不存在 |
+| 001002 | 知识库未启用 |
+| 002001 | 批量入库参数校验失败 |
+| 002002 | 批量入库任务不存在 |
+| 002003 | 批量入库任务数据格式错误 |
+
+---
+
+## 4. 接口详情
+
+### 4.1 知识库列表查询
+
+**GET /api/v1/knowledge-bases**
+
+查询当前应用有权限访问的已启用知识库列表。
+
+**请求参数（Query）：**
+
+| 参数名 | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| page | integer | 否 | 页码，默认 1 |
+| page_size | integer | 否 | 每页条数，默认 20，最大 100 |
+
+**响应参数：**
+
+```json
+{
+  "code": "000000",
+  "message": "success",
+  "data": {
+    "total": 10,
+    "page": 1,
+    "page_size": 20,
+    "items": [
+      {
+        "id": "5138215886300893584",
+        "name": "建设工程知识库",
+        "parent_table": "kb_parent_table_001",
+        "child_table": "kb_child_table_001",
+        "document_count": 1520,
+        "status": 1,
+        "created_at": "2026-05-10T10:30:00Z",
+        "created_by": "admin",
+        "metadata_schema": [
+          {
+            "field_name_cn": "文档编号",
+            "field_name_en": "doc_number",
+            "field_type": "string",
+            "description": "文档的唯一编号"
+          },
+          {
+            "field_name_cn": "发布日期",
+            "field_name_en": "publish_date",
+            "field_type": "date",
+            "description": "文档发布日期"
+          }
+        ]
+      }
+    ]
+  },
+  "request_id": "req_xxxxxxxxxxxxxxxx"
+}
+```
+
+**列表项字段说明：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| id | string | 知识库ID |
+| name | string | 知识库名称 |
+| parent_table | string | 父集合表名 |
+| child_table | string | 子集合表名 |
+| document_count | integer | 文档数量 |
+| status | integer | 状态：1-启用，0-禁用 |
+| created_at | string | 创建时间，ISO 8601 格式 |
+| created_by | string | 创建人 |
+| metadata_schema | array | 元数据字典定义列表 |
+
+**metadata_schema 字段说明：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| field_name_cn | string | 字段中文名称 |
+| field_name_en | string | 字段英文名称 |
+| field_type | string | 字段类型：string/integer/float/date/boolean/array |
+| description | string | 字段描述 |
+
+---
+
+### 4.2 知识库详情查询
+
+**GET /api/v1/knowledge-bases/{id}**
+
+查询指定知识库的详细信息，包括元数据字典定义。
+
+**路径参数：**
+
+| 参数名 | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| id | string | 是 | 知识库ID |
+
+**响应参数：**
+
+```json
+{
+  "code": "000000",
+  "message": "success",
+  "data": {
+    "id": "5138215886300893584",
+    "name": "建设工程知识库",
+    "description": "建设工程相关法规文档",
+    "parent_table": "kb_parent_table_001",
+    "child_table": "kb_child_table_001",
+    "document_count": 1520,
+    "status": 1,
+    "created_at": "2026-05-10T10:30:00Z",
+    "created_by": "admin",
+    "updated_at": "2026-05-15T14:20:00Z",
+    "metadata_schema": [
+      {
+        "field_name_cn": "文档编号",
+        "field_name_en": "doc_number",
+        "field_type": "string",
+        "description": "文档的唯一编号"
+      },
+      {
+        "field_name_cn": "发布日期",
+        "field_name_en": "publish_date",
+        "field_type": "date",
+        "description": "文档发布日期"
+      },
+      {
+        "field_name_cn": "文档来源",
+        "field_name_en": "source",
+        "field_type": "string",
+        "description": "文档来源机构"
+      }
+    ]
+  },
+  "request_id": "req_xxxxxxxxxxxxxxxx"
+}
+```
+
+---
+
+### 4.3 知识库批量入库
+
+**POST /api/v1/knowledge-bases/{kb_id}/batch-import**
+
+提交批量入库任务，系统将片段向量化后存入向量数据库。
+
+**路径参数：**
+
+| 参数名 | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| kb_id | string | 是 | 知识库ID |
+
+**请求体：**
+
+```json
+{
+  "task_no": "IMP202605170001",
+  "callback_url": "https://collect-system.example.com/api/callback/import-result",
+  "parents": [
+    {
+      "index": 0,
+      "parent_id": "5138215886300893584",
+      "hierarchy": "建设工程质量管理条例",
+      "text": "第一条 为了加强对建设工程质量的管理...",
+      "metadata": {
+        "doc_number": "国务院令第279号",
+        "publish_date": "2000-01-30"
+      },
+      "doc_id": "doc_001",
+      "tag_list": ["法规", "质量管理"],
+      "permission": {
+        "visible_roles": ["role_admin", "role_engineer"],
+        "visible_users": ["user_001"]
+      }
+    }
+  ],
+  "children": [
+    {
+      "index": 0,
+      "parent_id": "5138215886300893584",
+      "hierarchy": "第一章 总则",
+      "text": "第一条 为了加强对建设工程质量的管理，保证建设工程质量...",
+      "metadata": {
+        "doc_number": "国务院令第279号",
+        "section": "第一章"
+      },
+      "doc_id": "doc_001",
+      "tag_list": ["法规", "总则"],
+      "permission": {
+        "visible_roles": ["role_admin"]
+      }
+    }
+  ]
+}
+```
+
+**请求参数说明：**
+
+| 参数名 | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| task_no | string | 是 | 入库任务号，由调用方生成，用于记录当前入库任务状态及后续查询进度 |
+| callback_url | string | 否 | 回调地址，任务完成后样本中心将处理结果推送至该地址，不传则不回调 |
+| parents | array | 是 | 父段信息列表 |
+| children | array | 否 | 子段信息列表 |
+
+**parents/children 项字段说明：**
+
+| 参数名 | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| index | integer | 是 | 分片索引号 |
+| parent_id | string | 是 | 父段ID，子段通过此字段关联父段 |
+| hierarchy | string | 否 | 章节信息 |
+| text | string | 是 | 段文本信息 |
+| metadata | object | 否 | 段元数据信息，键值对结构 |
+| doc_id | string | 否 | 文档ID |
+| tag_list | array | 否 | 标签列表 |
+| permission | object | 否 | 权限配置 |
+
+**permission 字段说明：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| visible_roles | array | 可见角色 ID 列表 |
+| visible_users | array | 可见用户 ID 列表 |
+
+**响应参数：**
+
+```json
+{
+  "code": "000000",
+  "message": "success",
+  "data": {
+    "task_id": "task_20260517xxxxxxxx",
+    "status": "pending"
+  },
+  "request_id": "req_xxxxxxxxxxxxxxxx"
+}
+```
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| task_id | string | 任务ID |
+| status | string | 任务状态：pending-待处理 |
+
+---
+
+### 4.4 批量入库任务查询
+
+**GET /api/v1/knowledge-bases/batch-import/{task_id}**
+
+查询批量入库任务的处理状态和结果。
+
+**路径参数：**
+
+| 参数名 | 类型 | 必录 | 说明 |
+|--------|------|------|------|
+| task_id | string | 是 | 入库任务ID |
+
+**响应参数：**
+
+**进行中：**
+```json
+{
+  "code": "000000",
+  "message": "success",
+  "data": {
+    "task_id": "task_20260517xxxxxxxx",
+    "task_no": "IMP202605170001",
+    "status": "processing",
+    "progress": {
+      "total": 100,
+      "processed": 45,
+      "succeeded": 43,
+      "failed": 2
+    },
+    "created_at": "2026-05-17T10:00:00Z",
+    "updated_at": "2026-05-17T10:01:30Z"
+  },
+  "request_id": "req_xxxxxxxxxxxxxxxx"
+}
+```
+
+**已完成：**
+```json
+{
+  "code": "000000",
+  "message": "success",
+  "data": {
+    "task_id": "task_20260517xxxxxxxx",
+    "task_no": "IMP202605170001",
+    "status": "completed",
+    "progress": {
+      "total": 100,
+      "processed": 100,
+      "succeeded": 98,
+      "failed": 2
+    },
+    "created_at": "2026-05-17T10:00:00Z",
+    "completed_at": "2026-05-17T10:05:00Z",
+    "failures": [
+      {
+        "index": 12,
+        "parent_id": "5138215886300893584",
+        "error": "文本内容为空，跳过入库"
+      },
+      {
+        "index": 56,
+        "parent_id": "5138215886300893584",
+        "error": "向量化模型调用超时"
+      }
+    ]
+  },
+  "request_id": "req_xxxxxxxxxxxxxxxx"
+}
+```
+
+**失败：**
+```json
+{
+  "code": "000000",
+  "message": "success",
+  "data": {
+    "task_id": "task_20260517xxxxxxxx",
+    "task_no": "IMP202605170001",
+    "status": "failed",
+    "error": "向量数据库连接异常",
+    "created_at": "2026-05-17T10:00:00Z",
+    "completed_at": "2026-05-17T10:00:05Z"
+  },
+  "request_id": "req_xxxxxxxxxxxxxxxx"
+}
+```
+
+**字段说明：**
+
+| 参数名 | 类型 | 说明 |
+|--------|------|------|
+| task_id | string | 任务ID，系统生成 |
+| task_no | string | 入库任务号，调用方传入 |
+| status | string | 任务状态：pending-待处理，processing-处理中，completed-已完成，failed-失败 |
+| progress | object | 进度信息 |
+| progress.total | integer | 总条数 |
+| progress.processed | integer | 已处理条数 |
+| progress.succeeded | integer | 成功条数 |
+| progress.failed | integer | 失败条数 |
+| failures | array | 失败明细列表 |
+| error | string | 整体失败原因（仅 status=failed 时返回） |
+| created_at | string | 任务创建时间 |
+| updated_at | string | 状态更新时间 |
+| completed_at | string | 任务完成时间 |
+
+---
+
+## 5. 任务状态流转
+
+```
+pending → processing → completed
+                      → failed
+```
+
+| 状态 | 说明 |
+|------|------|
+| pending | 任务已接收，排队等待处理 |
+| processing | 任务正在处理中 |
+| completed | 任务处理完成（可能部分失败） |
+| failed | 任务整体失败，无数据入库 |
+
+---
+
+## 6. 轮询与回调机制
+
+### 6.1 轮询方式
+外部系统提交任务后，通过 **GET /api/v1/knowledge-bases/batch-import/{task_id}** 轮询任务状态。
+
+**建议轮询策略：**
+- 初始间隔 2 秒
+- 每次轮询后间隔 × 1.5，上限 30 秒
+- 任务终态（completed/failed）后停止轮询
+
+### 6.2 回调方式（可选）
+
+外部系统在提交批量入库任务时，若无法主动轮询，可在请求体中传入 `callback_url`。任务完成后样本中心主动向该地址推送处理结果。
+
+**回调请求：** POST {callback_url}
+
+```json
+{
+  "task_id": "task_20260517xxxxxxxx",
+  "task_no": "IMP202605170001",
+  "status": "completed",
+  "kb_id": "5138215886300893584",
+  "progress": {
+    "total": 100,
+    "processed": 100,
+    "succeeded": 98,
+    "failed": 2
+  },
+  "completed_at": "2026-05-17T10:05:00Z"
+}
+```
+
+回调失败时最多重试 3 次，间隔 10s / 30s / 60s。
+
+---
+
+## 7. 限流与配额
+
+| 接口 | 限流规则 |
+|------|----------|
+| 获取 Token | 10 次/分钟/app_id |
+| 知识库列表 | 60 次/分钟/app_id |
+| 知识库详情 | 60 次/分钟/app_id |
+| 批量入库提交 | 20 次/分钟/app_id |
+| 任务查询 | 120 次/分钟/app_id |
+
+超限返回 HTTP 429，Header 中包含限流信息：
+```
+X-RateLimit-Limit: 60
+X-RateLimit-Remaining: 0
+X-RateLimit-Reset: 1715932800
+```
+
+---
+
+## 8. 接口总览
+
+| 序号 | 方法 | 路径 | 说明 |
+|------|------|------|------|
+| 1 | POST | /api/v1/auth/token | 获取访问令牌 |
+| 2 | GET | /api/v1/knowledge-bases | 知识库列表查询 |
+| 3 | GET | /api/v1/knowledge-bases/{id} | 知识库详情查询 |
+| 4 | POST | /api/v1/knowledge-bases/{kb_id}/batch-import | 批量入库提交 |
+| 5 | GET | /api/v1/knowledge-bases/batch-import/{task_id} | 入库任务查询 |
+
+---
+
+## 9. 异步任务表设计
+
+### 9.1 表结构定义
+
+**表名：`t_samp_task_management`**
+
+样本中心异步任务表，用于记录所有异步任务的生命周期。
+
+| 字段名 | 类型 | 说明 |
+|--------|------|------|
+| task_id | varchar(50) | 任务ID，系统自动生成，主键 |
+| task_no | varchar(50) | 任务编号，请求方传入，用于外部追踪 |
+| task_type | varchar(50) | 任务类型，如：bi（批量入库） |
+| task_params | text | 任务参数，JSON 格式存储原始请求参数 |
+| task_source | varchar(50) | 任务来源，枚举定义，如：col（采集系统） |
+| callback_url | varchar(300) | 任务回调地址 |
+| status | varchar(20) | 任务状态，枚举定义 |
+| callback_status | varchar(20) | 任务回调状态，枚举定义 |
+| error_message | varchar(3000) | 任务错误信息 |
+| completed_time | datetime | 任务完成时间 |
+| created_time | datetime | 任务创建时间 |
+| updated_time | datetime | 任务更新时间 |
+
+### 9.2 任务状态枚举
+
+| 状态值 | 说明 |
+|--------|------|
+| pending | 任务已接收，排队等待处理 |
+| processing | 任务正在处理中 |
+| completed | 任务处理完成（可能部分失败） |
+| failed | 任务整体失败，无数据入库 |
+
+### 9.3 回调状态枚举
+
+| 状态值 | 说明 |
+|--------|------|
+| pending | 待处理 |
+| processing | 处理中 |
+| success | 回调成功 |
+| failed | 回调失败 |
+
+### 9.4 任务处理逻辑
+
+1. **任务接收**：批量入库任务接收请求后，先将任务保存到任务表，状态设为 `pending`
+2. **异步处理**：发起异步任务进行知识片段入库处理，同时更新任务表状态为 `processing`
+3. **任务完成**：处理完成后更新任务表状态为 `completed`，记录完成时间
+4. **任务失败**：处理失败时更新任务表状态为 `failed`，同时写入错误信息到 `error_message`
+5. **回调通知**：任务处理完成后，若 `callback_url` 不为空，则发起回调请求，并根据回调结果更新 `callback_status`
+6. **状态查询**：入库任务查询接口直接查询任务表的 `status` 和 `callback_status`
+
+### 9.5 任务类型扩展
+
+任务表通过 `task_type` 字段支持多种任务类型，当前支持：
+
+| task_type | 说明 |
+|-----------|------|
+| bi | 批量入库任务 |
+
+后续可按需扩展其他任务类型（如：批量删除、数据同步等）。
+
+---
+
+## 10. 代码结构说明
+
+### 10.1 Token 认证模块
+
+| 文件路径 | 说明 |
+|----------|------|
+| `src/app/api/v1/token_api_view.py` | Token 接口路由定义，处理 `/api/v1/auth/token` 请求 |
+| `src/app/service/api/token_api_service.py` | Token 业务逻辑，负责凭证校验、Token 签发与过期管理 |
+
+### 10.2 知识库 API 模块
+
+| 文件路径 | 说明 |
+|----------|------|
+| `src/app/api/v1/knowledge_base_api_view.py` | 知识库相关接口路由定义，包含列表查询、详情查询、批量入库、任务查询 |
+| `src/app/service/api/knowledge_base_api_service.py` | 知识库业务逻辑，包含知识库查询、批量入库任务创建、任务状态查询等 |
+
+### 10.3 任务管理模块
+
+| 文件路径 | 说明 |
+|----------|------|
+| `src/app/service/sample_task_management_service.py` | 异步任务管理服务，负责任务的创建、状态更新、回调执行、进度追踪 |
+
+

项目/样本中心对外API接口需求文档.md

@@ -87,4 +87,51 @@
   - 外部系统（如：采集系统）接入样本中心API的token该怎么设计 
   - 外部系统（如：采集系统）是批量异步任务
     - 提交数据的任务ID，返回任务接收状态的接口，任务ID
-    - 处理完成后的任务ID，返回任务处理结果（轮询或回调）
+    - 处理完成后的任务ID，返回任务处理结果（轮询或回调）
+
+
+
+
+### API接口文档设计
+ - 样本中心异步任务表设计
+   - 表名称 t_samp_task_management
+     - 任务表字段定义
+       - 任务ID varchar(50)
+       - 任务编号 varchar(50) 请求传入的任务编号
+       - 任务类型，如：批量入库
+       - 任务参数 text 文本字段，接入任务参数
+       - 任务来源 枚举定义，如：采集系统
+       - 任务回调地址 varchar(300)
+       - 任务状态，枚举定义
+         - | pending | 任务已接收，排队等待处理 |
+         - | processing | 任务正在处理中 |
+         - | completed | 任务处理完成（可能部分失败） |
+         - | failed | 任务整体失败，无数据入库 |
+       - 任务回调状态，枚举定义
+         - 待处理 |
+         - 处理中 |
+         - 回调成功 |
+         - 回调失败 |
+       - 任务错误信息 varchar(3000)
+       - 任务完成时间 datetime
+       - 任务创建时间 datetime
+       - 任务更新时间 datetime
+   - 任务逻辑
+     - src/app/service/sample_task_management_service.py
+ 
+ - 业务逻辑定义
+   - 批量入库任务接收请求后，先保存到任务表（状态为：pending 任务已接收，排队等待处理）
+   - 再发起异步任务进行处理（知识片段入库），并更新任务表状态为：processing 
+   - 任务处理完成，更新任务表状态为：completed
+   - 如果任务处理失败，更新任务表状态为：failed，同时更新错误信息
+   - 任务处理完成后，如果回调地址不为空，则发起回调请求，同时根据回调状态更新任务表回调状态
+   - 入库任务查询接口，直接查询任务表的处理状态
+
+ - API 接口定义
+   - API 接入的token接口定义代码逻辑 
+     - 接口路由 src/app/api/v1/token_api_view.py
+     - 业务逻辑 src/app/service/api/token_api_service.py
+   - API 接口定义代码逻辑 
+     - 接口路由 src/app/api/v1/knowledge_base_api_view.py
+     - 业务逻辑 src/app/service/api/knowledge_base_api_service.py
+