Files
yanxuan/README.md
T

133 lines
8.1 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.
# 呱咕研选 · 考研择校数据项目
> **新成员入口(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行 |