# 技术领域AI分析系统（ISO-Tech-Analyzer） — API 接口文档

> 版本: v3.0（2026-09-02，按 OpenAPI 自动生成，覆盖全部接口）
> Base URL: `http://127.0.0.1:8000/api/v1`（外部API为 `http://127.0.0.1:8000/api/external/v1`）
> 响应格式: JSON (`application/json`)
> 在线交互式文档: `/docs`（Swagger UI）、`/redoc`；原始 OpenAPI: `/openapi.json`
> 重新生成: `python scripts/gen_api_doc.py`

---

## 概述

### 认证方式

| 类型 | 说明 |
|------|------|
| **JWT（默认）** | 先 `POST /api/v1/auth/login` 换取 token，后续请求携带 `Authorization: Bearer <token>`。登录接口同时返回 `must_change_password`（密码不合规需强制改密）与 `pwd_rule` |
| **外部 API** | 请求头携带 `X-API-Key: <your-api-key>`，通过 `/api/external/v1/*` 访问（密钥在平台『API密钥』页管理） |
| **公开端点** | 登录、手机验证码找回密码（发送验证码/重置密码）、健康检查等无需认证 |

### 角色与数据边界

- 角色: `admin`（平台管理员）/ `ent_admin`（企业管理员）/ `user`（企业成员）
- 企业成员仅能访问本企业数据；预审议项目普通成员仅见本人创建的（详见各接口说明）
- 未归属企业的非 admin 账号，除登录外所有接口返回 401

### 错误响应

```json
{ "detail": "错误信息" }
```

| HTTP 状态码 | 说明 |
|-------------|------|
| 200 | 成功 |
| 400 | 参数/业务校验失败（详见 detail） |
| 401 | 未认证 / Token失效 / 账号未归属企业 |
| 402 | 企业余额不足 |
| 403 | 无权限 / 账号被禁用 / 企业被停用 |
| 404 | 资源不存在（含无权限资源的越权保护） |
| 422 | 请求体字段类型错误 |
| 500 | 服务器内部错误 |

### 接口总览（共 558 个）

| 章节 | 模块 | 接口数 |
|------|------|--------|
| 1 | 认证与账号安全 | 8 |
| 2 | 用户管理（平台） | 7 |
| 3 | 企业管理（平台） | 8 |
| 4 | 企业侧功能（企业管理员） | 14 |
| 5 | ISO 体系与领域 | 5 |
| 6 | AI 分析 | 10 |
| 7 | 领域分组 | 21 |
| 8 | 知识库与报告 | 11 |
| 9 | SOP 与文档模板 | 15 |
| 10 | 审核员专业评价 | 20 |
| 11 | 技术专家评价 | 8 |
| 12 | 学习资料与考试 | 19 |
| 13 | 代码评审 | 17 |
| 14 | 数据源管理 | 20 |
| 15 | 系统配置与日志 | 7 |
| 16 | 企业审核指导书 | 4 |
| 17 | AI预审议 | 54 |
| 18 | 不符合整改 | 9 |
| 19 | 体系文件核查（符合性检查） | 36 |
| 20 | 认证规则 | 40 |
| 21 | 标准转版 | 72 |
| 22 | AI知识中心（自学习） | 14 |
| 23 | 智能派遣 | 19 |
| 24 | 预受理与人日估算 | 29 |
| 25 | 游戏化学习 | 32 |
| 26 | CNCA上报校验 | 10 |
| 27 | 管理接口与外部 API | 15 |
| 28 | 通用 | 3 |

---

## 1. 认证与账号安全

### PUT `/api/v1/auth/bind-phone`

确认绑定手机号

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `BindPhoneRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| phone | string | 是 | Phone |
| code | string | 是 | Code |

---

### POST `/api/v1/auth/login`

登录

**认证**: 公开（无需认证）

**请求体字段**（模型 `LoginRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | Username |
| password | string | 是 | Password |

---

### POST `/api/v1/auth/logout`

登出（前端清除 token 即可）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/auth/me`

获取当前用户信息

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/auth/password`

修改密码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `ChangePasswordRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| old_password | string | 是 | Old Password |
| new_password | string | 是 | New Password |

---

### POST `/api/v1/auth/reset-password-by-phone`

找回密码：验证码 + 新密码

**认证**: 公开（无需认证）

**请求体字段**（模型 `ResetByPhoneRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| phone | string | 是 | Phone |
| code | string | 是 | Code |
| new_password | string | 是 | New Password |

---

### POST `/api/v1/auth/send-bind-code`

绑定/更换手机号：向新手机号发送验证码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `SendResetCodeRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| phone | string | 是 | Phone |

---

### POST `/api/v1/auth/send-reset-code`

找回密码：向绑定手机号发送验证码（不泄露手机号是否已绑定）

**认证**: 公开（无需认证）

**请求体字段**（模型 `SendResetCodeRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| phone | string | 是 | Phone |

---

## 2. 用户管理（平台）

### GET `/api/v1/modules`

获取所有可配置模块列表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/operation-logs`

查看操作日志（仅管理员）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |
| user_id | query | 否 | integer |   |
| action | query | 否 | string |   |

---

### GET `/api/v1/token-usage-by-user`

按用户统计 Token 消耗（仅管理员）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| days | query | 否 | integer |   |

---

### GET `/api/v1/users`

用户列表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/users`

创建用户

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `CreateUserRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | Username |
| password | string | 否 | Password |
| phone | string | 否 | Phone |
| display_name | string | 否 | Display Name |
| role | string | 否 | Role（默认 "user"） |
| permissions | array<string> | 否 | Permissions |
| enterprise_id | integer | 否 | Enterprise Id |

---

### PUT `/api/v1/users/{user_id}`

编辑用户

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| user_id | path | 是 | integer |   |

**请求体字段**（模型 `UpdateUserRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| display_name | string | 否 | Display Name |
| role | string | 否 | Role |
| is_active | boolean | 否 | Is Active |
| password | string | 否 | Password |
| phone | string | 否 | Phone |
| permissions | array<string> | 否 | Permissions |
| enterprise_id | integer | 否 | Enterprise Id |

---

### DELETE `/api/v1/users/{user_id}`

删除用户

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| user_id | path | 是 | integer |   |

---

## 3. 企业管理（平台）

### GET `/api/v1/enterprises`

企业列表（含成员数、余额）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/enterprises`

开通企业：一个事务内建企业+企业管理员账号+初始余额流水

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `CreateEnterpriseRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ent_code | string | 是 | Ent Code |
| ent_name | string | 是 | Ent Name |
| short_name | string | 否 | Short Name |
| contact_name | string | 否 | Contact Name |
| contact_phone | string | 否 | Contact Phone |
| remark | string | 否 | Remark |
| admin_username | string | 是 | Admin Username |
| admin_password | string | 否 | Admin Password |
| admin_phone | string | 否 | Admin Phone |
| admin_display_name | string | 否 | Admin Display Name |
| initial_balance | number | 否 | Initial Balance |
| kb_sources | array<string> | 否 | Kb Sources |

---

### PUT `/api/v1/enterprises/{ent_id}`

编辑企业基本信息/状态

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| ent_id | path | 是 | integer |   |

**请求体字段**（模型 `UpdateEnterpriseRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ent_name | string | 否 | Ent Name |
| short_name | string | 否 | Short Name |
| contact_name | string | 否 | Contact Name |
| contact_phone | string | 否 | Contact Phone |
| status | integer | 否 | Status |
| remark | string | 否 | Remark |
| kb_sources | array<string> | 否 | Kb Sources |

---

### GET `/api/v1/enterprises/{ent_id}/balance-logs`

平台查看某企业充值/扣减流水

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| ent_id | path | 是 | integer |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |
| change_type | query | 否 | string |   |

---

### POST `/api/v1/enterprises/{ent_id}/balance-logs/{log_id}/correct`

充值纠正/作废：平台管理员修改某笔充值流水的金额（填错金额时纠正；改0=作废）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| ent_id | path | 是 | integer |   |
| log_id | path | 是 | integer |   |

**请求体字段**（模型 `RechargeCorrectRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| new_amount | number | 是 | New Amount |
| remark | string | 否 | Remark（默认 ""） |

---

### POST `/api/v1/enterprises/{ent_id}/recharge`

企业充值

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| ent_id | path | 是 | integer |   |

**请求体字段**（模型 `RechargeRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| amount | number | 是 | Amount |
| remark | string | 否 | Remark（默认 ""） |

---

### POST `/api/v1/enterprises/{ent_id}/reset-admin-password`

重置企业管理员密码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| ent_id | path | 是 | integer |   |

**请求体字段**（模型 `ResetAdminPasswordRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| new_password | string | 是 | New Password |

---

### POST `/api/v1/enterprises/{ent_id}/set-balance`

直接设置企业余额：平台管理员直接把余额改成指定数值（new_balance=null 设为不限量）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| ent_id | path | 是 | integer |   |

**请求体字段**（模型 `SetBalanceRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| new_balance | number | 否 | New Balance |
| remark | string | 否 | Remark（默认 ""） |

---

## 4. 企业侧功能（企业管理员）

### GET `/api/v1/enterprise/api-keys`

本企业API密钥列表（仅 ent_admin）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/enterprise/api-keys`

创建本企业API密钥；raw_key 仅本次返回，落库只存 SHA256。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `EntApiKeyCreate`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | Name |
| description | string | 否 | Description（默认 ""） |
| expires_at | string | 否 | Expires At |

---

### DELETE `/api/v1/enterprise/api-keys/{key_id}`

撤销本企业密钥（置 is_active=0，与平台侧行为一致，保留审计痕迹）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| key_id | path | 是 | integer |   |

---

### POST `/api/v1/enterprise/api-keys/{key_id}/toggle`

启用/停用本企业密钥

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| key_id | path | 是 | integer |   |

---

### GET `/api/v1/enterprise/balance`

本企业余额

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/enterprise/balance-logs`

本企业余额流水（只看自己的）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |
| change_type | query | 否 | string |   |

---

### GET `/api/v1/enterprise/config`

读取企业参数（企业全员可读）；kb_sources 为平台管理员设定，此处只读

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/enterprise/config`

保存企业三项参数（仅 ent_admin）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `SaveConfigRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| iso_systems | array<string> | 否 | Iso Systems |
| cnas_scope | object | 否 | Cnas Scope |
| grouping_params | object | 否 | Grouping Params |

---

### GET `/api/v1/enterprise/info`

本企业基本信息

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/enterprise/members`

本企业成员列表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/enterprise/members`

创建本企业成员（role 固定 user）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `CreateMemberRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| username | string | 是 | Username |
| password | string | 否 | Password |
| phone | string | 否 | Phone |
| display_name | string | 否 | Display Name |
| permissions | array<string> | 否 | Permissions |

---

### PUT `/api/v1/enterprise/members/{uid}`

编辑本企业成员

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| uid | path | 是 | integer |   |

**请求体字段**（模型 `UpdateMemberRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| display_name | string | 否 | Display Name |
| is_active | boolean | 否 | Is Active |
| phone | string | 否 | Phone |
| permissions | array<string> | 否 | Permissions |

---

### DELETE `/api/v1/enterprise/members/{uid}`

删除本企业成员（不可删企管账号）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| uid | path | 是 | integer |   |

---

### POST `/api/v1/enterprise/members/{uid}/reset-password`

重置本企业成员密码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| uid | path | 是 | integer |   |

**请求体字段**（模型 `ResetMemberPasswordRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| new_password | string | 是 | New Password |

---

## 5. ISO 体系与领域

### 5.1 ISO 体系

### GET `/api/v1/iso-systems`

List all ISO systems.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/iso-systems/{code}`

Get single ISO system.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| code | path | 是 | string |   |

---

### 5.2 领域管理

### GET `/api/v1/analysis/{domain_id}`

Get latest analysis result for a domain.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | path | 是 | integer |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/domains`

List domains with optional filters. Includes EC9000 from td_sc15_category.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| cnas_major | query | 否 | string |   |
| status | query | 否 | string / integer |   |

---

### GET `/api/v1/domains/{domain_id}`

Get domain detail.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | path | 是 | integer |   |

---

## 6. AI 分析

### 6.1 AI 分析与进度

### POST `/api/v1/analysis`

Trigger Analysis

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `AnalysisRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| iso_systems | array<string> | 是 | Iso Systems |
| cnas_majors | array<string> | 否 | Cnas Majors（默认 []） |
| max_workers | integer | 否 | Max Workers（默认 1） |
| domain_ids | array<integer> | 否 | Domain Ids（默认 []） |

---

### POST `/api/v1/analysis/batch-sub-analyze`

Batch re-generate sub-category analyses for an ISO system.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |

---

### PUT `/api/v1/analysis/{domain_id}`

Update analysis status (e.g., confirm=2).

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | path | 是 | integer |   |
| iso_system | query | 是 | string |   |
| status | query | 是 | integer |   |

---

### POST `/api/v1/analysis/{domain_id}/re-analyze`

Clear existing analysis and re-trigger.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | path | 是 | integer |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/analysis/{task_id}`

Get Task Status

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/analysis/{task_id}/cancel`

Cancel Task

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### GET `/api/v1/progress`

Get Progress

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/progress/control`

Control Task

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| action | query | 是 | string |   |
| task_id | query | 是 | integer |   |

---

### 6.2 子类别分析

### GET `/api/v1/sub-categories`

List Sub Categories

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_major | query | 否 | string |   |
| cnas_code | query | 否 | string |   |
| iso_system | query | 否 | string |   |
| analyzed | query | 否 | integer |   |

---

### GET `/api/v1/sub-categories/{cnas_code}`

Get Sub Analysis

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

## 7. 领域分组

### 7.1 领域分组与分组方案

### GET `/api/v1/document-metadata`

获取文档元数据配置（企业用户可见本企业行+平台共享NULL行，admin看全部）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| doc_type | query | 否 | string |   |

---

### POST `/api/v1/document-metadata`

保存文档元数据配置（按 enterprise_id+iso_system+doc_type 定位：

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/grouping`

List grouping results. Falls back to td_analysis+td_domain if no grouping records.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| cnas_major | query | 否 | string |   |
| scheme_id | query | 否 | integer |   |

---

### POST `/api/v1/grouping/batch-confirm`

Batch confirm groupings.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `app__api__v1__grouping__BatchConfirmRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ids | array<integer> | 是 | Ids |

