# 样本中心对外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. 接口总览

| 序号 | 方法 | 路径 | 说明 |
|------|------|------|------|
| 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`**

样本中心异步任务表，用于记录所有异步任务的生命周期。


### 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 | 批量入库任务 |

后续可按需扩展其他任务类型（如：批量删除、数据同步等）。