gaokao-volunteer-system/docs/API.md

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

用途：进程/配置级健康检查。

响应示例：

{
  "status": "ok"
}

---

2.2 认证 API

POST /api/auth/login

用途：管理员登录，获取 Bearer JWT。

请求体：

{
  "username": "admin",
  "password": "admin123"
}

成功响应：

{
  "access_token": "<jwt>",
  "token_type": "bearer",
  "expires_in": 3600,
  "user": {
    "id": "...",
    "username": "admin",
    "role": "admin"
  }
}

使用方式：

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

用途：获取当前登录管理员信息。

请求头：

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

用途：手工录单。

典型字段：

{
  "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

命令格式：

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

示例：

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

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

命令格式：

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 真相：

python3 -m admin.app --port 8000
curl http://127.0.0.1:8000/openapi.json

验证 T5 主链测试：

python3 -m pytest tests/test_t5_e2e_workflows.py tests/test_t5_performance.py -q

如本文与代码不一致，优先级顺序为：

1. 代码与实跑结果
2. OpenAPI / CLI --help
3. 本文档