gaokao-volunteer-system/docs/ARCHITECTURE.md

# 架构设计

## 🏛️ 整体架构

```
┌─────────────────────────────────────────────────────────────┐
│                       用户交互层                              │
│  ┌─────────────────┐  ┌─────────────────┐                  │
│  │  Hermes对话      │  │  命令行          │                  │
│  └────────┬────────┘  └────────┬────────┘                  │
└───────────┼─────────────────────┼─────────────────────────────┘
            │                     │
┌───────────▼─────────────────────▼─────────────────────────────┐
│                       业务逻辑层                               │
│  ┌──────────────────┐  ┌──────────────────┐                  │
│  │ 3个Hermes Skills │  │ 独立Python脚本   │                  │
│  │ - advisor        │  │ - visual-report  │                  │
│  │ - spec-checker   │  │ - quick-3min     │                  │
│  │ - zhangxuefeng   │  │ - collect-info   │                  │
│  └────────┬─────────┘  └────────┬─────────┘                  │
└───────────┼─────────────────────┼─────────────────────────────┘
            │                     │
┌───────────▼─────────────────────▼─────────────────────────────┐
│                       规则与数据层                             │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐        │
│  │ provinces/   │  │ errors/      │  │ templates/   │        │
│  │ 省份规则     │  │ 错误模式     │  │ 报告模板     │        │
│  └──────────────┘  └──────────────┘  └──────────────┘        │
└───────────────────────────────────────────────────────────────┘
            │
┌───────────▼─────────────────────────────────────────────────────┐
│                       持久化层                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ docs/        │  │ data/        │  │ CHANGELOG.md │          │
│  │ 文档案例     │  │ 示例数据     │  │ 变更历史     │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
└─────────────────────────────────────────────────────────────────┘
```

## 🎯 设计原则

### 1. 关注点分离（Separation of Concerns）

- **Skills**：负责对话式交互
- **脚本**：负责批处理和数据处理
- **规则**：负责业务规则集中管理
- **数据**：负责持久化

### 2. 单点真相（Single Source of Truth）

- 规则统一在 `rules/`
- 文档统一在 `docs/`
- 示例统一在 `data/`

### 3. 可扩展性

- 省份可扩展（添加新省份只需修改 `PROVINCE_RULES`）
- 错误模式可扩展（添加新错误到 `ERRORS.md`）
- 案例可扩展（添加新案例到 `case-studies/`）

### 4. 渐进增强

- 基础对话能力
- 增强：可视化报告
- 高级：自动检查
- 专家：数据驱动决策

## 🔄 数据流

### 场景A：对话生成方案

```
用户输入 → Skill加载 → 收集信息
    ↓
霍兰德评估 → 个性化匹配 → 院校推荐
    ↓
生成方案 → 输出
    ↓
（可选）调用 spec-checker 检查
```

### 场景B：检查现有方案

```
用户方案 → spec-checker加载
    ↓
省份识别 → 加载对应规则
    ↓
规则匹配 → 发现问题
    ↓
分类输出 → 修正建议
```

### 场景C：生成可视化报告

```
考生数据 → 模板渲染
    ↓
HTML生成 → PDF转换
    ↓
Markdown输出
```

## 🔌 扩展点

### 添加新省份

```python
# 在 spec_checker_v2.py 中
PROVINCE_RULES["新省份"] = {
    "mode": "院校专业组",
    "max_volunteers": 45,
    "max_majors_per_group": 6,
    "has_adjustment": True,
    "adjustment_scope": "组内专业",
    "retrieval_rule": "...",
    "collection_count": 2,
    "subject_mode": "3+1+2",
    "official_url": "...",
    "exam_subject_total": 750,
}
```

### 添加新错误模式

```markdown
### E###：<错误名称>

- **症状**：<方案表现>
- **正确**：<应该是>
- **场景**：<何时出现>
- **修复**：<如何修正>
- **首次发现**：<日期>
```

### 添加新Skill

```
skills/
├── my-new-skill/
│   ├── SKILL.md
│   ├── references/
│   ├── templates/
│   └── scripts/
```

## 📊 技术栈

| 层    | 技术                        |
| ----- | --------------------------- |
| Skill | Markdown + YAML frontmatter |
| 脚本  | Python 3.10+                |
| 数据  | JSON / YAML / Markdown      |
| 版本  | Git                         |
| 文档  | Markdown                    |

## 🎓 学习路径

### 新手（1天）

1. 阅读 README.md
2. 了解3个Skill的作用
3. 体验1次完整对话流程

### 进阶（3天）

1. 熟悉 rules/ 目录结构
2. 学习 spec-checker 的工作原理
3. 修改一份现有方案

### 专家（1周）

1. 添加一个新省份规则
2. 添加一种新错误模式
3. 优化一个Skill的逻辑

---

**版本**：v2.0  
**最后更新**：2026-06-11