niuniu/gaokao-volunteer-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ef4bb462953a5a6c536e9aeb3ce8e8eea01e37ae
gaokao-volunteer-system/docs/TECH_ARCHITECTURE.md
Hermes Agent 56a9327e78 feat: 技术架构设计 + 详细实施计划 
根据产品规划设计完成技术设计和实施分解：

1. docs/TECH_ARCHITECTURE.md（新，587行）
   - 分层架构图（接入层/网关/服务/数据/基础设施）
   - 技术栈选型（Python + SQLite + FastAPI）
   - 核心模块设计：
     * AI审核服务（49元版）
     * 反扎堆检测
     * 数据溯源
     * 订单管理
   - 数据架构与目录结构
   - 安全设计（脱敏/权限/审计）
   - 性能指标
   - 11项技术决策记录

2. docs/IMPLEMENTATION_PLAN.md（新，432行）
   - 5大开发任务（30天）
   - T1: AI审核服务（10天，P0核心）
   - T2: 反扎堆检测（5天，P0）
   - T3: 数据溯源（5天，P1）
   - T4: 订单管理（5天，P1）
   - T5: 集成测试（5天，P0）
   - 详细周计划（4周）
   - 每个Task的DoD
   - 风险与应对

3. docs/plans/ 新增3份详细计划：
   - T1-1-crowd-db-setup.md (扎堆数据库，3个子任务)
   - T1-2-audit-skill-and-parser.md (Skill+解析器)
   - T1-4-to-1-10-audit-completion.md (T1.4-1.8完整代码)

4. docs/NAVIGATION.md 更新
   - 添加新文档索引

每个实施计划都包含：
- TDD流程（写测试→失败→实现→通过→提交）
- 完整可复制代码
- 精确文件路径
- 验证命令和预期输出
- 提交步骤

技术决策：
- 选用SQLite（本地优先，零配置）
- FastAPI作为Web框架
- 扎堆数据库手动维护（合规考虑）
- 数据溯源JSON文件存储（Git友好）
2026-06-12 09:18:52 +08:00