---

### POST `/api/v1/grouping/batch-confirm-by-domain`

Batch confirm groupings by domain_id (for fallback records). Creates grouping records as needed.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `BatchConfirmByDomainRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| domain_ids | array<integer> | 是 | Domain Ids |
| iso_system | string | 是 | Iso System |

---

### POST `/api/v1/grouping/confirm-by-domain`

Confirm a grouping by domain_id (for fallback records without grouping id). Creates grouping record if needed.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | query | 是 | integer |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/grouping/export/{task_id}/download`

下载已完成的ZIP文件

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### GET `/api/v1/grouping/export/{task_id}/progress`

查询导出进度

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### GET `/api/v1/grouping/progress-overview`

Get analysis progress overview for ALL ISO systems and schemes.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/grouping/reports/{grouping_id}`

Get group analysis report data.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| grouping_id | path | 是 | integer |   |

---

### GET `/api/v1/grouping/reports/{grouping_id}/docx`

Download group analysis report as DOCX, reusing build_domain_report() format.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| grouping_id | path | 是 | integer |   |

---

### GET `/api/v1/grouping/schemes`

List all grouping schemes for an ISO system.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |

---

### POST `/api/v1/grouping/schemes`

Create a new grouping scheme.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `SchemeCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| iso_system | string | 是 | Iso System |
| scheme_name | string | 是 | Scheme Name |
| parameters | object | 否 | Parameters（默认 {}） |

---

### PUT `/api/v1/grouping/schemes/{scheme_id}`

Update a grouping scheme (only when status=0).

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scheme_id | path | 是 | integer |   |

**请求体字段**（模型 `SchemeUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| scheme_name | string | 否 | Scheme Name |
| parameters | object | 否 | Parameters |

---

### DELETE `/api/v1/grouping/schemes/{scheme_id}`

Delete a scheme and all its grouping results.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scheme_id | path | 是 | integer |   |

---

### POST `/api/v1/grouping/schemes/{scheme_id}/execute`

Execute AI grouping for a scheme — reads parameters, calls AI per cnas_major, saves results.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scheme_id | path | 是 | integer |   |

---

### POST `/api/v1/grouping/schemes/{scheme_id}/export-all`

启动批量导出（立即返回，后台生成ZIP）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scheme_id | path | 是 | integer |   |

---

### POST `/api/v1/grouping/schemes/{scheme_id}/generate-reports`

Generate technical domain analysis reports for all groups in a scheme.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scheme_id | path | 是 | integer |   |

---

### POST `/api/v1/grouping/{grouping_id}/confirm`

Confirm a grouping.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| grouping_id | path | 是 | integer |   |

---

### 7.2 分组配置

### GET `/api/v1/grouping/config`

Get Grouping Config

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| cnas_major | query | 否 | string |   |

---

### PUT `/api/v1/grouping/config`

Update Grouping Config

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

## 8. 知识库与报告

### 8.1 知识库

### GET `/api/v1/knowledge-base`

List Kb

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| doc_type | query | 否 | string |   |

---

### POST `/api/v1/knowledge-base`

Upload Kb

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |
| iso_system | string | 否 | Iso System（默认 "*"） |
| iso_name | string | 否 | Iso Name（默认 ""） |
| doc_code | string | 否 | Doc Code（默认 ""） |
| doc_title | string | 否 | Doc Title（默认 ""） |
| doc_type | string | 否 | Doc Type（默认 "cnas_rule"） |

---

### GET `/api/v1/knowledge-base/{kb_id}`

Get Kb

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kb_id | path | 是 | integer |   |

---

### DELETE `/api/v1/knowledge-base/{kb_id}`

Delete Kb

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kb_id | path | 是 | integer |   |

---

### POST `/api/v1/knowledge-base/{kb_id}/parse`

Parse Kb

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kb_id | path | 是 | integer |   |

---

### 8.2 报告管理

### GET `/api/v1/reports/major/{cnas_major}/overview/docx`

下载CNAS大类的整体概览报告DOCX。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_major | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/reports/sub/docx`

下载单个子类别的技术领域分析报告DOCX。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | query | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/reports/sub/json`

获取单个子类别的技术领域分析数据（JSON格式，用于页面查看）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | query | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### POST `/api/v1/reports/{analysis_id}/revise`

Ai Revise

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| analysis_id | path | 是 | integer |   |

**请求体字段**（模型 `ReviseRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| message | string | 是 | Message |
| chat_history | array<object> | 否 | Chat History（默认 []） |

---

### GET `/api/v1/reports/{domain_id}`

Get Report

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | path | 是 | integer |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/reports/{domain_id}/docx`

Download Docx Report

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | path | 是 | integer |   |
| iso_system | query | 是 | string |   |

---

## 9. SOP 与文档模板

### 9.1 SOP 文档

### POST `/api/v1/sop/batch`

Batch generate SOPs for all analyzed domains in an ISO system.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |

---

### POST `/api/v1/sop/sub/batch`

Batch generate SOPs for sub-categories without SOP, up to `limit` per call.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |
| cnas_major | query | 否 | string |   |
| limit | query | 否 | integer |   |

---

### POST `/api/v1/sop/sub/{cnas_code}`

Generate SOP for a single sub-category.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |
| cnas_major | query | 否 | string |   |

---

### GET `/api/v1/sop/sub/{cnas_code}`

Get Sub Sop

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/sop/sub/{cnas_code}/download`

Download Sub Sop

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### POST `/api/v1/sop/{domain_code}`

Generate Sop

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/sop/{domain_code}`

Get Sop

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/sop/{domain_code}/download`

Download Sop

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### 9.2 DOCX 模板

### GET `/api/v1/docx-templates`

List Docx Templates

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/docx-templates`

Save Template

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/docx-templates/upload`

Upload a .docx template file. The template can use Jinja2-style placeholders like {{domain_name}}.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| doc_type | query | 否 | string |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |

---

### GET `/api/v1/docx-templates/{iso_system}/{doc_type}`

Get Template

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | path | 是 | string |   |
| doc_type | path | 是 | string |   |

---

### DELETE `/api/v1/docx-templates/{iso_system}/{doc_type}`

Delete Template

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | path | 是 | string |   |
| doc_type | path | 是 | string |   |

---

### GET `/api/v1/docx-templates/{iso_system}/{doc_type}/generate/{domain_id}`

Generate a document from the uploaded .docx template, filling in analysis data.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | path | 是 | string |   |
| doc_type | path | 是 | string |   |
| domain_id | path | 是 | integer |   |

---

### 9.3 导出

### POST `/api/v1/export/{iso_system}/docx`

Export all analysis reports as DOCX for an ISO system.

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | path | 是 | string |   |

---

## 10. 审核员专业评价

### POST `/api/v1/evaluator/apply`

应用选中的代码到审核员代码池

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/evaluator/chat`

AI对话助手

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/evaluator/download-interview`

下载面谈记录表文件

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| file | query | 是 | string |   |
| task_id | query | 否 | integer |   |

---

### GET `/api/v1/evaluator/download-transfer-doc`

下载互通扩展文档

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| file | query | 是 | string |   |
| task_id | query | 否 | integer |   |

---

### POST `/api/v1/evaluator/evaluate`

上传Word文档 + 入队评价（异步）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| auditor_name | string | 是 | Auditor Name |
| auditor_code | string | 否 | Auditor Code（默认 ""） |
| iso_list | string | 是 | Iso List |
| scheme_map | string | 否 | Scheme Map（默认 ""） |
| word_file | string | 是 | Word File |

---

### GET `/api/v1/evaluator/evaluator-progress`

获取当前评价队列状态

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/evaluator/evaluator-result/{task_id}`

获取已完成任务的详细评价结果

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/evaluator/evaluator-task/{task_id}/cancel`

取消或停止评价任务

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/evaluator/evaluator-task/{task_id}/delete`

删除评价任务

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/evaluator/evaluator-task/{task_id}/reevaluate`

使用原文件重新评价（使用最新规则）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### GET `/api/v1/evaluator/evaluator-tasks`

获取评价任务列表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/evaluator/generate-interview`

生成面谈记录表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/evaluator/grade-exam`

上传审核员填写的试卷Word文件，AI自动判卷

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| task_id | integer | 是 | Task Id |
| iso | string | 是 | Iso |
| dalei | string | 是 | Dalei |
| filled_file | string | 是 | Filled File |

---

### GET `/api/v1/evaluator/learning/rules`

查询学习规则列表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso | query | 否 | string |   |
| keyword | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### DELETE `/api/v1/evaluator/learning/rules/{rule_id}`

删除学习规则

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

---

### GET `/api/v1/evaluator/learning/stats`

学习统计

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso | query | 否 | string |   |

---

### POST `/api/v1/evaluator/save-record`

保存评价记录到数据库

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/evaluator/search-auditor`

搜索审核员（自动完成）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| q | query | 否 | string |   |

---

### POST `/api/v1/evaluator/task/{task_id}/chat`

基于评价任务的多轮AI对话 + 自动学习

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### GET `/api/v1/evaluator/task/{task_id}/chat-history`

获取评价任务的对话历史

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

## 11. 技术专家评价

### GET `/api/v1/expert-eval/code-pool/all`

获取指定体系下的所有专业代码（不分类，用于 FSMS/HACCP 等无大类体系）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso | query | 否 | string |   |

---

### GET `/api/v1/expert-eval/code-pool/{dalei}`

获取指定体系+大类下的专业代码列表（从 td_audit_code）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| dalei | path | 是 | string |   |
| iso | query | 否 | string |   |

---

### GET `/api/v1/expert-eval/dalei-pool`

获取指定体系下的大类列表（从 td_audit_code）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso | query | 否 | string |   |

---

### POST `/api/v1/expert-eval/evaluate`

上传工作经历文档，评价技术专家是否具备指定专业代码的能力

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| expert_name | string | 是 | Expert Name |
| eval_targets | string | 是 | Eval Targets |
| word_file | string | 是 | Word File |

---

### GET `/api/v1/expert-eval/result/{task_id}`

获取技术专家评价结果

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/expert-eval/task/{task_id}/cancel`

取消评价任务

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/expert-eval/task/{task_id}/delete`

删除评价任务

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### GET `/api/v1/expert-eval/tasks`

获取技术专家评价任务列表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

## 12. 学习资料与考试

### GET `/api/v1/exam/batch-current-task`

查找指定体系的当前/最近批量任务（用于断点续传检测）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |

---

### POST `/api/v1/exam/batch-export`

启动批量导出学习资料/试卷（后台线程）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |
| export_type | query | 否 | string |   |
| cnas_major | query | 否 | string |   |

---

### POST `/api/v1/exam/batch-generate`

批量生成学习资料和/或试卷（加入队列，自动按顺序执行）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |
| gen_type | query | 否 | string |   |
| cnas_major | query | 否 | string |   |

---

### GET `/api/v1/exam/batch-progress`

获取批量生成进度

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/exam/batch-queue-status`

查询整个批量任务队列状态

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/exam/batch-task-status/{task_id}`

查询特定批量任务的执行状态

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | string |   |

---

### GET `/api/v1/exam/download-export/{task_id}`

下载导出的ZIP文件

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | string |   |

---

### GET `/api/v1/exam/exam-papers`

列表查询试卷

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| cnas_major | query | 否 | string |   |
| cnas_code | query | 否 | string |   |
| status | query | 否 | integer |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/exam/exam-papers/generate`

生成单个试卷

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |
| cnas_code | query | 是 | string |   |

---

### GET `/api/v1/exam/exam-papers/{cnas_code}`

查看单个试卷详情

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/exam/exam-papers/{cnas_code}/docx`

下载试卷 DOCX

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |
| with_answers | query | 否 | boolean |   |

---

### POST `/api/v1/exam/export-grading-result`

导出判卷结果为DOCX文档。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/exam/export-progress/{task_id}`

查询导出进度

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | string |   |

---

### POST `/api/v1/exam/grade-subjective`

AI评分在线答题中的主观题。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/exam/study-materials`

列表查询学习资料

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| cnas_major | query | 否 | string |   |
| cnas_code | query | 否 | string |   |
| status | query | 否 | integer |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/exam/study-materials/generate`

生成单个学习资料

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 是 | string |   |
| cnas_code | query | 是 | string |   |

---

### GET `/api/v1/exam/study-materials/{cnas_code}`

查看单个学习资料详情

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/v1/exam/study-materials/{cnas_code}/docx`

下载学习资料 DOCX

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cnas_code | path | 是 | string |   |
| iso_system | query | 是 | string |   |

---

### POST `/api/v1/exam/upload-and-grade`

上传填写好的试卷DOCX，自动识别并判卷

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| cnas_code | query | 否 | string |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 否 | File |

---

## 13. 代码评审

### POST `/api/v1/code-review/analyze`

启动代码评审分析 — 入队立即返回，AI分析在后台异步执行（评审任务队列页可随时查看结果）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `app__api__v1__code_review__AnalyzeRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| enterprise | EnterpriseInfo | 是 |   |
| items | array<ProjectItem> | 是 | Items |

---

### GET `/api/v1/code-review/kw-map/{iso}`

获取关键词映射表（调试用）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso | path | 是 | string |   |

---

### GET `/api/v1/code-review/list`

列出代码评审任务（分页；评审任务队列页轮询此接口，可随时查看每次评审的状态与结果）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/code-review/{task_id}`

查询任务状态和结果

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/code-review/{task_id}/chat`

AI 对话助手（多轮记忆+任务现场+知识库注入+接受纠正人设；对话后可自动提炼纠正为pending知识）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

**请求体字段**（模型 `ChatRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| message | string | 是 | Message |

---

### GET `/api/v1/code-review/{task_id}/chat-history`

该任务的对话历史（倒序取 limit 条后正序返回），供前端打开任务时渲染连续对话

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |
| limit | query | 否 | integer |   |

---

### POST `/api/v1/code-review/{task_id}/chat/{chat_id}/learn`

通道1：用户点「学到」→ AI提炼本轮纠正 → 直批入知识中心（approved）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |
| chat_id | path | 是 | integer |   |

---

### POST `/api/v1/code-review/{task_id}/delete`

删除评审任务及其对话记录（运行中的任务不可删除）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/code-review/{task_id}/feedback`

