niuniu/gaokao-volunteer-system

Fork 0

Files

Hermes Agent 3f46811e49

CI / pytest (Python 3.10) (push) Has been cancelled

Details

CI / pytest (Python 3.11) (push) Has been cancelled

Details

CI / pytest (Python 3.12) (push) Has been cancelled

Details

release: cut v2.1

2026-06-13 14:49:58 +08:00

9.5 KiB

Raw Permalink Blame History

架构设计（当前实现视角）

本文档描述 2026-06-13 当前仓库中已经落地、可验证的系统架构。

一句话定位：

这不是“完整用户端 Web 自助闭环产品”
这是一个“管理后台 + 订单/分享/渠道同步 + AI 审核链路”的可运行系统

1. 架构总览

┌──────────────────────────────────────────────────────────────┐
│                      接入与交互层                            │
│  Hermes Skills   CLI Scripts   Admin FastAPI   Share Page   │
└───────────────┬───────────────┬───────────────┬──────────────┘
                │               │               │
┌───────────────▼──────────────────────────────────────────────┐
│                      应用服务层                              │
│  AI审核编排   订单服务/状态机   分享权限   渠道同步   统计聚合 │
└───────────────┬──────────────────────────────────────────────┘
                │
┌───────────────▼──────────────────────────────────────────────┐
│                       数据与持久化层                         │
│  SQLite(admin/orders/cases/share) + JSON crowd_db + 模板/静态 │
└──────────────────────────────────────────────────────────────┘

核心结论：

管理后台与人工服务交付链已经形成主链
AI 审核从解析 → 规则检查 → 扎堆检测 → 报告输出已经形成统一入口
分享、渠道同步、订单状态机都已有独立模块与测试
用户端 Web 自助注册/下单/支付/资料填写/站内交付主链仍缺失

2. 分层设计

2.1 接入与交互层

当前存在 4 类入口：

Hermes Skills

skills/gaokao-college-advisor/
skills/gaokao-spec-checker/
skills/gaokao-audit/

scripts/gaokao-quick-3min.py
scripts/gaokao-order-manager
scripts/gaokao-data-trace
scripts/gaokao-channel-fallback

管理后台 HTTP API