714 lines
25 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 技术架构设计
## 高考志愿填报智能系统 v2.1
**版本**: v2.1
**状态**: 设计中
**最后更新**: 2026-06-11
---
## 1. 架构总览
### 1.1 分层架构
```
┌─────────────────────────────────────────────────────────────────┐
│ 用户接入层 (Channels) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 闲鱼聊天 │ │ 微信私聊 │ │ Web/H5 │ │ 客户端 │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │
│ │ │ │ │ │
│ └─────────────┴─────────────┴─────────────┘ │
│ ▼ │
├─────────────────────────────────────────────────────────────────┤
│ 接入网关层 (Gateway) │
│ ┌──────────────────────────────────────────────────────┐ │
│ │ 消息路由 │ 协议适配 │ 鉴权 │ 限流 │ 监控 │ 日志 │ │
│ └──────────────────────────────────────────────────────┘ │
│ ▼ │
├─────────────────────────────────────────────────────────────────┤
│ 业务服务层 (Services) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 咨询会话 │ │ 方案生成 │ │ AI审核 │ │
│ │ Conversation │ │ PlanGen │ │ Audit │ │
│ ├──────────────┤ ├──────────────┤ ├──────────────┤ │
│ │ 规范检查 │ │ 反扎堆检测 │ │ 数据溯源 │ │
│ │ Checker │ │ AntiCrowd │ │ Trace │ │
│ ├──────────────┤ ├──────────────┤ ├──────────────┤ │
│ │ 报告生成 │ │ 订单管理 │ │ 用户管理 │ │
│ │ Report │ │ Order │ │ User │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ▼ │
├─────────────────────────────────────────────────────────────────┤
│ 数据支撑层 (Data) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 省份规则库 │ │ 院校数据库 │ │ 案例库 │ │
│ │ (27省) │ │ (2025位次) │ │ (咨询档案) │ │
│ ├──────────────┤ ├──────────────┤ ├──────────────┤ │
│ │ 用户表 │ │ 订单表 │ │ 报表表 │ │
│ │ (脱敏) │ │ (多渠道) │ │ (统计) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ ▼ │
├─────────────────────────────────────────────────────────────────┤
│ 基础设施层 (Infra) │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Python 3.10+ │ │ SQLite │ │ LocalFS │ │
│ │ FastAPI │ │ (本地优先) │ │ (本地文件) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
### 1.2 核心设计原则
| 原则 | 说明 |
| -------------- | ------------------------------- |
| **本地优先** | 默认本地存储/处理，云端可选 |
| **简单可执行** | 不引入复杂中间件，Python + 文件 |
| **单一来源** | 27省规则库为唯一政策真源 |
| **数据脱敏** | 敏感字段加密/脱敏处理 |
| **可审计** | 所有操作可追溯 |
| **可扩展** | 模块化设计，易于新增省份/功能 |
---
## 2. 技术栈选型
### 2.1 当前(v2.0)技术栈
```
├── 核心语言
│ └── Python 3.10+
│
├── 现有模块（已实现）
│ ├── gaokao-college-advisor/ # 基础顾问Skill
│ ├── gaokao-spec-checker/ # 规范检查V2
│ ├── zhangxuefeng-skillset/ # 张雪峰风格Skill
│ └── gaokao-counselor-long/ # 龙老师Skill
│
├── 数据处理
│ ├── 省份规则: hardcoded in scripts
│ ├── 院校数据: inline text/template
│ └── 用户档案: 临时文件存储
│
├── 报告输出
│ ├── Markdown (简单)
│ ├── HTML (weasyprint)
│ └── PDF (weasyprint)
│
└── 命令行入口
├── gaokao-checker
├── gaokao-quick-3min.py
└── gaokao-visual-report-v2.py
```
### 2.2 v2.1新增技术栈
```
├── AI审核服务
│ ├── 方案解析: PDF (pdfplumber) / 文本 / 截图(OCR待定)
│ ├── 政策检查: 调用 gaokao-spec-checker
│ ├── 扎堆检测: 大厂AI推荐数据库(本地JSON)
│ └── 报告生成: weasyprint (PDF)
│
├── 反扎堆检测
│ ├── 推荐库: JSON文件 (data/crowd_db/)
│ ├── 比对算法: Python fuzzy match
│ └── 风险评估: 规则引擎
│
├── 数据溯源
│ ├── 数据标注: extend data model
│ ├── 置信度: 元数据字段
│ └── 来源链接: URL字段
│
└── 订单管理（v2.1）
├── 存储: SQLite (data/orders.db)
├── API: 简单的CRUD
└── Web: 暂用管理后台CLI
```
### 2.3 技术选型原则
| 维度 | 选择 | 理由 |
| ----------- | ------------- | ---------------------- |
| **语言** | Python 3.10+ | 现有代码基础，无需切换 |
| **存储** | SQLite + 文件 | 本地优先，零配置 |
| **Web框架** | FastAPI | 轻量、自动文档、异步 |
| **PDF** | weasyprint | 已用，成熟方案 |
| **前端** | 待定 | 2027年Q2再决定 |
| **部署** | 单机 | 用户基数小，无需集群 |
---
## 3. 核心模块设计
### 3.1 AI审核服务（49元版）
#### 模块结构
```
skills/gaokao-audit/
├── SKILL.md # 角色定义
├── scripts/
│ ├── audit_service.py # 主服务
│ ├── plan_parser.py # 方案解析（PDF/文本）
│ ├── crowd_detector.py # 扎堆检测
│ ├── checker_integration.py # 调用规范检查
│ ├── report_generator.py # 报告生成
│ └── data/
│ └── crowd_db.json # 大厂AI推荐数据库
├── templates/
│ └── audit_report.html # 审核报告模板
├── examples/
│ └── audit_demo.md
└── tests/
└── test_audit.py
```
#### 关键数据流
```
用户上传方案（PDF/文本/截图）
↓
plan_parser.py 解析
↓
提取：考生信息 + 院校列表 + 专业组
↓
checker_integration.py 调用规范检查
↓
crowd_detector.py 检测扎堆
↓
综合生成审核结果
↓
report_generator.py 输出PDF
↓
交付用户
```
#### 关键接口
```python
# 审核服务接口
def audit_plan(plan_content: str, plan_format: str) -> AuditResult:
"""
审核大厂AI生成的志愿方案
Args:
plan_content: 方案内容（PDF文本/原始文字）
plan_format: 'pdf_text' | 'text' | 'screenshot_ocr'
Returns:
AuditResult: {
'policy_errors': [...], # 政策错误
'crowd_risks': [...], # 扎堆风险
'data_issues': [...], # 数据问题
'suggestions': [...], # 修正建议
'overall_score': int, # 综合评分 0-100
}
"""
```
---
### 3.2 反扎堆检测
#### 数据模型
```python
# 大厂AI推荐数据库
{
"湖南省": {
"578分": { # 分数段
"院校": [
{
"name": "长沙理工大学",
"major": "会计学",
"frequency": 4, # 4个大厂AI都推荐
"risk_level": "high", # high/medium/low
"predicted_increase": 18, # 预测分数线上涨
"alternatives": [ # 替代推荐
{"name": "湖南工商大学", "major": "会计学", "score": 95},
{"name": "湖北经济学院", "major": "财务管理", "score": 92},
]
}
]
}
}
}
```
#### 检测算法
```python
def detect_crowd_risk(plan: List[Volunteer], user_score: int) -> List[CrowdRisk]:
"""
检测扎堆风险
1. 遍历用户方案中的每条志愿
2. 在 crowd_db.json 中查询该院校是否被大厂AI高频推荐
3. 根据 frequency 和 predicted_increase 评估风险等级
4. 返回风险列表 + 替代方案
"""
```
#### 数据来源策略
- **初始数据**: 手动整理6-8月期间各AI平台公开推荐
- **更新机制**: 每周手动更新（避免爬虫合规风险）
- **数据规模**: 预计每省50-100条热门推荐
---
### 3.3 数据溯源
#### 数据模型扩展
```python
# 院校数据扩展
class College:
name: str
# ... 现有字段
# 新增溯源字段
source: str # "湖南省教育考试院" / "阳光高考" / ...
source_url: str # 原始数据链接
source_type: str # "official" / "report" / "estimated"
data_year: int # 数据年份
confidence: float # 置信度 0-1
last_updated: date # 最后更新日期
verified_by: str # 验证人
```
#### 报告展示
```
推荐院校：湖南工商大学
─────────────────────────────
【2025年录取数据】
✓ 最低分：565分
来源：湖南省教育考试院
链接：http://jyt.hunan.gov.cn/...
数据日期：2025-08-15
置信度：★★★★★ (官方)
✓ 位次：28,500名
来源：湖南省教育考试院
链接：http://jyt.hunan.gov.cn/...
数据日期：2025-08-15
置信度：★★★★★ (官方)
【专业满意度】⭐⭐⭐⭐☆ 4.2/5
来源：阳光高考平台
链接：https://gaokao.chsi.com.cn/...
样本量：234位在校生
置信度：★★★★☆ (官方平台)
【就业数据】
⚠️ 就业率：92%
来源：湖南工商大学2024年就业质量报告
数据日期：2024-12-30
置信度：★★★☆☆ (学校自报)
⚠️ 平均薪资：5800元/月
来源：同上
数据日期：2023届
置信度：★★★☆☆ (学校自报)
─────────────────────────────
📌 以上数据为2025年，2026年实际以官方公布为准
```
---
### 3.4 订单管理
#### 数据模型
```python
class Order:
id: str # 订单号
source: str # 'xianyu' | 'wechat' | 'web' | 'school'
external_id: str # 外部订单号（闲鱼订单号/微信备注）
service_version: str # 'audit' | 'basic' | 'standard' | 'premium'
amount: int # 金额（分）
status: str # 'pending' | 'paid' | 'serving' | 'delivered' | 'completed' | 'refunded'
# 客户信息
customer_name: str # 脱敏存储
customer_phone: str # 加密存储
customer_wechat: str
# 考生信息
candidate_name: str # 脱敏存储
candidate_province: str
candidate_score: int
candidate_rank: int
candidate_subjects: List[str]
candidate_interests: str
candidate_strong_subjects: str
candidate_weak_subjects: str
candidate_family: str
# 服务信息
assigned_consultant: str # 分配给谁
plan_file: str # 方案文件路径
audit_report: str # 审核报告路径
pdf_path: str # PDF报告路径
# 时间戳
created_at: datetime
paid_at: datetime
started_at: datetime
delivered_at: datetime
completed_at: datetime
# 元数据
notes: str
tags: List[str]
upgrade_from: str # 升级来源订单
```
#### API设计
```python
# REST API (FastAPI)
POST /api/orders # 创建订单
GET /api/orders # 列表
GET /api/orders/{id} # 详情
PATCH /api/orders/{id} # 更新
POST /api/orders/{id}/pay # 标记支付
POST /api/orders/{id}/deliver # 标记交付
POST /api/orders/{id}/refund # 退款
POST /api/orders/{id}/upgrade # 升级订单
GET /api/orders/stats # 统计
```
---
## 4. 数据架构
### 4.1 目录结构
```
gaokao-volunteer-system/
├── data/ # 数据目录
│ ├── colleges/ # 院校数据
│ │ ├── hunan.json # 湖南省院校
│ │ ├── zhejiang.json # 浙江省院校
│ │ └── ...
│ ├── rules/ # 规则数据
│ │ ├── provinces.json # 省份规则汇总
│ │ └── errors.json # 错误模式
│ ├── crowd_db/ # 扎堆检测数据库
│ │ ├── hunan.json # 湖南大厂AI推荐
│ │ └── ...
│ ├── sources.json # 数据溯源元数据
│ └── orders.db # 订单数据库(SQLite)
│
├── skills/
│ ├── gaokao-audit/ # 新增: AI审核Skill
│ ├── gaokao-college-advisor/
│ ├── gaokao-spec-checker/
│ ├── gaokao-counselor-long/
│ └── zhangxuefeng-skillset/
│
├── scripts/ # 命令行工具
│ ├── gaokao-checker
│ ├── gaokao-audit # 新增: AI审核CLI
│ ├── gaokao-crowd-detector # 新增: 扎堆检测CLI
│ └── ...
│
├── tests/ # 测试
│ ├── test_audit.py # 新增
│ ├── test_crowd.py # 新增
│ ├── test_data_trace.py # 新增
│ └── test_orders.py # 新增
│
└── docs/ # 文档
├── ARCHITECTURE.md # 架构文档
├── API.md
└── plans/ # 实施计划
```
### 4.2 数据流图
```
┌─────────────────┐
│ 用户咨询数据 │ (省份、分数、选科等)
└────────┬────────┘
│
▼
┌─────────────────┐ ┌──────────────────┐
│ 会话状态管理 │◄────│ 27省规则库 │
│ (in-memory) │ │ (PROVINCE_RULES) │
└────────┬────────┘ └──────────────────┘
│
▼
┌─────────────────────────────────────────────┐
│ 方案生成引擎 │
│ - 兴趣匹配 (RIASEC) │
│ - 学科强弱匹配 │
│ - 家庭情况匹配 │
│ - 反扎堆检测 │
└────────┬────────────────────────────────────┘
│
▼
┌─────────────────┐
│ 规范检查器V2 │ ◄── 调用 ──► 错误模式库
│ (自动) │ (15种)
└────────┬────────┘
│
▼
┌─────────────────┐
│ 报告生成 │ ──► PDF/HTML/Markdown
│ (含数据溯源) │
└─────────────────┘
```
---
## 5. 性能设计
### 5.1 性能目标
| 指标 | 目标值 | 当前 |
| ------------ | ------- | ---- |
| 单次咨询响应 | < 5秒 | ✅ |
| 方案生成时间 | < 10秒 | ✅ |
| 审核报告生成 | < 30秒 | 🆕 |
| 报告PDF生成 | < 5秒 | ✅ |
| 并发支持 | 10用户 | ⏳ |
| 数据库查询 | < 100ms | ✅ |
### 5.2 优化策略
- **缓存**: 规则库内存常驻
- **异步**: I/O密集操作异步化
- **批处理**: 批量PDF生成
- **CDN**: 静态资源（暂不需要）
---
## 6. 安全设计
### 6.1 数据安全
| 数据 | 处理方式 | 存储位置 |
| -------- | ---------------- | -------- |
| 手机号 | AES加密 | SQLite |
| 姓名 | 脱敏显示 | SQLite |
| 订单内容 | 明文（业务需要） | SQLite |
| 支付信息 | 不存储 | - |
| PDF报告 | 文件存储 | LocalFS |
### 6.2 访问控制
```python
# 权限设计
class Role:
SUPER_ADMIN = "super_admin" # 全部权限
PRODUCT = "product" # 产品经理
OPERATIONS = "operations" # 运营
ANALYST = "analyst" # 数据分析师
CONSULTANT = "consultant" # 顾问
CUSTOMER_SERVICE = "cs" # 客服
# 资源权限
PERMISSIONS = {
Role.SUPER_ADMIN: ["*"],
Role.PRODUCT: ["orders:read", "users:read", "data:export"],
Role.OPERATIONS: ["orders:read", "orders:write", "users:read"],
# ...
}
```
### 6.3 操作审计
```python
class AuditLog:
user_id: str
action: str # "view_order" / "create_order" / ...
resource_type: str # "order" / "user" / "data"
resource_id: str
timestamp: datetime
ip_address: str
details: dict
```
---
## 7. 部署架构
### 7.1 v2.1 部署方案（本地优先）
```
┌─────────────────────────────────────────┐
│ 用户本地机器 │
├─────────────────────────────────────────┤
│ │
│ ┌────────────────────────────────┐ │
│ │ Python Runtime (3.10+) │ │
│ │ ┌──────────────────────────┐ │ │
│ │ │ FastAPI Server │ │ │
│ │ │ (管理后台 + API) │ │ │
│ │ │ Port: 8000 │ │ │
│ │ └──────────────────────────┘ │ │
│ │ ┌──────────────────────────┐ │ │
│ │ │ Hermes Skills │ │ │
│ │ │ (gaokao-* 系列) │ │ │
│ │ └──────────────────────────┘ │ │
│ └────────────────────────────────┘ │
│ ┌────────────────────────────────┐ │
│ │ SQLite Database │ │
│ │ (data/orders.db) │ │
│ └────────────────────────────────┘ │
│ ┌────────────────────────────────┐ │
│ │ File Storage │ │
│ │ (data/reports/, data/audits/) │ │
│ └────────────────────────────────┘ │
│ │
└─────────────────────────────────────────┘
```
### 7.2 数据备份
- **自动备份**: 每日定时打包 `data/` 目录
- **Git版本**: 规则库和错误模式库Git管理
- **异地**: 3个远程仓库同步（已完成）
---
## 8. 集成设计
### 8.1 Skills间的调用关系
```
gaokao-counselor-long (主)
├── 调用 gaokao-college-advisor (方案生成)
├── 调用 gaokao-spec-checker (规范检查)
├── 调用 gaokao-audit (新: AI审核) 🆕
└── 调用反扎堆检测模块 🆕
gaokao-audit (新)
├── 调用 gaokao-spec-checker
├── 调用反扎堆检测
└── 生成审核报告
数据溯源模块
├── 院校数据扩展
└── 报告展示增强
```
### 8.2 命令行集成
```bash
# 现有
gaokao-checker plan.txt # 规范检查
gaokao-visual-report-v2.py # 生成报告
gaokao-quick-3min.py # 问卷
# 新增
gaokao-audit plan.pdf # AI方案审核 🆕
gaokao-crowd-detect volunteer.json # 扎堆检测 🆕
gaokao-data-trace college.json # 数据溯源查询 🆕
gaokao-order-manager # 订单管理CLI 🆕
```
---
## 9. 监控设计
### 9.1 业务指标
| 指标 | 计算方式 | 告警阈值 |
| -------------- | --------- | -------- |
| 方案生成成功率 | 成功/总数 | <90% |
| 审核报告生成 | 成功/总数 | <95% |
| 扎堆检测准确率 | 抽样核对 | <85% |
| 订单创建成功率 | 成功/总数 | <95% |
### 9.2 技术指标
| 指标 | 监控方式 | 告警阈值 |
| ----------- | -------- | -------- |
| API响应时间 | 日志统计 | >5s |
| 错误率 | 日志统计 | >5% |
| 数据库大小 | 文件大小 | >1GB |
---
## 10. 演进路径
### Phase 1: v2.1 (2026年6-7月) - 当前
- AI审核服务
- 反扎堆检测
- 数据溯源增强
- 订单管理基础
### Phase 2: v2.2 (2026 Q3-Q4) - 下一阶段
- Web后台界面
- 数据自动化对接
- 案例库完善
### Phase 3: v2.3 (2027 Q1-Q2) - Web端上线
- 用户端Web界面
- 完整支付集成
- 多端PWA
### Phase 4: v3.0 (2027 Q3+) - 规模化
- 服务端部署
- 高级智能推荐
- 商业化完善
---
## 11. 技术决策记录
### TD001: 选用SQLite而非PostgreSQL
**决策**: SQLite
**理由**:
- 本地优先架构
- 零配置、零维护
- 用户基数小（<10万）
- 后续可平滑迁移到PostgreSQL
### TD002: FastAPI作为Web框架
**决策**: FastAPI
**理由**:
- Python生态
- 自动API文档
- 异步支持
- 性能良好
### TD003: 数据溯源本地JSON存储
**决策**: JSON文件
**理由**:
- 简单查询
- 易于编辑
- 无数据库依赖
- 便于Git版本管理
### TD004: 扎堆数据库手动维护
**决策**: 人工整理
**理由**:
- 避免爬虫合规风险
- 数据准确性高
- 维护成本可接受
- 后续可半自动化
---
**下一步**: 查看 [实施计划](IMPLEMENTATION_PLAN.md)
Reference in New Issue View Git Blame Copy Permalink