记录采纳/拒绝反馈；勾选采纳的代码逐条直接进入知识中心（自动确认）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/code-review/{task_id}/manual-answer`

人工提交正确答案（AI 评审整体不对时）：覆盖本任务对应体系的推荐代码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

**请求体字段**（模型 `ManualAnswerRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| answers | array<ManualAnswerItem> | 是 | Answers |

---

### POST `/api/v1/code-review/{task_id}/rerun`

按历史任务的企业信息与项目列表重新发起评审（新任务入队，不覆盖原记录）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/code-review/{task_id}/save`

保存采纳的专业代码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

**请求体字段**（模型 `SaveRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| cti_id | integer | 是 | Cti Id |
| codes | string | 是 | Codes |
| use_code | string | 否 | Use Code（默认 ""） |
| scope | string | 否 | Scope（默认 ""） |
| iso | string | 否 | Iso（默认 ""） |

---

### GET `/api/v1/token-usage/export`

导出 Token 消耗记录为 CSV

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| days | query | 否 | integer |   |

---

### GET `/api/v1/token-usage/pricing`

获取当前配置的模型价格表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/token-usage/pricing-config`

获取模型单价配置（内置价 + 管理员覆盖价）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/token-usage/pricing-config`

保存模型单价覆盖配置（仅对新产生的计费记录生效）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `UpdatePricingConfigRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| overrides | object | 是 | Overrides |

---

### GET `/api/v1/token-usage/stats`

获取 Token 消耗统计信息

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| days | query | 否 | integer |   |

---

## 14. 数据源管理

### GET `/api/v1/code-review/data/audit-codes`

查询审核代码池

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso | query | 否 | string |   |
| keyword | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/code-review/data/audit-codes`

新增审核代码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### DELETE `/api/v1/code-review/data/audit-codes/{item_id}`

删除审核代码（软删除）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

---

### GET `/api/v1/code-review/data/cnas-industry`

查询CNAS行业分类

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/code-review/data/cnas-industry`

新增CNAS行业

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### DELETE `/api/v1/code-review/data/cnas-industry/{item_id}`

删除CNAS行业

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

---

### GET `/api/v1/code-review/data/code-industry`

查询行业映射

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/code-review/data/code-industry`

新增行业映射

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### DELETE `/api/v1/code-review/data/code-industry/{item_id}`

删除行业映射

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

---

### GET `/api/v1/code-review/data/handbook-codes`

查询手册代码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| system | query | 否 | string |   |
| keyword | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/code-review/data/handbook-codes`

新增手册代码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### DELETE `/api/v1/code-review/data/handbook-codes/{item_id}`

删除手册代码

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

---

### GET `/api/v1/code-review/data/kb-categories`

查询知识库分类

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/code-review/data/kb-categories`

新增知识库分类

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/code-review/data/kb-categories/{item_id}`

更新知识库分类

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

---

### DELETE `/api/v1/code-review/data/kb-categories/{item_id}`

删除知识库分类

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

---

### GET `/api/v1/code-review/data/project-knowledge`

查询历史项目知识库

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso | query | 否 | string |   |
| keyword | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/code-review/data/project-knowledge`

新增历史项目

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### DELETE `/api/v1/code-review/data/project-knowledge/{item_id}`

删除历史项目

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

---

### GET `/api/v1/code-review/data/stats`

获取数据源统计信息

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

## 15. 系统配置与日志

### GET `/api/v1/system-config`

获取所有系统配置（显示实际生效值，敏感字段脱敏）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/system-config/available-models`

获取可选的AI模型列表（内置分组 + 系统配置页添加的自定义模型）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/system-config/batch`

批量更新配置（注意：此路由必须在 /system-config/{key} 之前定义）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/system-config/clean-tmp`

清理临时文件

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/system-config/tmp-files`

列出临时文件目录中的文件

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/system-config/{key}`

获取单个配置项

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| key | path | 是 | string |   |

---

### PUT `/api/v1/system-config/{key}`

更新配置项

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| key | path | 是 | string |   |

---

## 16. 企业审核指导书

### GET `/api/v1/audit-guide/download/{task_id}`

下载生成的ZIP文件

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | string |   |

---

### POST `/api/v1/audit-guide/generate`

上传管理手册+企业参数，启动后台生成任务

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| enterprise_name | string | 是 | Enterprise Name |
| cert_scope | string | 是 | Cert Scope |
| iso_system | string | 是 | Iso System |
| cnas_codes | string | 是 | Cnas Codes |
| manual_file | string | 否 | Manual File |

---

### GET `/api/v1/audit-guide/progress/{task_id}`

查询生成任务进度

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | string |   |

---

### GET `/api/v1/audit-guide/search-codes`

模糊搜索CNAS专业代码（按iso_system过滤）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| q | query | 否 | string |   |
| iso_system | query | 否 | string |   |
| limit | query | 否 | integer |   |

---

## 17. AI预审议

### POST `/api/v1/pre-review/audit-types`

Add Audit Type

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `AuditTypeIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | string | 否 | Code（默认 ""） |
| name | string | 否 | Name（默认 ""） |

---

### PUT `/api/v1/pre-review/audit-types/{type_id}`

Update Audit Type

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| type_id | path | 是 | integer |   |

**请求体字段**（模型 `AuditTypeUpdateIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | Name |
| enabled | integer | 否 | Enabled |

---

### DELETE `/api/v1/pre-review/audit-types/{type_id}`

Delete Audit Type

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| type_id | path | 是 | integer |   |

---

### PUT `/api/v1/pre-review/audit-types/{type_id}/override`

企业级覆盖平台共享审核类型（ent_admin）：改写名称/停用，可一键还原

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| type_id | path | 是 | integer |   |

**请求体字段**（模型 `DictNameOverrideIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | Name |
| enabled | integer | 否 | Enabled（默认 1） |

---

### DELETE `/api/v1/pre-review/audit-types/{type_id}/override`

还原平台默认：删除本企业对该平台审核类型的覆盖行

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| type_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-review/checklist`

合并列表：平台行+企业自有行；企业覆盖行（origin_id 非NULL）折进其平台行——

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/pre-review/checklist`

Add Checklist Item

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `ChecklistIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| item_no | integer | 否 | Item No（默认 0） |
| check_point | string | 是 | Check Point |
| iso_types | array<string> | 否 | Iso Types |
| audit_types | array<string> | 否 | Audit Types |
| file_categories | array<string> | 否 | File Categories |
| enabled | integer | 否 | Enabled（默认 1） |

---

### GET `/api/v1/pre-review/checklist-settings`

企业级检查要点设置（企业全员可读）：use_platform_checklist 全局开关

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/pre-review/checklist-settings`

企业级全局开关（仅 ent_admin）：关闭后本企业审议只用企业自有检查项。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `ChecklistSwitchIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| use_platform_checklist | integer | 是 | Use Platform Checklist |

---

### PUT `/api/v1/pre-review/checklist/{item_id}`

Update Checklist Item

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

**请求体字段**（模型 `ChecklistIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| item_no | integer | 否 | Item No（默认 0） |
| check_point | string | 是 | Check Point |
| iso_types | array<string> | 否 | Iso Types |
| audit_types | array<string> | 否 | Audit Types |
| file_categories | array<string> | 否 | File Categories |
| enabled | integer | 否 | Enabled（默认 1） |

---

### DELETE `/api/v1/pre-review/checklist/{item_id}`

Delete Checklist Item

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

---

### PUT `/api/v1/pre-review/checklist/{item_id}/override`

企业级覆盖平台共享检查要点（ent_admin）：upsert 覆盖行。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

**请求体字段**（模型 `ChecklistOverrideIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| check_point | string | 是 | Check Point |
| iso_types | array<string> | 否 | Iso Types |
| audit_types | array<string> | 否 | Audit Types |
| file_categories | array<string> | 否 | File Categories |
| enabled | integer | 否 | Enabled（默认 1） |

---

### DELETE `/api/v1/pre-review/checklist/{item_id}/override`

还原平台默认：删除本企业对该平台检查项的覆盖行。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| item_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-review/dict`

三类字典合并读（平台admin→平台带；企业账号→平台+本企业）：

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/pre-review/dict-settings`

企业级字典设置（企业全员可读）：三类「使用平台共享项」全局开关

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/pre-review/dict-settings`

企业级字典全局开关（仅 ent_admin，只作用于本企业）：关闭后本企业的自动识别

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `DictSwitchIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| use_platform_iso | integer | 否 | Use Platform Iso |
| use_platform_file_cat | integer | 否 | Use Platform File Cat |
| use_platform_audit_type | integer | 否 | Use Platform Audit Type |

---

### GET `/api/v1/pre-review/extract-task/{task_id}`

预提取任务状态轮询（企业维度隔离，仿 analysis 任务状态端点）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-review/file-categories`

Add File Category

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `FileCategoryIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | string | 否 | Code（默认 ""） |
| name | string | 否 | Name（默认 ""） |
| keywords | array<array<string>> | 否 | Keywords |
| header_patterns | array<array<string>> | 否 | Header Patterns |

---

### PUT `/api/v1/pre-review/file-categories/{category_id}`

Update File Category

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| category_id | path | 是 | integer |   |

**请求体字段**（模型 `FileCategoryUpdateIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | Name |
| keywords | array<array<string>> | 否 | Keywords |
| header_patterns | array<array<string>> | 否 | Header Patterns |
| enabled | integer | 否 | Enabled |
| sort_order | integer | 否 | Sort Order |

---

### DELETE `/api/v1/pre-review/file-categories/{category_id}`

Delete File Category

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| category_id | path | 是 | integer |   |

---

### PUT `/api/v1/pre-review/file-categories/{category_id}/override`

企业级覆盖平台共享文件类别（ent_admin）：改写名称/识别关键词/表头编号模式/

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| category_id | path | 是 | integer |   |

**请求体字段**（模型 `FileCategoryOverrideIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | Name |
| keywords | array<array<string>> | 否 | Keywords |
| header_patterns | array<array<string>> | 否 | Header Patterns |
| enabled | integer | 否 | Enabled（默认 1） |

---

### DELETE `/api/v1/pre-review/file-categories/{category_id}/override`

还原平台默认：删除本企业对该平台类别的覆盖行

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| category_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-review/files/batch-delete`

批量删除文件（前端多选/全选后一次提交）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### DELETE `/api/v1/pre-review/files/{file_id}`

Delete File

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| file_id | path | 是 | integer |   |

---

### PUT `/api/v1/pre-review/files/{file_id}/category`

Set File Category

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| file_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-review/files/{file_id}/download`

Download File

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| file_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-review/files/{file_id}/extract`

单文件强制重提取（同步等待；扫描件走OCR可能耗时数十秒）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| file_id | path | 是 | integer |   |

---

### PUT `/api/v1/pre-review/files/{file_id}/stage`

行级阶段标记修改（第40轮 2026-10-23）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| file_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-review/iso-systems`

Add Iso System

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `IsoSystemIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| code | string | 否 | Code（默认 ""） |
| name | string | 否 | Name（默认 ""） |

---

### PUT `/api/v1/pre-review/iso-systems/{system_id}`

Update Iso System

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| system_id | path | 是 | integer |   |

**请求体字段**（模型 `IsoSystemUpdateIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | Name |
| enabled | integer | 否 | Enabled |

---

### DELETE `/api/v1/pre-review/iso-systems/{system_id}`

Delete Iso System

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| system_id | path | 是 | integer |   |

---

### PUT `/api/v1/pre-review/iso-systems/{system_id}/override`

企业级覆盖平台共享认证体系（ent_admin）：改写名称/停用，可一键还原

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| system_id | path | 是 | integer |   |

**请求体字段**（模型 `DictNameOverrideIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | Name |
| enabled | integer | 否 | Enabled（默认 1） |

---

### DELETE `/api/v1/pre-review/iso-systems/{system_id}/override`

还原平台默认：删除本企业对该平台体系的覆盖行

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| system_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-review/issue-summary`

按体系汇总频发问题（纯统计，零AI计费）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_code | query | 否 | string |   |
| days | query | 否 | integer |   |

---

### POST `/api/v1/pre-review/issue-summary/ai-advice`

按需生成某体系的管理建议（每次调用计费一次，feature=pre_review）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `PrIssueAdviceReq`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| iso_code | string | 是 | 体系代码 |
| days | integer | 否 | 只统计最近N天，0=全部（默认 0） |

---

### GET `/api/v1/pre-review/projects`

List Projects

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| ep_name | query | 否 | string |   |
| tid | query | 否 | string |   |
| iso_code | query | 否 | string |   |
| report_status | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/pre-review/projects`

Create Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `app__api__v1__pre_review__ProjectIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ep_name | string | 是 | Ep Name |
| tid | integer | 否 | Tid |
| iso_codes | array<string> | 否 | Iso Codes |
| audit_types | array<string> | 否 | Audit Types |
| scope_text | string | 否 | Scope Text（默认 ""） |

---

### GET `/api/v1/pre-review/projects-all`

项目查询页数据源：本企业全员可见（不叠加 created_by 过滤）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| ep_name | query | 否 | string |   |
| tid | query | 否 | string |   |
| iso_code | query | 否 | string |   |
| report_status | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/pre-review/projects/purge-files`

清理历史项目原文件（2026-10-21 第31轮）：物理删除原件（本地/OSS）释放存储，

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/pre-review/projects/{project_id}`

Get Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### DELETE `/api/v1/pre-review/projects/{project_id}`

Delete Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-review/projects/{project_id}/extract`

项目级预提取（后台任务；只处理未成功提取的文件，已成功跳过不重复OCR）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-review/projects/{project_id}/files`

批量上传审核资料。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| files | array<string> | 是 | Files |
| category_code | string | 否 | Category Code（默认 "auto"） |
| stage | string | 否 | Stage（默认 ""） |

---

### POST `/api/v1/pre-review/projects/{project_id}/files-direct`

浏览器直传 OSS 确认入库（upload_files 的直传版，第26轮）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-review/projects/{project_id}/reports`

List Reports

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-review/projects/{project_id}/restart-task`

终止项目当前提取/审议任务并重新发起（2026-10-20 重启孤儿任务解套）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-review/projects/{project_id}/run`

