# 技术领域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 | 服务器内部错误 |

### 接口总览（共 344 个）

| 章节 | 模块 | 接口数 |
|------|------|--------|
| 1 | 认证与账号安全 | 8 |
| 2 | 用户管理（平台） | 7 |
| 3 | 企业管理（平台） | 8 |
| 4 | 企业侧功能（企业管理员） | 10 |
| 5 | ISO 体系与领域 | 5 |
| 6 | AI 分析 | 10 |
| 7 | 领域分组 | 21 |
| 8 | 知识库与报告 | 11 |
| 9 | SOP 与文档模板 | 15 |
| 10 | 审核员专业评价 | 20 |
| 11 | 技术专家评价 | 8 |
| 12 | 学习资料与考试 | 19 |
| 13 | 代码评审 | 14 |
| 14 | 数据源管理 | 20 |
| 15 | 系统配置与日志 | 7 |
| 16 | 企业审核指导书 | 4 |
| 17 | AI预审议 | 21 |
| 18 | 不符合整改 | 9 |
| 19 | 体系文件核查（符合性检查） | 34 |
| 20 | 认证规则 | 40 |
| 21 | 标准转版 | 39 |
| 22 | 管理接口与外部 API | 11 |
| 23 | 通用 | 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/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>`

**请求体字段**（模型 `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 对话助手

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| task_id | path | 是 | integer |   |

**请求体字段**（模型 `ChatRequest`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| message | string | 是 | Message |
| system_prompt | string | 否 | System Prompt（默认 ""） |

---

### 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}/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预审议

### GET `/api/v1/pre-review/checklist`

List Checklist

**认证**: 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） |

---

### 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 |   |

---

### GET `/api/v1/pre-review/dict`

Pr Dict

**认证**: 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/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 |   |

---

### GET `/api/v1/pre-review/projects`

List Projects

**认证**: JWT：请求头 `Authorization: Bearer <token>`

---

### POST `/api/v1/pre-review/projects`

Create Project

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**请求体字段**（模型 `app__api__v1__pre_review__ProjectIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| ep_name | string | 是 | Ep Name |
| iso_codes | array<string> | 否 | Iso Codes |
| audit_types | array<string> | 否 | Audit Types |
| scope_text | string | 否 | Scope Text（默认 ""） |

---

### 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}/files`

批量上传审核资料。

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| files | array<string> | 是 | Files |
| category_code | string | 否 | Category Code（默认 "auto"） |

---

### 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}/run`

Run Pre Review

**认证**: 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 |   |

---

## 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}/instances`

创建检查单实例（幂等：已存在则返回现有实例）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| project_id | path | 是 | integer |   |

**请求体字段**（模型 `InstanceCreateIn`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| template_id | integer | 是 | 模板ID |

---

### 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/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 |

---

### 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） |

---

### 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}/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 |   |

**请求体字段**（模型 `Body_batch_confirm_clauses_api_v1_std_convert_projects__pid__clauses_batch_confirm_post`）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| clause_ids | array<integer> | 是 | Clause Ids |

---

### 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}/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/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}/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}/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 |   |

---

### 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/en`

S2 新版英文上传：.docx/.txt 建 en_parse 切块任务（.json 亦支持结构化直传）

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |

---

### POST `/api/v1/std-convert/projects/{pid}/upload/gb`

S1 旧国标上传：.json 即时入库；.docx/.txt 建 gb_parse 切块任务

**认证**: JWT：请求头 `Authorization: Bearer <token>`

**参数**:

| 名称 | 位置 | 必填 | 类型 | 说明 |
|------|------|------|------|------|
| pid | path | 是 | integer |   |

**表单字段**（multipart/form-data）:

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| file | string | 是 | File |

---

### 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/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 |   |

---

## 22. 管理接口与外部 API

### 22.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 |   |

---

### 22.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`

---

## 23. 通用

### GET `/`

Serve Frontend

**认证**: 公开（无需认证）

---

### GET `/api/v1/api-doc`

Get Api Doc

**认证**: 公开（无需认证）

---

### GET `/api/v1/health`

Health

**认证**: 公开（无需认证）

---

## 24. 重要响应字段补充（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 | 低风险 |