# API 参考（当前真相）
本文档描述 2026-06-13 当前仓库中已落地、可验证的接口与命令行入口。
适用范围：
- 管理后台 FastAPI API
- 已交付 CLI（审核 / 订单 / 数据溯源）
- 关键数据契约与鉴权约定
不包含：
- 旧版 `spec_checker_v2.py` 的逐函数说明
- 尚未落地的用户端 Web 自助下单/支付/资料填写闭环
---
## 1. 当前接口面
### 1.1 HTTP / FastAPI
服务入口：`python3 -m admin.app --port 8000`
基础约定：
- 健康检查：`GET /health`
- 登录：`POST /api/auth/login`
- Bearer 鉴权：除 `/health`、`/dashboard`、`/s/{code}` 外，管理 API 默认需要 JWT
- OpenAPI：`GET /openapi.json`
- Swagger：`GET /docs`
### 1.2 CLI
当前仓库内已落地的主要 CLI：
- `python3 -m skills.gaokao-audit.scripts.audit_cli `
- `python3 scripts/gaokao-order-manager ...`
- `python3 scripts/gaokao-data-trace `
- `python3 scripts/gaokao-quick-3min.py`
- `python3 scripts/gaokao-channel-fallback ...`
---
## 2. 管理后台 HTTP API
### 2.1 健康检查
#### `GET /health`
用途：进程/配置级健康检查。
响应示例：
```json
{
"status": "ok"
}
```
---
### 2.2 认证 API
#### `POST /api/auth/login`
用途：管理员登录，获取 Bearer JWT。
请求体：
```json
{
"username": "admin",
"password": "admin123"
}
```
成功响应：
```json
{
"access_token": "",
"token_type": "bearer",
"expires_in": 3600,
"user": {
"id": "...",
"username": "admin",
"role": "admin"
}
}
```
使用方式：
```bash
curl -X POST http://127.0.0.1:8000/api/auth/login \
-H 'Content-Type: application/json' \
-d '{"username":"admin","password":"admin123"}'
```
#### `GET /api/auth/me`
用途：获取当前登录管理员信息。
请求头：
```text
Authorization: Bearer
```
---
### 2.3 元数据 API
#### `GET /api/meta`
用途：返回后台前端使用的枚举/元信息。
典型用途：
- 订单状态枚举
- 来源渠道枚举
- 服务版本枚举
- 案例审核状态等
---
### 2.4 用户 API（T6.3）
#### `GET /api/users`
用途：分页列出用户，默认返回脱敏字段。
常见查询参数：
- `limit`
- `offset`
- 其他筛选项以 OpenAPI 为准
#### `GET /api/users/{user_key}`
用途：查看单个用户详情。
说明：`user_key` 可为内部 id 或路由支持的用户标识。
---
### 2.5 订单 API（T6.4）
#### `GET /api/orders`
用途：分页列出订单。
常见查询参数：
- `status`
- `source`
- `limit`
- `offset`
说明：
- 列表默认走脱敏输出
- 不应依赖该接口获取完整明文手机号/身份证号
#### `GET /api/orders/export`
用途：导出订单 CSV。
说明：
- 当前导出路径复用后台查询条件
- 输出仍遵循后台脱敏边界
- 如需对外发送报表，建议二次审核 CSV 内容
#### `GET /api/orders/{order_id}`
用途：查看订单详情与状态历史。
#### `POST /api/orders`
用途：手工录单。
典型字段：
```json
{
"source": "xianyu",
"service_version": "audit",
"amount_cents": 4900,
"customer_name": "王家长",
"customer_phone": "13800001234",
"candidate_name": "李明",
"candidate_province": "湖南",
"candidate_score": 578,
"candidate_rank": 26800
}
```
说明：
- `external_id` 可留空，支持人工补录
- 写路径复用 `OrdersDAO` 状态机与落库逻辑
#### `PATCH /api/orders/{order_id}`
用途：更新订单业务字段、推进状态、处理退款。
说明：
- 非法状态流转会被拒绝
- 订单状态机为：`pending -> paid -> serving -> delivered -> completed`，另有 `refunded`
- 文档应以 OpenAPI 和 `data/orders/state_machine.py` 为最终事实源
---
### 2.6 案例 API（T6.5）
#### `GET /api/cases`
用途：案例列表。
#### `POST /api/cases`
用途：创建案例。
#### `GET /api/cases/{case_id}`
用途：查看案例详情。
#### `PATCH /api/cases/{case_id}`
用途：更新案例。
#### `POST /api/cases/{case_id}/review`
用途：案例审核。
#### `DELETE /api/cases/{case_id}`
用途：删除案例。
---
### 2.7 统计 API（T6.2）
#### `GET /api/stats/dashboard`
用途：一站式仪表盘数据。
响应结构：
- `summary`
- `by_status`
- `by_source`
- `by_service_version`
- `trends`
- `generated_at`
关键口径：
- 收入 = `paid / serving / delivered / completed` 四态订单的 `amount_cents` 累计值
- `pending`、`refunded` 不计入收入
- 趋势桶粒度为天（UTC）
- 空日期补 0，前端得到稠密序列
- 统计路径不读取 PII
#### `GET /api/stats/orders`
用途：兼容订单统计接口；字段名沿用早期 stub 版本，但已接真实 SQL 聚合。
---
### 2.8 UI 路由
#### `GET /dashboard`
用途：极简后台仪表盘页面。
说明：
- 页面本身可公开访问
- 数据请求仍依赖登录态/JWT
#### `GET /s/{code}`
用途：分享页短链接访问入口。
说明：
- 由 `data/share/short_link.py` 与 `admin/share_page.py` 提供能力
- 权限控制支持 `read/comment/edit/admin`
---
## 3. CLI 接口
### 3.1 AI 审核 CLI
入口：`python3 -m skills.gaokao-audit.scripts.audit_cli`
命令格式：
```bash
python3 -m skills.gaokao-audit.scripts.audit_cli plan.txt \
--output plan.audit.pdf \
--format text \
--json
```
参数：
- `input`：方案文件路径
- `--output`：PDF 输出路径；默认 `.audit.pdf`
- `--format`：`text | pdf_text | screenshot_ocr`
- `--json`：额外输出审核结果 JSON
标准输出包含：
- 输入文件路径
- 识别省份
- 综合评分
- PDF 报告路径
- 可选 JSON payload
主链能力：
- 方案解析
- 规范检查集成
- 扎堆风险检测
- HTML/PDF 报告输出
---
### 3.2 订单管理 CLI
入口：`python3 scripts/gaokao-order-manager`
通用参数：
- `--db `：订单库路径，默认 `data/orders.db`
- `--human`：终端友好文本输出；默认 JSON
- `--actor`：操作者标识
已落地子命令：
- `create`
- `list`
- `show`
- `update`
- `pay`
- `deliver`
- `upgrade`
- `stats`
- `export`
示例：
```bash
python3 scripts/gaokao-order-manager --db data/orders.db create \
--source xianyu \
--service-version audit \
--amount-cents 4900 \
--customer-name 王家长 \
--customer-phone 13800001234 \
--candidate-name 李明 \
--candidate-province 湖南 \
--candidate-score 578
```
```bash
python3 scripts/gaokao-order-manager --db data/orders.db pay
python3 scripts/gaokao-order-manager --db data/orders.db deliver
python3 scripts/gaokao-order-manager --db data/orders.db export --output orders.csv
```
行为约束：
- 详情默认返回状态历史
- `update` 仅允许业务字段，`status` 不允许直接硬改
- 状态流转必须走状态机
- 默认输出经过 `Order.to_dict()` 脱敏处理
---
### 3.3 数据溯源 CLI
入口：`python3 scripts/gaokao-data-trace`
命令格式：
```bash
python3 scripts/gaokao-data-trace "中南大学"
python3 scripts/gaokao-data-trace "中南大学" --human
```
参数：
- `school_name`：院校名称，支持包含匹配
- `--human`：终端友好输出；默认 JSON
输出字段：
- `province`
- `school`
- `major`
- `frequency`
- `platforms`
- `predicted_increase`
- `alternatives`
- `score_range`
- `data_year`
- `source`
- `source_url`
- `source_type`
- `confidence`
- `last_updated`
用途：
- 查询某院校/专业推荐的来源信息
- 向审核报告补充“为什么这样推荐”的数据依据
---
## 4. 关键数据契约
### 4.1 订单状态机
当前文档级约定：
- `pending`
- `paid`
- `serving`
- `delivered`
- `completed`
- `refunded`
注意：
- 直接写状态属于越界使用
- HTTP 与 CLI 都应复用 `OrdersDAO.transition_status()`
### 4.2 订单隐私边界
默认脱敏字段包括但不限于：
- 手机号
- 身份证号
- 部分姓名
明文敏感数据不应通过普通列表接口、CSV 报表或分享页直接暴露。
### 4.3 统计口径
仪表盘与统计接口共享以下前提：
- `GAOKAO_DB_PATH`：admin 用户库
- `GAOKAO_ORDERS_DB_PATH`：订单库
- 收入统计只看订单金额和状态，不读取 PII
---
## 5. 环境变量
常用运行变量：
- `GAOKAO_ENV`
- `GAOKAO_DB_PATH`
- `GAOKAO_ORDERS_DB_PATH`
- `GAOKAO_JWT_SECRET`
- `GAOKAO_ADMIN_USER`
- `GAOKAO_ADMIN_PASS`
- `GAOKAO_ORDERS_FERNET_KEY`
最低要求：
- 生产环境必须提供高熵 `GAOKAO_JWT_SECRET`
- 订单/用户相关路径需要 `GAOKAO_ORDERS_FERNET_KEY`
- 生产环境不得使用默认弱口令 `admin123`
---
## 6. 验证建议
查看最新 API 真相：
```bash
python3 -m admin.app --port 8000
curl http://127.0.0.1:8000/openapi.json
```
验证 T5 主链测试：
```bash
python3 -m pytest tests/test_t5_e2e_workflows.py tests/test_t5_performance.py -q
```
如本文与代码不一致，优先级顺序为：
1. 代码与实跑结果
2. OpenAPI / CLI `--help`
3. 本文档