Run Pre Review

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### PUT `/api/v1/pre-review/projects/{project_id}/temp-checklist`

项目级临时检查要点：每行一条，保存在项目上长期有效——

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `TempChecklistIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| temp_checklist | string | 否 | Temp Checklist |

---

### PUT `/api/v1/pre-review/projects/{project_id}/tid`

修改项目任务ID（2026-10-13 第19轮）：任务ID偶有填错，允许企业管理员

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `ProjectTidIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| tid | integer | 是 | Tid |

---

### POST `/api/v1/pre-review/projects/{project_id}/upload-policy`

签发浏览器直传 OSS 凭证（PostObject policy，第26轮低带宽根治）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-review/reports/{report_id}`

Get Report

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| report_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-review/reports/{report_id}/docx`

Export Report Docx

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| report_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-review/reports/{report_id}/status`

Report Status

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| report_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-review/unpack-status/{project_id}`

压缩包后台解压进度轮询（2026-10-20 上传异步化；企业隔离，跨企业404）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

## 18. 不符合整改

### POST `/api/v1/nc-rectify/analyze`

流式分析：similar → message* → done；AI失败且无内容时降级模板方案（不计费）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `app__api__v1__nc_rectify__AnalyzeRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| problem | string | 是 | Problem |
| company | string | 否 | Company（默认 ""） |

---

### GET `/api/v1/nc-rectify/cases`

List Cases

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/nc-rectify/cases`

Add Case

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `CaseCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| category | string | 否 | Category（默认 ""） |
| problem | string | 是 | Problem |
| clause | string | 否 | Clause（默认 ""） |
| root_cause | array<string> | 否 | Root Cause（默认 []） |
| correction | array<string> | 否 | Correction（默认 []） |
| corrective_action | array<string> | 否 | Corrective Action（默认 []） |
| attachment_types | array<string> | 否 | Attachment Types（默认 []） |

---

### GET `/api/v1/nc-rectify/cases/export`

Export Cases

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/nc-rectify/history`

List History

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/nc-rectify/history/{hid}`

History Detail

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| hid | path | 是 | integer |   |

---

### GET `/api/v1/nc-rectify/plan-download`

Plan Download

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| file | query | 是 | string |   |

---

### POST `/api/v1/nc-rectify/save-plan`

Save Plan

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `SavePlanRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| result | string | 是 | Result |
| company | string | 否 | Company（默认 ""） |
| sign_name | string | 否 | Sign Name（默认 ""） |

---

### POST `/api/v1/nc-rectify/upload`

Upload File

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |

---

## 19. 体系文件核查（符合性检查）

### 19.1 体系文件核查 - 项目

### GET `/api/v1/cb/projects`

List Projects

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/cb/projects`

Create Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `app__api__v1__cb_project__ProjectIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| project_code | string | 是 | 项目编号 |
| cb_name | string | 否 | Cb Name（默认 ""） |
| cb_short | string | 否 | Cb Short（默认 ""） |
| cb_address | string | 否 | Cb Address（默认 ""） |
| cb_phone | string | 否 | Cb Phone（默认 ""） |
| cb_email | string | 否 | Cb Email（默认 ""） |
| cb_scope | string | 否 | Cb Scope（默认 ""） |
| is_default | integer | 否 | Is Default |

---

### PUT `/api/v1/cb/projects/{project_id}`

Update Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `app__api__v1__cb_project__ProjectIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| project_code | string | 是 | 项目编号 |
| cb_name | string | 否 | Cb Name（默认 ""） |
| cb_short | string | 否 | Cb Short（默认 ""） |
| cb_address | string | 否 | Cb Address（默认 ""） |
| cb_phone | string | 否 | Cb Phone（默认 ""） |
| cb_email | string | 否 | Cb Email（默认 ""） |
| cb_scope | string | 否 | Cb Scope（默认 ""） |
| is_default | integer | 否 | Is Default |

---

### DELETE `/api/v1/cb/projects/{project_id}`

Delete Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### GET `/api/v1/cb/tasks/{task_id}`

任务进度轮询（校验企业归属）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### 19.2 体系文件核查 - 体系文件

### PATCH `/api/v1/cb/docs/{doc_id}`

Update Doc

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| doc_id | path | 是 | integer |   |

**请求体字段**（模型 `DocUpdate`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| doc_code | string | 否 | Doc Code |
| doc_title | string | 否 | Doc Title |
| doc_level | integer | 否 | Doc Level |

---

### DELETE `/api/v1/cb/docs/{doc_id}`

Delete Doc

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| doc_id | path | 是 | integer |   |

---

### GET `/api/v1/cb/docs/{doc_id}/download`

Download Doc

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| doc_id | path | 是 | integer |   |

---

### GET `/api/v1/cb/projects/{project_id}/docs`

List Docs

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |
| level | query | 否 | integer |   |

---

### POST `/api/v1/cb/projects/{project_id}/docs/extract`

批量提取文本（不计费）：提交后台任务，返回 task_id 供轮询

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `ExtractReq`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| doc_ids | array<integer> | 否 | Doc Ids |
| reextract | boolean | 否 | Reextract（默认 false） |

---

### GET `/api/v1/cb/projects/{project_id}/docs/stats`

Doc Stats

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### POST `/api/v1/cb/projects/{project_id}/docs/upload`

Upload Docs

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| files | array<string> | 是 | Files |

---

### 19.3 体系文件核查 - 检查单与实例

### GET `/api/v1/cb/instances/{instance_id}`

实例详情：模板 + 章节 + 检查项（合并填写结果）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| instance_id | path | 是 | integer |   |

---

### DELETE `/api/v1/cb/instances/{instance_id}`

Delete Instance

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| instance_id | path | 是 | integer |   |

---

### POST `/api/v1/cb/instances/{instance_id}/fill`

启动 AI 填充（异步任务，进度走 GET /cb/tasks/{task_id}）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| instance_id | path | 是 | integer |   |

---

### PUT `/api/v1/cb/instances/{instance_id}/items/{item_id}`

行内保存单字段（防抖自动保存入口）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| instance_id | path | 是 | integer |   |
| item_id | path | 是 | integer |   |

**请求体字段**（模型 `ItemSaveIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| field | string | 是 | doc_reference/problem_description/conformity/notes |
| value | string | 否 | Value（默认 ""） |

---

### POST `/api/v1/cb/projects/{project_id}/check-all`

一键检查全部模板（异步任务）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### POST `/api/v1/cb/projects/{project_id}/check-single`

单独核查某一个检查清单（异步任务入队，可连续提交多个清单排队执行）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `CheckSingleIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| template_id | integer | 是 | 检查单模板ID |

---

### POST `/api/v1/cb/projects/{project_id}/instances`

创建检查单实例（幂等：已存在则返回现有实例）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `InstanceCreateIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| template_id | integer | 是 | 模板ID |

---

### GET `/api/v1/cb/tasks`

核查任务队列（本企业；平台admin看全部）——提交后可离开页面，随时回来看进度

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/cb/templates`

模板列表：base 在前，domain 按 group_name 分组；带 project_id 时合并实例状态

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | query | 否 | integer |   |

---

### GET `/api/v1/cb/templates/{template_id}`

模板详情：章节 + 检查项（只读）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| template_id | path | 是 | integer |   |

---

### 19.4 体系文件核查 - 差距分析

### POST `/api/v1/cb/projects/{project_id}/gap-answer`

提交用户对B类问题的回答，AI二次整改

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `GapAnswerIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| questions | array<object> | 否 | Questions |
| answers_text | string | 否 | Answers Text（默认 ""） |

---

### POST `/api/v1/cb/projects/{project_id}/gap-fix`

启动AI智能整改（异步任务，进度走 GET /cb/tasks/{task_id}）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### GET `/api/v1/cb/projects/{project_id}/gap-questions`

待确认问题（重新映射到当前差距序号）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### DELETE `/api/v1/cb/projects/{project_id}/gap-questions`

Clear Pending Questions

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### GET `/api/v1/cb/projects/{project_id}/gaps`

差距汇总：计数必须与 SQL 一致（直接统计 responses）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### 19.5 体系文件核查 - 导出与整改

### POST `/api/v1/cb/export/checklist`

同步导出单张检查单为 Word（CNAS 版面，符合性着色）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `ChecklistExportIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| project_id | integer | 是 | 项目ID |
| template_id | integer | 是 | 模板ID |
| instance_id | integer | 否 | 实例ID；缺省按项目+模板查找 |

---

### GET `/api/v1/cb/generated-docs/{doc_id}/download`

Download Generated

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| doc_id | path | 是 | integer |   |

---

### POST `/api/v1/cb/projects/{project_id}/doc-revise`

导出AI整改后的体系文件 ZIP（异步任务，计费 doc_revise）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### POST `/api/v1/cb/projects/{project_id}/export-batch`

批量导出全部检查单为 ZIP（异步任务，不计费）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### GET `/api/v1/cb/projects/{project_id}/exports`

导出记录（最近 20 条）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### 19.6 体系文件核查 - AI助手

### POST `/api/v1/cb/chat/init`

创建或复用聊天会话

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `ChatInitIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| project_id | integer | 是 | Project Id |
| session_id | integer | 否 | Session Id（默认 0） |

---

### POST `/api/v1/cb/chat/send`

发送消息：保存用户消息 → 取最近10条历史 → AI回复 → 保存回复

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `ChatSendIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| session_id | integer | 是 | Session Id |
| message | string | 是 | Message |

---

### GET `/api/v1/cb/chat/sessions/{session_id}/messages`

Chat Messages

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| session_id | path | 是 | integer |   |

---

### DELETE `/api/v1/cb/chat/sessions/{session_id}/messages`

Chat Clear

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| session_id | path | 是 | integer |   |

---

## 20. 认证规则

### 20.1 认证规则 - 规则管理

### GET `/api/v1/cert-rules`

规则列表（分页 + rule_type/status 过滤 + 编号/名称关键字搜索）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_type | query | 否 | string |   |
| status | query | 否 | string |   |
| keyword | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/cert-rules`

创建规则（status=01）+ 标准关联 + create 修订快照

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `CertRuleCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| rule_code | string | 是 | Rule Code |
| rule_name | string | 是 | Rule Name |
| rule_type | string | 是 | Rule Type |
| domain_code | string | 否 | Domain Code |
| version | string | 否 | Version |
| compiler_name | string | 否 | Compiler Name |
| compiler_date | string | 否 | Compiler Date |
| reviewer_name | string | 否 | Reviewer Name |
| reviewer_date | string | 否 | Reviewer Date |
| approver_name | string | 否 | Approver Name |
| approver_date | string | 否 | Approver Date |
| doc_path | string | 否 | Doc Path |
| standard_ids | array<integer> | 否 | Standard Ids（默认 []） |

---

### GET `/api/v1/cert-rules/stats`

模块首页统计：按类型（A/B/C）计数 + 最新5条规则

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/cert-rules/{rule_id}`

规则详情：主表 + 章节 + 关联标准 + 备案

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

---

### PUT `/api/v1/cert-rules/{rule_id}`

更新规则主表字段（含编制/审核/批准）+ 标准关联全量替换

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

**请求体字段**（模型 `CertRuleUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| rule_code | string | 否 | Rule Code |
| rule_name | string | 否 | Rule Name |
| rule_type | string | 否 | Rule Type |
| domain_code | string | 否 | Domain Code |
| version | string | 否 | Version |
| compiler_name | string | 否 | Compiler Name |
| compiler_date | string | 否 | Compiler Date |
| reviewer_name | string | 否 | Reviewer Name |
| reviewer_date | string | 否 | Reviewer Date |
| approver_name | string | 否 | Approver Name |
| approver_date | string | 否 | Approver Date |
| doc_path | string | 否 | Doc Path |
| standard_ids | array<integer> | 否 | Standard Ids |

---

### DELETE `/api/v1/cert-rules/{rule_id}`

软删除规则：deleted=1 并重命名 rule_code 释放唯一键

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

---

### PUT `/api/v1/cert-rules/{rule_id}/chapters`

章节全量保存（按 chapter_no 为键，先删后插）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

**请求体字段**（模型 `ChaptersSaveRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| chapters | array<ChapterItem> | 否 | Chapters（默认 []） |

---

### PUT `/api/v1/cert-rules/{rule_id}/filing`

备案数据 upsert（任意 JSON 对象）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

---

### GET `/api/v1/cert-rules/{rule_id}/revisions`

修订历史列表（revision_no 降序，含快照）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

---

### PUT `/api/v1/cert-rules/{rule_id}/status`

规则状态流转（01新建/02修订/03注销）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

**请求体字段**（模型 `StatusUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| status | string | 是 | Status |

---

### 20.2 认证规则 - AI分析

### GET `/api/v1/cert-ai-tasks/{task_id}`

任务进度查询（企业归属校验，跨企业 404）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/cert-projects/{project_id}/ai/materials`

立项材料生成：建 cert_rule_project 后台任务（申请书+可行性报告），返回 task_id

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### POST `/api/v1/cert-rules/{rule_id}/ai/generate`

全文生成：建 cert_rule_generate 后台任务，返回 task_id

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

---

### POST `/api/v1/cert-rules/{rule_id}/ai/rebuild`

全文重建：建 cert_rule_rebuild 后台任务（worker 先写重建前快照），返回 task_id

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

---

### POST `/api/v1/cert-rules/{rule_id}/chapters/{chapter_id}/polish`

单章润色（同步阻塞）：语言优化不改变含义，成功返回新内容

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |
| chapter_id | path | 是 | integer |   |

---

### POST `/api/v1/cert-rules/{rule_id}/chapters/{chapter_id}/revise`

单章修订（同步阻塞）：按指令修订章节正文，成功返回新内容

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |
| chapter_id | path | 是 | integer |   |

**请求体字段**（模型 `ReviseChapterRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| instruction | string | 是 | 修改指令 |

---

### 20.3 认证规则 - 标准库

### GET `/api/v1/cert-standards`

共享标准列表（分页 + 编号/名称关键字搜索）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| standard_code | query | 否 | string |   |
| standard_name | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/cert-standards`

