# 呱咕研选 · 考研择校数据项目 > **新成员入口(2026-10-30)**:先阅读 [项目接手指南](docs/项目接手指南_20261030.md)。当前可运行产品是 [离线择校 UI](docs/择校UI/index.html),数据库恢复方法见 [数据库备份说明](数据库备份/README.md)。本文件下方保留历史项目说明,部分数字、表名和路径可能过时;尤其 B2 分母存在 1,019 与 1,039 的文档冲突,使用前需复核。 对标「呱呱严选」平台的考研择校数据库 + 数据展示网站。 ## 目录结构 | 目录 | 说明 | |------|------| | `数据库/` | **双库**:`zexiao_2027.db`(主库·生产库,13.7GB)+ `ggyx.db`(采集库,1.7GB)。顶层 py 为历史工具脚本(仅 0.6MB),核心流程只用 `ingest_ggyx_all.py`(镜像)与 `_diff_ggyx_counts.py`(校验);`views.sql` 为视图定义 | | `脚本/` | 当前所有采集/审计脚本(活跃):`ggyx采集/`(各源采集)、`audit_*.py`(审计链)、`run_audit_ci.py`(CI)、`website_export_v2.py`(网站导出)、`CDP调试/` | | `website/` | **数据展示网站**(`index.html` + `data/*.json`,响应式,全量下钻;招生人数按 §1.2a 正确口径) | | `审计报告/` | 正式报告(以 `全表审计_报告.md`、`四维深入审计.md`、`逐项审计_明细.md`、`年份维度缺口矩阵_v2.md` 为准);`历史归档沉淀_20261021/` 存归档回执与瘦身总账 | | `docs/审计口径规范.md` | **审计口径唯一权威定义(v2.1)**,所有对外数字须遵循 | | `docs/agent_handoffs/` | 各阶段 handoff 文档 | | `运行暂存/` | 运行工作区,只放**活跃**内容:`ggyx采集/`(采集状态与原始包)、`ggyx_chrome/`(**登录态,禁删**)、`zexiao_cache/`(研招网采集缓存与断点状态,脚本硬编码引用,勿移)、`yx_cookie.txt`、`logs/`、`inputs/`、`reports/`(R134 运行报告,仍在写入,勿当历史删) | | `_归档/` | **所有历史/临时/待删内容的唯一存放处**(项目内统一归档):`原始来源/`(官网原页证据,保留)、`UI成品图/`、`_待删_20261022/`(staging 21GB+重复候选+解析数据,确认后可整体删)、`历史产物/`(R134 报告与脚本、PDF 复核、测试产物)、`临时_20261022/`(tmp 目录,可删)、`杂项/`(散落抓取件)、`迁移备份_20261020/`、`脚本散件/`、`原始来源_自动登记/` | | `逆向/ggyx接口/` | 呱咕研选接口逆向样例 | > 项目体积约 30GB(含 `_归档/_待删_20261022` 11.8GB 待删)。删掉待删目录后约 19GB。四轮瘦身明细见 `审计报告/历史归档沉淀_20261021/项目瘦身总账.md`。 > **磁盘布局约定**:项目相关的一切只在 `D:\择校` 这一个文件夹内,D 盘根目录不再有 `zexiao_cache`、`ggyx_test_*`、`_待删_*` 等兄弟目录(2026-10-22 已全部并入)。 ## 核心数据口径 - **主库 `zexiao_2027.db`**:生产库,事实模型 + `ggyx_*` 镜像表 - **2027 官方目录 `chsi_2027_dir`**(105,411行/907校/11,706院系/1,404专业):研招网补采的**全量目录**,每行=院校×院系×专业×研究方向,含招生人数(enroll_num)、考试科目(exam_subjects)、学制、备注。**折算到专业级为 37,213 个「校×专业」键** - **历史目录 `dir_hist`**(146,318行/697校/2022–2027):第三方+官网采集的历年专业目录,多源交叉 - **点对点明细 `pd_dir_detail`**(160,282行/543校/2023–2027):17 列,含学费/学制/推免/初试复试科目/研究方向 - **倒推表 `ggyx_dir_hist_reverse`**(49,185行):从平台结果数据倒推的历年(2023-2026)招生情况,**对标呱呱严选"往年对比"** ## 审计口径(强制) **所有对外数字必须遵循 `docs/审计口径规范.md`(v2.1)。** 核心约束: - 院校键保留校区(矿大徐州≠北京、地大北京≠武汉),基线 **617 校**(对标集)/ 1019 校(平台校库) - 粒度分级 G1–G4,跨粒度不得比较行数;统一报表粒度为 **G2(校×专业)** - 分母分层标注:**B1** 官方907 / **B2** 平台校库1019 / **B2a** 平台对标617 / **B3** 平台目录934 - 覆盖率分子必须与分母取交集;分母即自身的不得报覆盖率(`n/a`) - 专业码为字母数字混合,**禁止剥离字母**(`1202Z1` 是自设专业,不是 `12021`) - 派生表(`_derived_at`)不计入覆盖度,单独展示 ```bash # 口径矩阵(14 维度 × 6 年份 + 8 项自检) python -B D:/择校/脚本/audit_spec_v2.py # 逐项明细(逐维度 × 逐年份 × 逐校,含缺口名单与归因) python -B D:/择校/脚本/audit_detail.py # 归档表落差(主表 vs a_* 归档 vs admission_list,量化可回补空间) python -B D:/择校/脚本/audit_archive_gap.py ``` ## 统一事实层(P0+P1 已完成) 主库存在三套并行数据,已建**事实层**整合并物化。**取数优先用 `fact_*`**: | 事实表 | 来源 | 行数 | 说明 | |---|---|---|---| | `fact_person` | `fs_dest_person` + `a_fs_dest_person_h` + `admission_list` | 1,096,071 | 录取/复试名单,按考生号去重;`admission_list` 定为 2026 届 | | `fact_score_dist` | `exam_dist` + `a_exam_dist_h` | 1,800,976 | 分数段,`seg_name` 规范化后合并 | | `fact_score` | `exam_score` + `a_exam_score_h` | 349,408 | 分数线 | 视图版 `v_fact_*` 保留作对照(`DROP VIEW` 可回滚)。重建命令:`python -B 脚本/build_fact_views.py`。 整合效果:录取明细 2024 79.6%→**85.3%**、2025 87.2%→**91.2%**、**2026 从 0 → 661 校 / 100%**;分数段/分数线各年 +0.2~2.9pp。 **完整方案见 `docs/数据整合与口径落地方案.md`**,落差量化见 `审计报告/归档表落差审计.md`。 ## 口径 CI(数据变更后必跑) ```bash python -B 脚本/run_audit_ci.py # 串起 4 个审计,硬性自检失败即退出码 1 python -B 脚本/run_audit_ci.py --fact # 先重建事实层再跑 ``` 硬性项:C1 校区不折叠 / C3 派生表 / C6 覆盖率不越界 / C7 双库镜像 / C10 事实层。 ## 表登记 `dim_table_meta`(185 张) ```bash python -B 脚本/build_table_meta.py # 重建元数据(幂等) ``` 登记每张表的 grain / year_scope / school_col / major_col / is_derived / in_matrix / source / purpose。 ## 待评估资产:`global_facts`(247 万条) 早期建的「事实-证据-评估」三层体系(约 850 万行),含 2021–2027 的 **报考人数 / 录取人数 / 一志愿录取 / 调剂录取 / 录取分数区间**,2025/2026 覆盖 330–350 校。 已展平为 `fact_global`,**尚未接入口径**。详见方案 §9。 ## 数据可信度分级(dir_hist.证据级别) - **一级**:院校官网发布的目录(网页/PDF),权威一手 - **二级**:第三方平台转载或结构化源 - **三级**:待核验 ## 常用命令 ```bash # 镜像采集库 → 主库 python -B D:/择校/数据库/ingest_ggyx_all.py # 重新导出网站数据(全量) python -B D:/择校/脚本/website_export_v2.py # 本地预览网站(全量下钻:院校→院系→专业→研究方向/人数/科目 + 专业反查) cd D:/择校/website && python -m http.server 8080 ``` ## 硬性纪律(见 AGENTS.md) - 注销/写操作/付费接口绝对不碰 - 交付数字必须可回溯到表/行/源文件/口径 - 每项实质任务写 handoff 到 `docs/agent_handoffs/` - 跑 Python 带 `-B`;批量任务先估磁盘写入 ## 采集脚本索引(脚本/ggyx采集/) | 脚本 | 数据源 | 状态 | |------|--------|------| | `fetch_thu_dir.py` | 清华官网 SSR | ✅ 211行 | | `fetch_sysu_dir.py` | 中山官网 PDF | ✅ 196行 | | `fetch_xjtu_dir.py` | 西交官网 PDF | ✅ 129行 | | `fetch_bsu_dir.py` | 北体官网 PDF(eol托管) | ✅ 29行 | | `fetch_shsmu_dir.py` | 上交医学院官网 PDF | ✅ 45行 | | `fetch_sks_dir.py` | 社科赛斯 SSR | ✅ 335行 | | `fetch_zju_dir.py` | 考研派结构化 | ✅ 152行 | | `fetch_kg365_dir.py` / `fetch_kg365_batch.py` | 中公研招结构化 | ✅ 1763行 | | `fetch_kaoyan_dir.py` | 考研帮 www | ✅ 6649行 | | `fetch_233_dir.py` | 233网校 | ✅ 93行 |