admin/app.py
admin/routes/*

极简页面

admin/static/dashboard.html
GET /dashboard
GET /s/{code} 分享页

设计意图：

人工顾问/运营同学优先走后台与 CLI
Hermes 对话场景优先走 Skills
对外公开访问当前仅限分享页，不等同于完整用户前台

2.2 应用服务层

A. AI 审核链路

主要模块：

skills/gaokao-audit/scripts/plan_parser.py
skills/gaokao-audit/scripts/checker_integration.py
skills/gaokao-audit/scripts/audit_service.py
skills/gaokao-audit/scripts/report_generator.py
skills/gaokao-audit/scripts/audit_cli.py
data/crowd_db/crowd_detector.py
data/crowd_db/risk_report.py

处理链路：

方案文本/PDF提取/OCR
  → 方案解析
  → 省份规则检查
  → 扎堆风险检测
  → 风险/问题聚合
  → HTML/PDF/JSON 报告输出

说明：

当前 AI 审核主链已经不是“只有零散脚本”
audit_cli.py 是统一编排入口
T5.1 已用端到端测试覆盖“输入方案 → 输出 PDF/JSON 审核报告”主链

B. 订单与交付链路

主要模块：

data/orders/models.py
data/orders/dao.py
data/orders/state_machine.py
data/orders/cli.py
admin/routes/orders.py

职责拆分：

models.py：订单数据模型
dao.py：SQLite 持久化、查询、事务、历史记录
state_machine.py：状态合法性约束
cli.py / routes/orders.py：两种入口，共用同一底层规则

状态机：

pending → paid → serving → delivered → completed
                    └──────────────→ refunded

关键原则：

不允许绕过状态机直接改状态
HTTP 与 CLI 写路径都应落到 DAO + 状态机
敏感字段默认脱敏展示

C. 分享能力

主要模块：

data/share/short_link.py
data/share/permission.py
admin/share_page.py
admin/routes/ui.py

能力：

短链接生成与解析
read/comment/edit/admin 权限模型
报告字段裁剪与脱敏
公开分享页渲染

设计定位：

服务于“人工交付后的分享/查看”
不是完整协作式前台产品

D. 渠道同步

主要模块：

data/channel_sync/webhook_server.py
data/channel_sync/xianyu_adapter.py
data/channel_sync/poller.py
data/channel_sync/audit.py
data/channel_sync/monitor.py

能力：

闲鱼 webhook 接单
poller 兜底补偿
webhook 审计日志
渠道健康巡检与人工 fallback 模板

设计原则：

自动接单优先
审计留痕
异常时可回落到人工补录

E. 后台统计与运营视图

主要模块：

admin/stats.py
admin/routes/stats.py
admin/routes/users.py
admin/routes/cases.py
admin/routes/meta.py

能力：

仪表盘汇总
订单/来源/服务版本分布
时间趋势
用户列表与案例管理
前端枚举元数据输出

2.3 数据与持久化层

SQLite

管理后台库

默认：data/orders/admin.db
内容：管理员、后台业务表、cases 等

订单库

默认：data/orders.db
内容：订单主表、状态历史、渠道同步相关辅助表

分享/短链数据

由 data/share/short_link.py 管理，实际落在 SQLite

JSON / Markdown 数据

crowd_db

路径：data/crowd_db/
内容：院校推荐、来源、置信度、年份等

规则与案例文档

路径：rules/、docs/、product/

模板与静态资源

审核报告模板：skills/gaokao-audit/templates/audit_report.html
分享页/后台静态资源：admin/static/*

3. 核心运行链路

3.1 人工服务主链（当前已落地）

渠道线索/人工录单
  → 订单入库
  → 顾问生成方案
  → AI审核
  → PDF/JSON/方案文件归档
  → 订单推进到 delivered/completed
  → 可选分享页分发

这是当前仓库最成熟、最贴近真实运行的主链。

3.2 后台运营主链（当前已落地）

管理员登录
  → 查看仪表盘/用户/订单/案例
  → 人工录单或补录
  → 状态流转/退款/导出
  → 跟踪渠道与交付情况

3.3 数据溯源查询链（当前已落地）

输入院校名
  → crowd_db 加载各省数据
  → 匹配学校/专业
  → 返回来源、年份、置信度、分数段、替代建议

3.4 性能验证链（T5.2 已落地）

quick-3min 解析+总结+推荐
  → 100 次基准执行
  → 断言总耗时 < 5s

admin FastAPI
  → Locust 10 并发压测
  → 断言聚合成功率 > 95%

4. 当前未落地主链

以下能力仍不应被本文档误描述为“已完成”：

用户端 Web 前台

用户注册/登录
用户自主下单/支付
站内资料填写
用户自助查看报告/订单进度

完整产品化闭环

面向最终考生/家长的独立前端应用
完整邮件/站内消息交付系统
自助支付后的自动任务编排闭环

因此，当前系统真实定位应是：

内部运营与人工服务增强系统：已成形
面向最终用户的完整产品：未完成

5. 安全与边界

5.1 已有防护

JWT 鉴权
生产环境 JWT 弱密钥阻断
管理员弱口令在 prod 阻断
订单敏感字段加密存储
默认脱敏输出
分享页权限分级

5.2 已知风险（截至当前评审）

渠道 webhook 的 X-Forwarded-For 信任边界仍需收紧
登录接口节流/锁定能力不足
CI 不能完整代表 clean env 下的后台可构建性
类型门禁与覆盖率门禁仍未完全闭环

这些属于“工程质量与安全债”，不改变主链已存在的事实，但影响生产可交付性评级。

6. 部署形态

6.1 本地运行

pip install -r requirements-admin.txt -r requirements-dev.txt
export GAOKAO_JWT_SECRET="$(python3 -c 'import secrets; print(secrets.token_hex(32))')"
python3 -m admin.app --port 8000

6.2 Docker Compose

已提供：

Dockerfile
docker-compose.yml
.env.docker.example

适用场景：

本机自测
单机部署验证

不应误解为：

已具备完整云原生、多副本、自动扩缩容架构

7. 真相源优先级

当文档与实现冲突时，按以下顺序判断：

代码与实跑结果
OpenAPI / CLI --help
测试文件（尤其 tests/test_t5_e2e_workflows.py、tests/test_t5_performance.py）
README / CHANGELOG
本文档
历史评审/历史计划文档

8. 验证命令

8.1 启动后台

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

8.2 复核 T5 主链

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

8.3 复核后台接口存在性

python3 -m pytest admin/tests/test_routes.py admin/tests/test_routes_orders.py admin/tests/test_routes_stats_dashboard.py -q

9.5 KiB Raw Permalink Blame History Unescape Escape

架构设计（当前实现视角）

1. 架构总览

2. 分层设计

2.1 接入与交互层

2.2 应用服务层

A. AI 审核链路

B. 订单与交付链路

C. 分享能力

D. 渠道同步

E. 后台统计与运营视图

2.3 数据与持久化层

SQLite

JSON / Markdown 数据

模板与静态资源

3. 核心运行链路

3.1 人工服务主链（当前已落地）

3.2 后台运营主链（当前已落地）

3.3 数据溯源查询链（当前已落地）

3.4 性能验证链（T5.2 已落地）

4. 当前未落地主链

5. 安全与边界

5.1 已有防护

5.2 已知风险（截至当前评审）

6. 部署形态

6.1 本地运行

6.2 Docker Compose

7. 真相源优先级

8. 验证命令

8.1 启动后台

8.2 复核 T5 主链

8.3 复核后台接口存在性

9.5 KiB

Raw Permalink Blame History