创建共享标准（仅平台admin）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `CertStandardCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| standard_code | string | 是 | Standard Code |
| standard_name | string | 是 | Standard Name |
| category | string | 否 | Category |
| status | integer | 否 | Status（默认 1） |

---

### GET `/api/v1/cert-standards/enabled`

企业账号：返回本企业启用的标准清单（JOIN 共享标准表）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/cert-standards/{standard_id}`

编辑共享标准（仅平台admin）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| standard_id | path | 是 | integer |   |

**请求体字段**（模型 `CertStandardUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| standard_code | string | 否 | Standard Code |
| standard_name | string | 否 | Standard Name |
| category | string | 否 | Category |
| status | integer | 否 | Status |

---

### DELETE `/api/v1/cert-standards/{standard_id}`

删除共享标准（仅平台admin）；被认证规则引用时禁止删除

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| standard_id | path | 是 | integer |   |

---

### PUT `/api/v1/cert-standards/{standard_id}/custom-code`

企业账号：设置某标准的企业自定义编号（upsert td_cert_ent_standard）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| standard_id | path | 是 | integer |   |

**请求体字段**（模型 `CustomCodeRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| custom_code | string | 否 | Custom Code |

---

### POST `/api/v1/cert-standards/{standard_id}/enable`

企业账号：启用/停用某标准（upsert td_cert_ent_standard）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| standard_id | path | 是 | integer |   |

**请求体字段**（模型 `EnableStandardRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| enabled | boolean | 否 | Enabled（默认 true） |

---

### POST `/api/v1/cert-standards/{standard_id}/pdf`

上传标准PDF（仅平台admin），落盘 data/storage/platform/cert_rule/standards/std_{id}.pdf

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| standard_id | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |

---

### 20.4 认证规则 - 立项管理

### GET `/api/v1/cert-projects`

立项列表（分页 + status 过滤 + 名称关键字搜索）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| status | query | 否 | string |   |
| keyword | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/cert-projects`

创建立项（status=draft，applicant 取当前用户）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `CertProjectCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | 否 | Title |
| project_name | string | 否 | Project Name |
| rule_id | integer | 否 | Rule Id |
| necessity | string | 否 | Necessity |
| market_analysis | string | 否 | Market Analysis |
| capability | string | 否 | Capability |
| risk_assessment | string | 否 | Risk Assessment |
| work_plan | string | 否 | Work Plan |

---

### GET `/api/v1/cert-projects/{project_id}`

立项详情

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### PUT `/api/v1/cert-projects/{project_id}`

更新立项（仅 draft/rejected 可编辑）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `CertProjectUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| project_name | string | 否 | Project Name |
| rule_id | integer | 否 | Rule Id |
| necessity | string | 否 | Necessity |
| market_analysis | string | 否 | Market Analysis |
| capability | string | 否 | Capability |
| risk_assessment | string | 否 | Risk Assessment |
| work_plan | string | 否 | Work Plan |

---

### DELETE `/api/v1/cert-projects/{project_id}`

删除立项（仅 draft 可删除）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### POST `/api/v1/cert-projects/{project_id}/transition`

立项状态流转：submit(draft→review) / approve(review→approved) / reject(review→rejected)

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `TransitionRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| action | string | 是 | Action |

---

### 20.5 认证规则 - 知识库

### GET `/api/v1/cert-kb`

知识库列表（分页 + 标题关键字搜索 + rule_type/is_template 过滤）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| title | query | 否 | string |   |
| rule_type | query | 否 | string |   |
| is_template | query | 否 | integer |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/cert-kb`

新建知识库条目：平台admin → 平台共享（enterprise_id=NULL）；企业账号 → 本企业私有

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `CertKbCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| rule_type | string | 是 | Rule Type |
| domain_code | string | 否 | Domain Code（默认 "*"） |
| title | string | 是 | Title |
| content | string | 否 | Content |
| is_template | integer | 否 | Is Template（默认 0） |
| status | integer | 否 | Status（默认 1） |

---

### GET `/api/v1/cert-kb/{kb_id}`

知识库详情（共享条目全员可见；私有条目仅本企业；否则404）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kb_id | path | 是 | integer |   |

---

### PUT `/api/v1/cert-kb/{kb_id}`

更新知识库条目：共享条目仅平台admin；私有条目仅本企业

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kb_id | path | 是 | integer |   |

**请求体字段**（模型 `CertKbUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| rule_type | string | 否 | Rule Type |
| domain_code | string | 否 | Domain Code |
| title | string | 否 | Title |
| content | string | 否 | Content |
| is_template | integer | 否 | Is Template |
| status | integer | 否 | Status |

---

### DELETE `/api/v1/cert-kb/{kb_id}`

删除知识库条目：共享条目仅平台admin；私有条目仅本企业

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kb_id | path | 是 | integer |   |

---

### 20.6 认证规则 - 导出

### POST `/api/v1/cert-projects/{project_id}/export`

导出立项资料 Word（docx_project）。不调 AI、不计费。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

---

### GET `/api/v1/cert-rule-export/{output_id}/download`

下载导出产物：非本企业产物 → 403；记录/文件缺失 → 404；

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| output_id | path | 是 | integer |   |

---

### GET `/api/v1/cert-rule-outputs`

导出记录分页列表（企业隔离，按 id 倒序）。只读 DB 记录，

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### DELETE `/api/v1/cert-rule-outputs/{output_id}`

删除导出记录：只删 DB 行，磁盘文件留档（与旧系统行为一致）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| output_id | path | 是 | integer |   |

---

### POST `/api/v1/cert-rules/{rule_id}/export`

导出规则产物。body: {"type": "docx_rule" | "excel_filing"}。不调 AI、不计费。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

---

## 21. 标准转版

### 21.1 标准转版

### PUT `/api/v1/std-convert/audit-guide/{rid}`

S9 人工编辑审核指导 → guide_status='edited'（此后 AI 重跑不覆盖本行）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

**请求体字段**（模型 `AuditGuideUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| focus_text | string | 否 | Focus Text |
| method_text | string | 否 | Method Text |
| common_nc_text | string | 否 | Common Nc Text |
| transition_text | string | 否 | Transition Text |

---

### PUT `/api/v1/std-convert/clauses/{cid}`

Edit Clause

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cid | path | 是 | integer |   |

**请求体字段**（模型 `ClauseEditRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | 否 | Title |
| paras | array<任意> | 否 | Paras |
| trans_text | array<任意> | 否 | Trans Text |
| norm_text | array<任意> | 否 | Norm Text |
| review_status | string | 否 | Review Status |

---

### PUT `/api/v1/std-convert/clauses/{cid}/norm`

Review Norm

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cid | path | 是 | integer |   |

**请求体字段**（模型 `NormReviewRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| norm_text | array<任意> | 否 | Norm Text |
| adopt_draft | object | 否 | Adopt Draft |

---

### PUT `/api/v1/std-convert/clauses/{cid}/trans`

人工改稿/确认直译：段落数必须与原文一致（铁律）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| cid | path | 是 | integer |   |

**请求体字段**（模型 `TransReviewRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| trans_text | array<任意> | 是 | Trans Text |

---

### GET `/api/v1/std-convert/demo/projects`

平台示范项目（只读）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/std-convert/dict`

List Dict

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | query | 否 | integer |   |

---

### POST `/api/v1/std-convert/dict`

Create Dict

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `DictCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| term_en | string | 否 | Term En（默认 ""） |
| term_zh | string | 是 | Term Zh |
| banned | array<任意> | 否 | Banned（默认 []） |
| note | string | 否 | Note（默认 ""） |
| project_id | integer | 否 | Project Id |

---

### PUT `/api/v1/std-convert/dict/{did}`

Update Dict

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| did | path | 是 | integer |   |

**请求体字段**（模型 `DictUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| term_en | string | 否 | Term En |
| term_zh | string | 否 | Term Zh |
| banned | array<任意> | 否 | Banned |
| note | string | 否 | Note |
| enabled | boolean | 否 | Enabled |

---

### DELETE `/api/v1/std-convert/dict/{did}`

Delete Dict

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| did | path | 是 | integer |   |

---

### PUT `/api/v1/std-convert/diff-gb/{rid}`

Update Diff Gb

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

**请求体字段**（模型 `DiffGbUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| final_category | string | 否 | Final Category |
| user_note | string | 否 | User Note |
| status | string | 否 | Status |

---

### PUT `/api/v1/std-convert/diff-version/{rid}`

Update Diff Ver

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

**请求体字段**（模型 `DiffVerUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| level | string | 否 | Level |
| user_note | string | 否 | User Note |
| status | string | 否 | Status |

---

### PUT `/api/v1/std-convert/explain/{rid}`

S7 人工编辑释义/举例 → explain_status='edited'（此后 AI 重跑不覆盖本行）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

**请求体字段**（模型 `ExplainUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| explain_text | string | 否 | Explain Text |
| example_text | string | 否 | Example Text |

---

### GET `/api/v1/std-convert/platform/rules`

平台级规则（词组/标题等）：企业端只读浏览

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rtype | query | 否 | string |   |

---

### GET `/api/v1/std-convert/projects`

List Projects

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/std-convert/projects`

Create Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `ProjectCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | Name |
| old_std_code | string | 否 | Old Std Code（默认 ""） |
| new_std_code | string | 否 | New Std Code（默认 ""） |
| settings | object | 否 | Settings |
| import_demo | boolean | 否 | Import Demo（默认 true） |
| src_lang | string | 否 | Src Lang（默认 "en"） |
| cmp_mode | string | 否 | Cmp Mode（默认 "version"） |

---

### GET `/api/v1/std-convert/projects/{pid}`

Get Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### PUT `/api/v1/std-convert/projects/{pid}`

Update Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `ProjectUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | Name |
| old_std_code | string | 否 | Old Std Code |
| new_std_code | string | 否 | New Std Code |
| settings | object | 否 | Settings |

---

### DELETE `/api/v1/std-convert/projects/{pid}`

Delete Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### GET `/api/v1/std-convert/projects/{pid}/audit-guides`

S9 审核指导列表（按条款 seq 序，标题从 EN 侧条款联查）+ 覆盖统计

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| status | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/std-convert/projects/{pid}/clauses`

List Clauses

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| side | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |
| trans_status | query | 否 | string |   |
| review_status | query | 否 | string |   |
| keyword | query | 否 | string |   |

---

### POST `/api/v1/std-convert/projects/{pid}/clauses/batch-confirm`

Batch Confirm Clauses

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `app__api__v1__std_convert__BatchConfirmRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| clause_ids | array<integer> | 否 | Clause Ids |
| side | string | 否 | Side |

---

### GET `/api/v1/std-convert/projects/{pid}/diff-gb`

List Diff Gb

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| category | query | 否 | string |   |
| status | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/std-convert/projects/{pid}/diff-version`

List Diff Ver

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| level | query | 否 | string |   |
| status | query | 否 | string |   |
| scope | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/std-convert/projects/{pid}/explains`

S7 释义列表（按条款 seq 序，标题从 EN 侧条款联查）+ 覆盖统计

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| status | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/std-convert/projects/{pid}/revise-batches`

S10 修订批次列表：逐批文件数 + 修订状态计数 + 条目四状态计数。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### GET `/api/v1/std-convert/projects/{pid}/revise-batches/{bid}/files`

S10 批次内文件列表：修订状态 + 逐文件条目四状态计数。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| bid | path | 是 | integer |   |

---

### GET `/api/v1/std-convert/projects/{pid}/revise-edits`

S10 修订条目分页（依据条款标题从 EN 侧条款联查）+ 状态统计。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| batch_id | query | 否 | integer |   |
| file_id | query | 否 | integer |   |
| status | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/revise-edits/batch`

S10 批量判定修订条目。file_id 给整文件批量（只作用于 ai 行，用户已改过的

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `ReviseEditBatchRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file_id | integer | 否 | File Id |
| ids | array<integer> | 否 | Ids |
| edit_status | string | 是 | Edit Status |

---

### GET `/api/v1/std-convert/projects/{pid}/rules`

List Rules

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| rtype | query | 否 | string |   |

---

### POST `/api/v1/std-convert/projects/{pid}/rules`

Create Rule

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `RuleCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| type | string | 是 | Type |
| k | string | 是 | K |
| v | 任意 | 否 | V |
| seq | integer | 否 | Seq（默认 0） |
| enabled | boolean | 否 | Enabled（默认 true） |

---

### PUT `/api/v1/std-convert/revise-edit/{rid}`

S10 人工编辑/判定单条修订：改 revised_text → edit_status='edited'；

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

**请求体字段**（模型 `ReviseEditUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| revised_text | string | 否 | Revised Text |
| edit_status | string | 否 | Edit Status |

---

### PUT `/api/v1/std-convert/rules/{rid}`

Update Rule

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

**请求体字段**（模型 `RuleUpdateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| k | string | 否 | K |
| v | 任意 | 否 | V |
| seq | integer | 否 | Seq |
| enabled | boolean | 否 | Enabled |

---

### DELETE `/api/v1/std-convert/rules/{rid}`

Delete Rule

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

---

### 21.2 标准转版 - AI

### POST `/api/v1/std-convert/projects/{pid}/audit-guide/regen`

S9 单条重生成（AI计费）：强制覆盖该条款现有审核指导（含人工 edited 稿，

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `AuditGuideRegenRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| clause_no | string | 是 | Clause No |

---

### POST `/api/v1/std-convert/projects/{pid}/audit-guide/run`

S9 逐条款审核指导（AI计费）：默认断点续跑，已生成（含人工 edited）条款跳过

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `AuditGuideRunRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| clause_nos | array<string> | 否 | Clause Nos |
| regen_all | boolean | 否 | Regen All（默认 false） |

---

### POST `/api/v1/std-convert/projects/{pid}/diff-gb/run`

S5 规范稿(或新版原文) vs GB 逐条差异（difflib≥0.95免AI；纯国标可免翻译直通）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/diff-version/run`

S6 新旧版本差异/跨标准比对 13 级定级（纯国标/英英直比可免翻译直通）。单标准模式不可用。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/explain/regen`

S7 单条重生成（AI计费）：强制覆盖该条款现有释义（含人工 edited 稿，

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `ExplainRegenRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| clause_no | string | 是 | Clause No |

---

### POST `/api/v1/std-convert/projects/{pid}/explain/run`

