503 lines
8.8 KiB
Markdown
503 lines
8.8 KiB
Markdown
# 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 <input>`
|
||
- `python3 scripts/gaokao-order-manager ...`
|
||
- `python3 scripts/gaokao-data-trace <school_name>`
|
||
- `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": "<jwt>",
|
||
"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 <token>
|
||
```
|
||
|
||
---
|
||
|
||
### 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 输出路径；默认 `<input>.audit.pdf`
|
||
- `--format`：`text | pdf_text | screenshot_ocr`
|
||
- `--json`：额外输出审核结果 JSON
|
||
|
||
标准输出包含：
|
||
|
||
- 输入文件路径
|
||
- 识别省份
|
||
- 综合评分
|
||
- PDF 报告路径
|
||
- 可选 JSON payload
|
||
|
||
主链能力：
|
||
|
||
- 方案解析
|
||
- 规范检查集成
|
||
- 扎堆风险检测
|
||
- HTML/PDF 报告输出
|
||
|
||
---
|
||
|
||
### 3.2 订单管理 CLI
|
||
|
||
入口：`python3 scripts/gaokao-order-manager`
|
||
|
||
通用参数：
|
||
|
||
- `--db <path>`：订单库路径，默认 `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 <order_id>
|
||
python3 scripts/gaokao-order-manager --db data/orders.db deliver <order_id>
|
||
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. 本文档
|