gaokao-guide/
├── app_api.py              # FastAPI 入口
├── Dockerfile              # Docker 构建（可选）
├── docker-compose.yml      # Docker Compose（可选）
├── requirements.txt        # Python 依赖
├── .env.example            # 配置模板
│
├── src/
│   ├── api/                # 接口层
│   │   ├── chat.py         #   SSE 流式对话
│   │   ├── tools.py        #   志愿评估 / 配置 CRUD
│   │   ├── conversations.py#   会话管理
│   │   ├── search.py       #   对话搜索
│   │   └── dependencies.py #   依赖注入（启动时初始化服务）
│   │
│   ├── agent/              # Agent 层
│   │   ├── volunteer.py    #   志愿评估处理
│   │   ├── opinion.py      #   观点检索
│   │   ├── style_chat.py   #   风格聊天
│   │   ├── fallback.py     #   通用兜底
│   │   └── router.py       #   意图路由
│   │
│   ├── retrieval/          # 检索层
│   │   ├── hybrid_search.py#   混合搜索（向量+FTS5+注入+联网）
│   │   ├── vector_search.py#   向量检索
│   │   ├── keyword_search.py#   SQLite FTS5 检索
│   │   ├── web_search.py   #   联网搜索（DuckDuckGo）
│   │   ├── structured_query.py# 结构化 SQL 查询
│   │   ├── embedding_service.py# Embedding 服务
│   │   └── reranker.py     #   重排序
│   │
│   ├── knowledge/          # 知识存储层
│   │   ├── chroma_store.py #   ChromaDB（向量 + 倒排）
│   │   ├── sqlite_store.py #   SQLite FTS5
│   │   └── session_store.py#   会话持久化
│   │
│   ├── safety/             # 安全层
│   │   └── input_gateway.py#   输入安全检测
│   │
│   └── utils/              # 工具
│       ├── prompt_templates.py# Prompt 模板
│       ├── conversation.py    # 对话管理
│       └── logger.py          # 日志
│
├── static/                 # 前端
│   ├── index.html          #   SPA 页面
│   ├── css/style.css       #   样式
│   └── js/                 #   前端逻辑
│       ├── app.js          #     编排 & 志愿评估渲染
│       ├── chat.js         #     对话流
│       ├── sidebar.js      #     会话列表
│       ├── api.js          #     API 封装
│       ├── settings.js     #     设置面板
│       └── utils.js        #     工具函数
│
├── scripts/                # 数据采集 & 工具脚本
│   ├── scrape_2026_admission.py  # 爬招生政策
│   ├── extract_all.py            # 数据抽取
│   ├── index_mvp.py              # 索引构建
│   ├── _clean_garbled.py         # 乱码清理
│   └── _reindex_2025.py          # 2025数据重索引
│
└── data/                   # 本地数据（gitignore）
    ├── chroma_db/          #   ChromaDB pickle
    ├── gaokao.db           #   SQLite 数据库
    ├── extracted/          #   提取文本
    ├── raw/                #   原始文件
    └── processed/          #   处理后文件

1. 分数定位 → 分数不重要，位次才重要。从一分一段表精确查找，禁止估算
2. 专业筛选 → 兴趣排第二，就业排第一。看专业壁垒高低、行业基本面
3. 地域匹配 → 选城市比选学校名字重要。产业集群在哪，实习机会在哪
4. 院校定档 → 专业实力 > 综合排名。行业认可度 > 985/211 名头
5. 风险对冲 → 给自己留后路。转专业难易度、考研/考公兼容性、行业周期

用户输入
  │
  ├── ① 安全检测 ─────────────→ 不通过 → 返回安全提醒，拒绝回答
  │                             通过 ↓
  ├── ② 意图路由 ─────────────→ volunteer / opinion / style_chat / general
  │     基于关键词预检 + LLM 二次确认，不同意图走不同 prompt 模板
  │
  ├── ③ 多路混合搜索 ─────────→ RRF 融合 + 联网兜底
  │     ├─ 向量检索（charbigram hash，语义兜底）
  │     ├─ FTS5 全文检索（SQLite 关键词匹配）
  │     ├─ 省份注入（扫描 ChromaDB 中 score_data 文档，匹配用户省份）
  │     └─ 联网搜索（优先14个官方数据源，本地不足时按需触发）
  │          │
  │     ┌────┴────┐
  │     │ RRF 融合 │ ← 三路结果加权合并，联网结果追加在末尾
  │     └────┬────┘
  │
  ├── ④ 位次精确提取 ─────────→ 从搜索结果中匹配一分一段表
  │     ├─ 找到精确位次 → 写入 prompt：用户N分 → 位次XXX名（禁止估算）
  │     └─ 未找到 → 标记「缺少精确一分一段表」
  │
  ├── ⑤ LLM 生成 ─────────────→ 主模型 → 失败时自动切换备用模型
  │     ├─ 智能问答：流式 SSE 返回，300-800 字/轮
  │     └─ 志愿评估：生成结构化 JSON（院校列表 + 位次 + 分析 + 风险）
  │
  ├── ⑥ 后端位次覆写 ─────────→ 无论 LLM 输出什么 rank 值，
  │                              后端用步骤④提取的精确值强制覆盖
  │
  ├── ⑦ 会话持久化 ───────────→ SQLite 存储
  │     ├─ 普通对话：role + content
  │     └─ 志愿评估：content_type=volunteer_assessment + structured_data
  │
  └── ⑧ 前端渲染 ─────────────→ 按 content_type 分发
        ├─ 普通文本 → Markdown 渲染
        └─ volunteer_assessment → 结构化卡片（位次定位 + 冲稳保 + 概率条 + 专业分析 + 风险提示）