S7 逐条释义（AI计费）：断点续跑，已生成（含人工 edited）条款跳过不重复计费

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `ExplainRunRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| clause_nos | array<string> | 否 | Clause Nos |

---

### POST `/api/v1/std-convert/projects/{pid}/impact/files`

S8 上传体系文件/日常表单（可多个，≤20个/次，单个≤100MB）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| files | array<string> | 否 | Files |
| kind | string | 否 | Kind（默认 "sys"） |
| items | string | 否 | Items |

---

### GET `/api/v1/std-convert/projects/{pid}/impact/files`

S8 已上传文件列表（含提取/分析状态与逐文件结论）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### DELETE `/api/v1/std-convert/projects/{pid}/impact/files/{fid}`

S8 删除已上传文件（连同盘文件/OSS对象 + .doc 转换缓存）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| fid | path | 是 | integer |   |

---

### GET `/api/v1/std-convert/projects/{pid}/impact/result`

S8 影响分析结果一次拉齐：综合结论 + 逐文件分析行

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/impact/run`

S8 发起影响分析（AI计费：每文件一次 + 综合一次；扫描件另计OCR）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/normalize`

S4 规范化：规则层全量 + 低相似度条款 AI 改写建议。中文标准模式不可用。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `NormalizeRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| skip_ai | boolean | 否 | Skip Ai（默认 false） |

---

### POST `/api/v1/std-convert/projects/{pid}/rebuild`

生成产物：规范化 docx + 对照表 xlsx（零AI零计费）。中文标准模式不可用。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/revise-batches`

S10 新建修订批次（可多次立项，每批次独立上传自己的文件集）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `ReviseBatchCreateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 否 | Name |

---

### DELETE `/api/v1/std-convert/projects/{pid}/revise-batches/{bid}`

S10 删除批次（级联：批次内文件行 + 修订条目行 + 物理文件/OSS对象 +

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| bid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/revise-batches/{bid}/files`

S10 批次内上传修订文件（仅 .doc/.docx + zip/rar/7z 整包，成员过滤只留

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| bid | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| files | array<string> | 否 | Files |
| items | string | 否 | Items |

---

### DELETE `/api/v1/std-convert/projects/{pid}/revise-file/{fid}`

S10 删除批次内文件（级联该文件修订条目 + 物理文件/OSS对象 + .conv 缓存）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| fid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/revise/regen`

S10 单文件重新修订（AI计费）：force=True 刷新该文件的 AI 条目；用户已

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `ReviseRegenRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file_id | integer | 是 | File Id |

---

### POST `/api/v1/std-convert/projects/{pid}/revise/run`

S10 AI 文件修订（AI计费：每≤40段落块一次调用）。硬依赖 S6 差异 +

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `ReviseRunRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| batch_id | integer | 是 | Batch Id |
| file_ids | array<integer> | 否 | File Ids |
| force | boolean | 否 | Force（默认 false） |

---

### GET `/api/v1/std-convert/projects/{pid}/tasks`

List Tasks

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/translate`

S3 AI翻译：支持子集条款；断点续跑（已完成/人工稿不重翻）。中文标准模式不可用。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**请求体字段**（模型 `TranslateRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| clause_nos | array<string> | 否 | Clause Nos |

---

### POST `/api/v1/std-convert/projects/{pid}/translate/retry-failed`

补译失败条款。中文标准模式不可用。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/upload-policy`

签发浏览器直传 OSS 凭证（PostObject policy）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/upload/en`

S2 新版标准上传：.docx/.txt/.pdf 建 en_parse 切块任务（.json 亦支持结构化直传；

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 否 | File |
| key | string | 否 | Key |
| name | string | 否 | Name |

---

### POST `/api/v1/std-convert/projects/{pid}/upload/gb`

S1 旧国标/对照标准上传：.json 即时入库；.docx/.txt/.pdf 建 gb_parse 切块任务

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 否 | File |
| key | string | 否 | Key |
| name | string | 否 | Name |

---

### GET `/api/v1/std-convert/tasks/{task_id}`

Get Task

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/tasks/{task_id}/cancel`

Cancel Task

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### 21.3 标准转版 - 导出

### GET `/api/v1/std-convert/export/{output_id}/download`

下载产物：非本企业产物 → 403；记录/文件缺失 → 404；

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| output_id | path | 是 | integer |   |

---

### GET `/api/v1/std-convert/outputs`

List Outputs

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | query | 是 | integer |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/export/audit-guide-docx`

S9 产物「审核作业指导书.docx」：与 S7 教材同条款树版式，每叶条款五栏目

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/export/clause-struct`

第47轮：S1(gb侧)/S2(en侧) 结构化条款导出 Excel / Word 表格（零AI计费）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| side | query | 是 | string |   |
| fmt | query | 否 | string |   |

---

### POST `/api/v1/std-convert/projects/{pid}/export/diff-gb`

Export Diff Gb

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/export/diff-version`

Export Diff Version

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/export/explain-docx`

S7 产物「标准原文与逐条释义.docx」：封面/编制说明/第一编正文/附录编，

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/export/impact-docx`

S8 产物「转版影响分析报告.docx」：总体结论/修订清单表/培训要点/客户告知

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/revise-batches/{bid}/export-all-zip`

S10 批次批量导出（第45轮：批次维度，原项目维度端点已废除）——

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| bid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/revise/{fid}/export-diff-docx`

S10 产物②修订对照表 docx：A4 横向逐条（位置/原文/修订后/依据条款/理由/

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| fid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/revise/{fid}/export-revised-docx`

S10 产物①清洁修订版 docx：应用 adopted+edited 修订，保留原格式（零AI）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| fid | path | 是 | integer |   |

---

### POST `/api/v1/std-convert/projects/{pid}/revise/{fid}/export-tracked-docx`

S10 产物③Word 痕迹修订版 docx：w:ins/w:del 修订标记（作者=AI转版助手），

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |
| fid | path | 是 | integer |   |

---

## 22. AI知识中心（自学习）

### POST `/api/v1/knowledge-center/ai-prescreen`

AI预审：对 pending 候选批量生成处置建议（ids缺省=全部未预审候选）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `AiPrescreenIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ids | array<integer> | 否 | Ids |

---

### POST `/api/v1/knowledge-center/apply-suggestions`

一键批量应用AI预审建议（人工点击触发）：

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `ApplySuggestionsIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ids | array<integer> | 是 | Ids |

---

### POST `/api/v1/knowledge-center/batch-ignore`

批量忽略待确认候选（不构成知识；已处置的跳过计数）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `BatchIgnoreIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ids | array<integer> | 是 | Ids |

---

### POST `/api/v1/knowledge-center/batch-reject`

批量拒绝待确认候选（已审核的跳过计数）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `BatchRejectIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ids | array<integer> | 是 | Ids |
| reason | string | 否 | Reason（默认 ""） |

---

### POST `/api/v1/knowledge-center/digest/generate`

手动生成今日日报：先预审全部未预审候选，再生成（force=true 覆盖当日已有日报）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `DigestGenerateIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| force | boolean | 否 | Force（默认 false） |

---

### GET `/api/v1/knowledge-center/digest/latest`

最近一日日报（date=YYYY-MM-DD 可指定；缺省今日）。无数据 data:null 不404。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| date | query | 否 | string |   |

---

### GET `/api/v1/knowledge-center/digest/list`

历史日报倒序分页

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/knowledge-center/list`

知识中心列表：admin 全量+模块/状态筛选；非 admin 仅已采纳（参数忽略）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| module | query | 否 | string |   |
| status | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/knowledge-center/pending-count`

各模块待确认计数（前端角标）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| module | query | 否 | string |   |

---

### PUT `/api/v1/knowledge-center/{kid}`

修改已采纳知识；晋升型模块同步改写晋升产物。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kid | path | 是 | integer |   |

**请求体字段**（模型 `UpdateIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| knowledge_text | string | 是 | Knowledge Text |
| promote_payload | object | 否 | Promote Payload |

---

### POST `/api/v1/knowledge-center/{kid}/approve`

确认候选为知识：知识内容必填；晋升型模块同事务写入目标知识存储。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kid | path | 是 | integer |   |

**请求体字段**（模型 `ApproveIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| knowledge_text | string | 是 | Knowledge Text |
| promote_payload | object | 否 | Promote Payload |

---

### POST `/api/v1/knowledge-center/{kid}/delete`

删除知识：级联删除晋升产物（容忍已不存在），立即不再参与后续AI。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kid | path | 是 | integer |   |

---

### POST `/api/v1/knowledge-center/{kid}/ignore`

忽略候选：不构成知识（非对错问题），归档后不再出现在待确认列表。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kid | path | 是 | integer |   |

---

### POST `/api/v1/knowledge-center/{kid}/reject`

拒绝候选（原因可空）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kid | path | 是 | integer |   |

**请求体字段**（模型 `RejectIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| reason | string | 否 | Reason（默认 ""） |

---

## 23. 智能派遣

### POST `/api/v1/smart-dispatch/batches`

上传Excel建批次（status=pending，后台manager自动拾取求解）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |
| name | string | 否 | Name（默认 ""） |
| use_qual_lib | integer | 否 | Use Qual Lib（默认 0） |

---

### GET `/api/v1/smart-dispatch/batches`

List Batches

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |
| status | query | 否 | string |   |

---

### GET `/api/v1/smart-dispatch/batches/{bid}`

轮询批次状态；completed 时附 stats 摘要

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| bid | path | 是 | integer |   |

---

### DELETE `/api/v1/smart-dispatch/batches/{bid}`

软删除（pending 批次删除后不再被拾取）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| bid | path | 是 | integer |   |

---

### GET `/api/v1/smart-dispatch/batches/{bid}/download`

下载结果Excel：非本企业 → 403；文件缺失/越界 → 404（RFC5987文件名）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| bid | path | 是 | integer |   |

---

### GET `/api/v1/smart-dispatch/batches/{bid}/result`

结果预览：tab=assign 派遣明细 / unassigned 未分配任务 / geo 地理编码明细

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| bid | path | 是 | integer |   |
| tab | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/smart-dispatch/qual-lib/imports`

上传ERP专业代码表CSV建导入批次（pending，后台worker拾取，24万行级）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |
| wipe | integer | 否 | Wipe（默认 0） |

---

### GET `/api/v1/smart-dispatch/qual-lib/imports`

List Qual Imports

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### DELETE `/api/v1/smart-dispatch/qual-lib/imports/{iid}`

撤销导入批次：软删批次 + 删除该批次仍在库的码行

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iid | path | 是 | integer |   |

---

### GET `/api/v1/smart-dispatch/qual-lib/persons`

人员查询：按姓名/编号模糊 → 分页人员 + 各自体系×码明细（每人≤500行）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| kw | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/smart-dispatch/qual-lib/stats`

库统计：码行数/人数/体系分布/注册资格分布/高风险占比 + 前端勾选可用性

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/smart-dispatch/reviews`

上传历史审核计划CSV+注册资格登记CSV建复盘批次（pending，后台worker拾取）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| plan_csv | string | 是 | Plan Csv |
| qual_csv | string | 是 | Qual Csv |
| name | string | 否 | Name（默认 ""） |
| resolve_enabled | integer | 否 | Resolve Enabled（默认 1） |
| use_qual_lib | integer | 否 | Use Qual Lib（默认 0） |

---

### GET `/api/v1/smart-dispatch/reviews`

List Reviews

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |
| status | query | 否 | string |   |

---

### GET `/api/v1/smart-dispatch/reviews/{rid}`

轮询复盘状态；completed 时附轻量 stats 摘要

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

---

### DELETE `/api/v1/smart-dispatch/reviews/{rid}`

软删除（pending 批次删除后不再被拾取）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

---

### GET `/api/v1/smart-dispatch/reviews/{rid}/download`

下载复盘报告Excel：非本企业 → 403；文件缺失/越界 → 404（RFC5987文件名）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |

---

### GET `/api/v1/smart-dispatch/reviews/{rid}/result`

复盘结果预览：tab=issues 问题清单 / projects 项目明细 /

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rid | path | 是 | integer |   |
| tab | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |
| level | query | 否 | string |   |
| q | query | 否 | string |   |

---

### GET `/api/v1/smart-dispatch/sample`

带示例数据的模板（6任务/9审核员/2占用，可直接提交求解体验）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/smart-dispatch/template`

空白标准模板（3 sheet + 填写说明）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

## 24. 预受理与人日估算

### POST `/api/v1/pre-accept/ent-info/search`

企业信息 AI 联网搜索（缓存命中零计费；失败降级空数据 200）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `EntSearchBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ep_name | string | 是 | Ep Name |
| force | boolean | 否 | Force（默认 false） |

---

### POST `/api/v1/pre-accept/evals`

Create Eval

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `EvalCreateBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ep_name | string | 是 | Ep Name |
| ep_info | object | 否 | Ep Info |
| audit_stage | string | 否 | Audit Stage（默认 "initial"） |
| systems | array<SystemRow> | 否 | Systems |
| multisite | MultisiteBody | 否 |   |
| confirmations | object | 否 | Confirmations |

---

### GET `/api/v1/pre-accept/evals`

List Evals

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |
| kw | query | 否 | string |   |
| status | query | 否 | string |   |

---

### GET `/api/v1/pre-accept/evals/{eval_id}`

Get Eval

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| eval_id | path | 是 | integer |   |

---

### PUT `/api/v1/pre-accept/evals/{eval_id}`

Update Eval

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| eval_id | path | 是 | integer |   |

**请求体字段**（模型 `EvalUpdateBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ep_name | string | 否 | Ep Name |
| ep_info | object | 否 | Ep Info |
| audit_stage | string | 否 | Audit Stage |
| systems | array<SystemRow> | 否 | Systems |
| multisite | MultisiteBody | 否 |   |
| confirmations | object | 否 | Confirmations |

---

### DELETE `/api/v1/pre-accept/evals/{eval_id}`

Delete Eval

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| eval_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-accept/evals/{eval_id}/evaluate`

同步执行确定性评估；缺信息返回 200 + verdict=need_supplement（永不 500）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| eval_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-accept/evals/{eval_id}/export`

Export Eval

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| eval_id | path | 是 | integer |   |
| fmt | query | 否 | string |   |

---

### POST `/api/v1/pre-accept/evals/{eval_id}/revise`

补充信息后复核：克隆新修订版并立即重评（沿用同一确定性管线）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| eval_id | path | 是 | integer |   |

**请求体字段**（模型 `EvalUpdateBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ep_name | string | 否 | Ep Name |
| ep_info | object | 否 | Ep Info |
| audit_stage | string | 否 | Audit Stage |
| systems | array<SystemRow> | 否 | Systems |
| multisite | MultisiteBody | 否 |   |
| confirmations | object | 否 | Confirmations |

---

### GET `/api/v1/pre-accept/evals/{eval_id}/trace`

Get Trace

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| eval_id | path | 是 | integer |   |
| stage | query | 否 | string |   |

---

### POST `/api/v1/pre-accept/extract-application`

上传认证申请表 → AI 结构化提取（企业隔离，登录即可）。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |

---

### GET `/api/v1/pre-accept/field-dict`

申请字段字典（前端动态表单/缺项标签用，与引擎内置字典同源）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/pre-accept/risk-level`

专业代码风险等级（td_audit_code，精确→段级前缀兼容回退）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso | query | 是 | string |   |
| code | query | 是 | string |   |

---

### GET `/api/v1/pre-accept/rules/accept-rules`

List Accept Rules

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scheme_key | query | 否 | string |   |

---

### POST `/api/v1/pre-accept/rules/accept-rules`

Create Accept Rule

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `AcceptRuleBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| scheme_key | string | 是 | Scheme Key |
| rule_code | string | 是 | Rule Code |
| category | string | 否 | Category（默认 ""） |
| title | string | 否 | Title（默认 ""） |
| description | string | 否 | Description |
| check_type | string | 否 | Check Type（默认 "info_required"） |
| severity | string | 否 | Severity（默认 "block"） |
| required_fields | array<string> | 否 | Required Fields |
| expr | string | 否 | Expr（默认 ""） |
| fail_suggestion | string | 否 | Fail Suggestion（默认 ""） |
| source_ref | string | 否 | Source Ref（默认 ""） |
| enabled | integer | 否 | Enabled（默认 1） |
| sort | integer | 否 | Sort（默认 0） |

---

### PUT `/api/v1/pre-accept/rules/accept-rules/{rule_id}`

Update Accept Rule

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

**请求体字段**（模型 `AcceptRuleBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| scheme_key | string | 是 | Scheme Key |
| rule_code | string | 是 | Rule Code |
| category | string | 否 | Category（默认 ""） |
| title | string | 否 | Title（默认 ""） |
| description | string | 否 | Description |
| check_type | string | 否 | Check Type（默认 "info_required"） |
| severity | string | 否 | Severity（默认 "block"） |
| required_fields | array<string> | 否 | Required Fields |
| expr | string | 否 | Expr（默认 ""） |
| fail_suggestion | string | 否 | Fail Suggestion（默认 ""） |
| source_ref | string | 否 | Source Ref（默认 ""） |
| enabled | integer | 否 | Enabled（默认 1） |
| sort | integer | 否 | Sort（默认 0） |

---

### DELETE `/api/v1/pre-accept/rules/accept-rules/{rule_id}`

Delete Accept Rule

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| rule_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-accept/rules/adjust-factors`

List Adjust Factors

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scheme_key | query | 否 | string |   |
| phase | query | 否 | string |   |

---

### POST `/api/v1/pre-accept/rules/adjust-factors`

Create Adjust Factor

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `AdjustFactorBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| scheme_key | string | 是 | Scheme Key |
| factor_code | string | 是 | Factor Code |
| name | string | 否 | Name（默认 ""） |
| phase | string | 是 | Phase |
| op_type | string | 否 | Op Type（默认 "multiply"） |
| op_value | number | 否 | Op Value |
| bound | string | 否 | Bound（默认 ""） |
| formula | string | 否 | Formula（默认 ""） |
| applies_when | object | 否 | Applies When |
| input_fields | array<string> | 否 | Input Fields |
| source_ref | string | 否 | Source Ref（默认 ""） |
| enabled | integer | 否 | Enabled（默认 1） |
| sort | integer | 否 | Sort（默认 0） |

---

### PUT `/api/v1/pre-accept/rules/adjust-factors/{row_id}`

Update Adjust Factor

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| row_id | path | 是 | integer |   |

**请求体字段**（模型 `AdjustFactorBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| scheme_key | string | 是 | Scheme Key |
| factor_code | string | 是 | Factor Code |
| name | string | 否 | Name（默认 ""） |
| phase | string | 是 | Phase |
| op_type | string | 否 | Op Type（默认 "multiply"） |
| op_value | number | 否 | Op Value |
| bound | string | 否 | Bound（默认 ""） |
| formula | string | 否 | Formula（默认 ""） |
| applies_when | object | 否 | Applies When |
| input_fields | array<string> | 否 | Input Fields |
| source_ref | string | 否 | Source Ref（默认 ""） |
| enabled | integer | 否 | Enabled（默认 1） |
| sort | integer | 否 | Sort（默认 0） |

---

### DELETE `/api/v1/pre-accept/rules/adjust-factors/{row_id}`

Delete Adjust Factor

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| row_id | path | 是 | integer |   |

---

### POST `/api/v1/pre-accept/rules/reseed`

重灌种子（子进程执行 scripts/seed_pa_rules.py，幂等 upsert 不删人工行）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/pre-accept/rules/schemes/{scheme_key}`

体系方案维护：仅允许改 name/calc_profile/appendix_ref/data_version/enabled/sort

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scheme_key | path | 是 | string |   |

---

### GET `/api/v1/pre-accept/rules/time-base`

List Time Base

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scheme_key | query | 否 | string |   |
| table_code | query | 否 | string |   |
| audit_stage | query | 否 | string |   |

---

### POST `/api/v1/pre-accept/rules/time-base`

Create Time Base

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `TimeBaseBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| scheme_key | string | 是 | Scheme Key |
| table_code | string | 是 | Table Code |
| audit_stage | string | 否 | Audit Stage（默认 "initial"） |
| eff_num_min | integer | 是 | Eff Num Min |
| eff_num_max | integer | 否 | Eff Num Max |
| grade | string | 否 | Grade（默认 ""） |
| base_value | number | 否 | Base Value |
| unit | string | 否 | Unit（默认 "manday"） |
| extra | object | 否 | Extra |
| source_ref | string | 否 | Source Ref（默认 ""） |
| enabled | integer | 否 | Enabled（默认 1） |

---

### POST `/api/v1/pre-accept/rules/time-base/batch-import`

批量导入蒸馏 JSON 行：[{...TimeBaseBody}]；dry_run=true 只回显 diff

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/pre-accept/rules/time-base/{row_id}`

Update Time Base

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| row_id | path | 是 | integer |   |

**请求体字段**（模型 `TimeBaseBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| scheme_key | string | 是 | Scheme Key |
| table_code | string | 是 | Table Code |
| audit_stage | string | 否 | Audit Stage（默认 "initial"） |
| eff_num_min | integer | 是 | Eff Num Min |
| eff_num_max | integer | 否 | Eff Num Max |
| grade | string | 否 | Grade（默认 ""） |
| base_value | number | 否 | Base Value |
| unit | string | 否 | Unit（默认 "manday"） |
| extra | object | 否 | Extra |
| source_ref | string | 否 | Source Ref（默认 ""） |
| enabled | integer | 否 | Enabled（默认 1） |

---

### DELETE `/api/v1/pre-accept/rules/time-base/{row_id}`

Delete Time Base

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| row_id | path | 是 | integer |   |

---

### GET `/api/v1/pre-accept/schemes`

启用的体系方案（含 calc_profile，前端据此动态渲染体系差异字段）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

## 25. 游戏化学习

### POST `/api/v1/gl/admin/gen-tasks`

建任务并 inline 执行（一次 chat 一次扣费，charged 幂等；失败不自动重试）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `GenTaskBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| domain_id | integer | 是 | Domain Id |
| task_type | string | 是 | Task Type |
| source_type | string | 否 | Source Type（默认 "domain_desc"） |
| source_ref_ids | array<integer> | 否 | Source Ref Ids |
| manual_text | string | 否 | Manual Text（默认 ""） |
| gen_params | object | 否 | Gen Params |
| enterprise_id | integer | 否 | Enterprise Id |

---

### GET `/api/v1/gl/admin/gen-tasks`

Admin List Gen Tasks

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | query | 否 | integer |   |
| status | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/gl/admin/gen-tasks/upload-source`

上传素材文件（PDF/Word 等）→ 提取文字 → 返回给前端回填 manual_text 素材框。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |

---

### GET `/api/v1/gl/admin/gen-tasks/{tid}`

Admin Get Gen Task

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| tid | path | 是 | integer |   |

---

### POST `/api/v1/gl/admin/gen-tasks/{tid}/commit`

勾选入库：question→pending 进人工审核；card→直接入库 enabled=1。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| tid | path | 是 | integer |   |

**请求体字段**（模型 `CommitBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| indices | array<integer> | 否 | Indices |

---

### POST `/api/v1/gl/admin/kb-convert`

知识库转化：cert_rule_kb 行 / 已确认经验 → 建 gen_task(kb_*) 并执行

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `KbConvertBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| domain_id | integer | 是 | Domain Id |
| source | string | 是 | Source |
| ref_ids | array<integer> | 否 | Ref Ids |
| gen_params | object | 否 | Gen Params |
| enterprise_id | integer | 否 | Enterprise Id |

---

### GET `/api/v1/gl/admin/questions`

Admin List Questions

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | query | 否 | integer |   |
| status | query | 否 | string |   |
| q_type | query | 否 | string |   |
| keyword | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/gl/admin/questions`

Admin Create Question

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `QuestionBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| domain_id | integer | 是 | Domain Id |
| q_type | string | 是 | Q Type |
| stem | string | 是 | Stem |
| options | array<string> | 否 | Options |
| correct_answer | 任意 | 否 | Correct Answer（默认 ""） |
| explanation | string | 否 | Explanation（默认 ""） |
| difficulty | integer | 否 | Difficulty（默认 1） |
| score | integer | 否 | Score（默认 10） |
| tags | array<string> | 否 | Tags |
| status | string | 否 | Status（默认 "draft"） |
| enterprise_id | integer | 否 | Enterprise Id |

---

### POST `/api/v1/gl/admin/questions/batch-import`

批量导入：直入 approved（默认），content_hash 对库+批内去重，逐条报告

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `BatchImportBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| domain_id | integer | 是 | Domain Id |
| questions | array<object> | 是 | Questions |
| enterprise_id | integer | 否 | Enterprise Id |
| status | string | 否 | Status（默认 "approved"） |

---

### PUT `/api/v1/gl/admin/questions/{qid}`

Admin Update Question

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| qid | path | 是 | integer |   |

**请求体字段**（模型 `QuestionBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| domain_id | integer | 是 | Domain Id |
| q_type | string | 是 | Q Type |
| stem | string | 是 | Stem |
| options | array<string> | 否 | Options |
| correct_answer | 任意 | 否 | Correct Answer（默认 ""） |
| explanation | string | 否 | Explanation（默认 ""） |
| difficulty | integer | 否 | Difficulty（默认 1） |
| score | integer | 否 | Score（默认 10） |
| tags | array<string> | 否 | Tags |
| status | string | 否 | Status（默认 "draft"） |
| enterprise_id | integer | 否 | Enterprise Id |

---

### DELETE `/api/v1/gl/admin/questions/{qid}`

Admin Delete Question

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| qid | path | 是 | integer |   |

---

### POST `/api/v1/gl/admin/questions/{qid}/review`

Admin Review Question

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| qid | path | 是 | integer |   |

**请求体字段**（模型 `ReviewBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| action | string | 是 | Action |
| note | string | 否 | Note（默认 ""） |

---

### GET `/api/v1/gl/admin/review-queue`

Admin Review Queue

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| type | query | 否 | string |   |
| domain_id | query | 否 | integer |   |

---

### GET `/api/v1/gl/admin/rpg-scripts`

游戏化学习管理-剧情脚本列表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | query | 否 | integer |   |
| status | query | 否 | string |   |
| script_key | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### POST `/api/v1/gl/admin/rpg-scripts`

游戏化学习管理-新建剧情脚本

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `RpgScriptBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| domain_id | integer | 是 | Domain Id |
| script_key | string | 是 | Script Key |
| title | string | 否 | Title（默认 ""） |
| summary | string | 否 | Summary（默认 ""） |
| script_json | object | 否 | Script Json |
| enterprise_id | integer | 否 | Enterprise Id |

---

### POST `/api/v1/gl/admin/rpg-scripts/validate`

无副作用校验节点图：断链/孤儿节点/quiz 缺题源等。editor 保存前预检

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/gl/admin/rpg-scripts/{sid}`

游戏化学习管理-剧情脚本详情

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| sid | path | 是 | integer |   |

---

### PUT `/api/v1/gl/admin/rpg-scripts/{sid}`

draft/pending/rejected 可改；approved 已发布不可直接改（用 new-version 出新稿）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| sid | path | 是 | integer |   |

**请求体字段**（模型 `RpgScriptUpdateBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| title | string | 否 | Title |
| summary | string | 否 | Summary |
| script_json | object | 否 | Script Json |
| enabled | integer | 否 | Enabled |

---

### DELETE `/api/v1/gl/admin/rpg-scripts/{sid}`

游戏化学习管理-删除剧情脚本

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| sid | path | 是 | integer |   |

---

### POST `/api/v1/gl/admin/rpg-scripts/{sid}/new-version`

克隆现有脚本为 version+1 的 draft（改剧本不破坏历史进度）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| sid | path | 是 | integer |   |

---

### POST `/api/v1/gl/admin/rpg-scripts/{sid}/review`

游戏化学习管理-剧情审核

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| sid | path | 是 | integer |   |

**请求体字段**（模型 `ReviewBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| action | string | 是 | Action |
| note | string | 否 | Note（默认 ""） |

---

### GET `/api/v1/gl/admin/stats`

运营统计：参与人数/积分分布/各关通过率/题目正确率Top错/内容资产盘点。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/gl/badges`

游戏化学习-勋章墙

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/gl/cards`

游戏化学习-我的卡册

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | query | 否 | integer |   |

---

### POST `/api/v1/gl/daily-checkin`

游戏化学习-每日签到

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/gl/domains`

游戏化学习-领域列表

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/gl/domains/{domain_id}/map`

游戏化学习-关卡地图

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | path | 是 | integer |   |

---

### POST `/api/v1/gl/levels/{level_id}/start`

游戏化学习-开局

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| level_id | path | 是 | integer |   |

---

### GET `/api/v1/gl/progress`

游戏化学习-我的总览

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### GET `/api/v1/gl/rank`

游戏化学习-排行榜

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| scope | query | 否 | string |   |
| limit | query | 否 | integer |   |

---

### POST `/api/v1/gl/sessions/{session_id}/check`

memory_match 翻两张牌 / pair_match 连一条线 的即时对错判定。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| session_id | path | 是 | string |   |

**请求体字段**（模型 `CheckBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| a | string | 是 | memory=第一张牌uid / pair=左列id |
| b | string | 是 | memory=第二张牌uid / pair=右列rid |

---

### POST `/api/v1/gl/sessions/{session_id}/submit`

游戏化学习-交卷判分

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| session_id | path | 是 | string |   |

**请求体字段**（模型 `SubmitBody`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| answers | object | 否 | {question_id: 用户答案} |
| duration_sec | integer | 否 | 前端计时（参考） |
| path | array<string> | 否 | RPG 路径留痕（Step5） |

---

## 26. CNCA上报校验

### 26.1 CNCA上报校验（平台UI）

### GET `/api/v1/cnca-report/accounts`

List Accounts

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/cnca-report/accounts`

Create Account

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### PUT `/api/v1/cnca-report/accounts/{aid}`

Update Account

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| aid | path | 是 | integer |   |

---

### DELETE `/api/v1/cnca-report/accounts/{aid}`

Delete Account

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| aid | path | 是 | integer |   |

---

### GET `/api/v1/cnca-report/batches`

List Batches

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/cnca-report/batches/{bid}`

批次详情：issues（level/sheet/rule_id 筛选，cap 2000）+ rows（status 筛选分页）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| bid | path | 是 | integer |   |
| level | query | 否 | string |   |
| sheet | query | 否 | string |   |
| rule_id | query | 否 | string |   |
| row_status | query | 否 | string |   |
| page | query | 否 | integer |   |
| page_size | query | 否 | integer |   |

---

### GET `/api/v1/cnca-report/batches/{bid}/file`

下载结果/原始文件 kind=success|error|report|annex（annex 支持 idx=0/1/2 多包）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| bid | path | 是 | integer |   |
| kind | query | 是 | string |   |
| idx | query | 否 | integer |   |

---

### GET `/api/v1/cnca-report/codes/{codebook}`

码表内容查询（code/name 模糊过滤），供前端填写辅助

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| codebook | path | 是 | string |   |
| q | query | 否 | string |   |
| limit | query | 否 | integer |   |

---

### POST `/api/v1/cnca-report/validate`

上传上报表（必选）+ 附件包（可选；prod 类别最多3个）执行模拟校验，同步返回 CNCA 语义结果

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| report_file | string | 是 | Report File |
| annex_file | string | 否 | Annex File |
| annex_file2 | string | 否 | Annex File2 |
| annex_file3 | string | 否 | Annex File3 |
| template_hint | string | 否 | Template Hint（默认 "auto"） |
| assume_date | string | 否 | Assume Date（默认 ""） |

---

### 26.2 CNCA上报校验 - 外部协议端点（zazh_new2直连）

### POST `/api/external/cnca/v1/report`

Cnca Report

**认证**: 外部API：`?token=tda_sk_…`（兼容 Bearer / X-API-Key）+ 协议层 params 凭据

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| params | string | 否 | Params（默认 ""） |
| reportFile | string | 否 | Reportfile |
| annexFile | string | 否 | Annexfile |
| annexFile2 | string | 否 | Annexfile2 |
| annexFile3 | string | 否 | Annexfile3 |

---

## 27. 管理接口与外部 API

### 27.1 管理接口（API密钥）

### GET `/api/admin/api-keys`

List Api Keys

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/admin/api-keys`

Create Api Key

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `CreateApiKeyRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| name | string | 是 | Name |
| description | string | 否 | Description（默认 ""） |
| expires_at | string | 否 | Expires At |
| enterprise_id | integer | 否 | Enterprise Id |

---

### DELETE `/api/admin/api-keys/{key_id}`

Revoke Api Key

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| key_id | path | 是 | integer |   |

---

### POST `/api/admin/api-keys/{key_id}/toggle`

Toggle Api Key

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| key_id | path | 是 | integer |   |

---

### 27.2 外部 API（X-API-Key）

### POST `/api/external/v1/analysis`

[External] Trigger AI analysis task. Returns task_id for polling.

**认证**: 外部API：请求头 `X-API-Key`

---

### GET `/api/external/v1/analysis/{domain_id}`

[External] Get analysis result for a domain.

**认证**: 外部API：请求头 `X-API-Key`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| domain_id | path | 是 | integer |   |
| iso_system | query | 是 | string |   |

---

### GET `/api/external/v1/analysis/{task_id}`

[External] Get analysis task status and progress.

**认证**: 外部API：请求头 `X-API-Key`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

---

### GET `/api/external/v1/domains`

[External] List domains with optional filters.

**认证**: 外部API：请求头 `X-API-Key`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |
| cnas_major | query | 否 | string |   |

---

### GET `/api/external/v1/iso-systems`

[External] List all active ISO systems.

**认证**: 外部API：请求头 `X-API-Key`

---

### GET `/api/external/v1/knowledge-base`

[External] List knowledge base documents.

**认证**: 外部API：请求头 `X-API-Key`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| iso_system | query | 否 | string |   |

---

### GET `/api/external/v1/progress`

[External] Get current task progress and queue status.

**认证**: 外部API：请求头 `X-API-Key`

---

### POST `/api/external/v1/smart-dispatch/solve`

[External] 上传Excel建求解批次（上传即排队，后台VRP求解）

**认证**: 外部API：请求头 `X-API-Key`

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |
| name | string | 否 | Name（默认 ""） |

---

### GET `/api/external/v1/smart-dispatch/solve/{batch_id}`

[External] 轮询批次状态；completed 时附统计摘要与结果计数

**认证**: 外部API：请求头 `X-API-Key`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| batch_id | path | 是 | integer |   |

---

### GET `/api/external/v1/smart-dispatch/solve/{batch_id}/download`

[External] 下载结果Excel（RFC5987文件名；文件缺失/越界404）

**认证**: 外部API：请求头 `X-API-Key`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| batch_id | path | 是 | integer |   |

---

### GET `/api/external/v1/smart-dispatch/template`

[External] 下载空白标准模板（3 sheet + 填写说明）

**认证**: 外部API：请求头 `X-API-Key`

---

## 28. 通用

### GET `/`

Serve Frontend

**认证**: 公开（无需认证）

---

### GET `/api/v1/api-doc`

Get Api Doc

**认证**: 公开（无需认证）

---

### GET `/api/v1/health`

Health

**认证**: 公开（无需认证）

---

## 29. 智能派遣外部调用指南（ERP 集成）

智能派遣支持外部系统（如 zazh_new2 认证ERP）经 **X-API-Key** 集成，三步完成：
**① 上传Excel建批次 → ② 轮询状态 → ③ 下载结果Excel**。求解为平台本地VRP计算，零AI Token消耗；
余额闸门与其他外部API一致（企业余额≤0 → 402）。

### 准备工作

1. 平台管理员在『API密钥』页为**企业密钥**开通（平台密钥无企业归属，调用返回400）；
2. 密钥形如 `tda_sk_xxxx`，请求头携带 `X-API-Key: tda_sk_xxxx`；
3. Excel按标准模板填写（3 sheet：审核任务/审核员/占用日程），
   可先 `GET /api/external/v1/smart-dispatch/template` 下载空白模板。
4. 「审核任务」sheet 的**期望审核开始/结束**为期望时间窗（可只填一个或都不填），
   不是确定日期——具体排到哪天由VRP算法在区间内求解，结果Excel回写实际审核日期；
   留空时引擎按提交日起默认60天区间兜底。旧表头「审核开始/审核结束」仍兼容识别。

### PHP curl 三步示例（zazh_new2 侧可直接照抄）

```php
<?php
// ===== 配置 =====
$baseUrl = 'http://平台地址/api/external/v1';
$apiKey  = 'tda_sk_你的企业密钥';

function sdRequest($url, $apiKey, $post = null) {
    $ch = curl_init($url);
    $headers = ['X-API-Key: ' . $apiKey];
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_TIMEOUT, 300);
    if ($post !== null) {           // multipart 上传
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_POSTFIELDS, $post);
    }
    curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
    $body = curl_exec($ch);
    $code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);
    return [$code, $body];          // 下载场景 $body 即为xlsx二进制
}

// ===== ① 上传Excel建批次 =====
$xlsxPath = '/path/to/派遣任务.xlsx';
$payload  = [
    'file' => new CURLFile($xlsxPath,
        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
        basename($xlsxPath)),
    'name' => '2026年10月监督审核派遣',   // 可选，留空=文件名
];
list($code, $body) = sdRequest("$baseUrl/smart-dispatch/solve", $apiKey, $payload);
if ($code == 402) { exit('企业余额不足，请先充值'); }
if ($code != 200) { exit('提交失败: ' . $body); }
$batchId = json_decode($body, true)['batch_id'];

// ===== ② 轮询状态（建议3~5秒一次；求解通常30秒~5分钟） =====
// status: pending/running/parsing/geocoding/eligibility/solving/
//         postprocess/exporting → 进行中；completed=成功；failed=失败
do {
    sleep(5);
    list($code, $body) = sdRequest("$baseUrl/smart-dispatch/solve/$batchId", $apiKey);
    $st = json_decode($body, true);
} while ($code == 200 && !in_array($st['status'], ['completed', 'failed']));
if ($st['status'] == 'failed') { exit('求解失败: ' . $st['error_message']); }
// $st['summary'] 含 tasks_total/tasks_assigned/tasks_unassigned/assigns/solve_sec/warnings

// ===== ③ 下载结果Excel（4 sheet：派遣结果/未分配任务/求解统计/地理编码明细） =====
list($code, $xlsx) = sdRequest("$baseUrl/smart-dispatch/solve/$batchId/download", $apiKey);
if ($code != 200) { exit('下载失败: HTTP ' . $code); }
file_put_contents("/path/to/派遣结果_{$batchId}.xlsx", $xlsx);
```

### 状态与错误速查

| HTTP | 含义 | 处理建议 |
|------|------|----------|
| 200 | 正常 | — |
| 400 | 非企业密钥 / 文件类型不支持（仅.xlsx/.xlsm）/ 超200MB / 内容为空 | 检查密钥与文件 |
| 401 | X-API-Key 缺失或无效 | 检查密钥 |
| 402 | 企业余额不足 | 充值后重试 |
| 404 | 批次不存在或属于其他企业（越权保护） | 检查 batch_id |

批次状态语义：`failed` 时读 `error_message`（含Excel行级校验错误，如"第3行：企业名称必填"）；
`completed` 时 `summary.warnings` 为复核提示（如两阶段间隔、180天滚动额度），不影响结果文件。

## 30. 重要响应字段补充（OpenAPI 未建模）

以下接口未声明响应模型，除上文参数/请求体外，补充其关键响应字段：

### POST `/api/v1/auth/login` 响应

```json
{
  "token": "JWT令牌",
  "user": {
    "id": 1, "username": "admin", "display_name": "管理员", "role": "admin",
    "permissions": [], "enterprise_id": null,
    "enterprise": {"enterprise_id": 1, "enterprise_name": "…", "ent_code": "…", "token_balance": null},
    "must_change_password": false,
    "pwd_rule": "密码至少8位，且必须同时包含大写字母、小写字母、数字和特殊符号",
    "phone": "13800000000"
  }
}
```

- `must_change_password=true` 时，前端强制弹窗改密后才能进入系统。
- `GET /api/v1/auth/me` 返回同结构（多 `last_login_at`，无 token）。

### 创建账号类接口的随机初始密码

密码留空时后端随机生成12位强密码，**仅在创建响应中返回一次**：

| 接口 | 响应字段 |
|------|----------|
| `POST /api/v1/users` | `initial_password`（附 id/username/display_name/role/permissions/message） |
| `POST /api/v1/enterprises` | `admin_initial_password`（附 id/ent_code/ent_name/admin_username/token_balance/message） |
| `POST /api/v1/enterprise/members` | `initial_password`（附 id/username/message） |

随机初始密码创建的账号 `must_change_password=true`，首次登录强制改密。

### 短信验证码规则（找回密码/绑定手机）

- 验证码6位数字，5分钟有效，一次性使用，连续错5次作废；
- 同一手机号60秒限发1次、每天限发3次；
- `POST /api/v1/auth/send-reset-code` 对未绑定手机号返回相同文案（防枚举），不泄露绑定状态；
- 短信服务未配置（.env 无 SMS_UID/SMS_KEY）时，发送类接口返回400"短信服务未配置，请联系管理员重置密码"。


## 附录

### 数据字典

#### ISO 体系代码

| code | 简称 | 全称 |
|------|------|------|
| A0101 | QMS | 质量管理体系 (ISO 9001) |
| A0102 | EC9000 | 质量管理体系-特殊领域 (CNAS-EC9000) |
| A0201 | EMS | 环境管理体系 (ISO 14001) |
| A0301 | OHSMS | 职业健康安全管理体系 (ISO 45001) |
| A0901 | EnMS | 能源管理体系 (ISO 50001) |
| A0501 | ISMS | 信息安全管理体系 (ISO 27001) |
| A0601 | ITSMS | 信息技术服务管理体系 (ISO 20000) |
| A04 | FSMS | 食品安全管理体系 (ISO 22000) |
| A05 | HACCP | 危害分析与关键控制点体系 |

#### 文档类型 (doc_type)

| 值 | 说明 |
|----|------|
| `domain_report` | 领域分析报告 |
| `cnas_rule` | CNAS 认可规范文档 |
| `sub_sop` | 子类别 SOP |
| `domain_sop` | 领域级 SOP |

#### 风险等级 (risk_level)

| 值 | 含义 |
|----|------|
| 1 | 高风险 |
| 2 | 中风险 |
| 3 | 低风险 |
