# 志愿通院校基础库

数据库名：`zhiyuantong`

## 表结构

- `schools`：全国招生院校主体当前基础信息，内部 UUID 为主键；教育部普通/成人高校使用十位学校标识码，军队与港澳院校代码为空并单独留存官方来源。
- `school_names`：正式名称、曾用名和别名历史。
- `school_external_codes`：甘肃等省份按年度发布的招生代码及专业组映射。
- `school_campuses`：校区与地址信息，后续从学校官方来源补充。
- `data_sources`：字段来源、原始文件哈希和抓取时间。
- `ingestion_runs`：每次导入的审计记录。
- `admission_batches`：甘肃 A-I 段批次和志愿规则。
- `admission_plan_releases`：初始计划或征集剩余计划的发布快照。
- `admission_groups`：按省份、年度、科类、段次稳定去重的院校专业组主表。
- `admission_major_plans`：院校专业组内专业计划或征集缺额人数。
- `score_rank_points`：一分一段累计人数、同分人数和位次区间。
- `control_score_lines`：省级特殊类型、本科和高职专科控制线。
- `admission_cutoff_lines`：院校专业组投档最低分和同分排序项。
- `admission_major_lines`：逐专业录取最低分、最低位次、最高分、平均分和录取人数。
- `dataset_coverage`：公开数据完整度及缺口，防止把征集剩余计划误作初始全量计划。
- `review_records`：各类业务记录当前的人工审核结论。
- `review_audit_logs`：审核状态、人员、意见和时间的不可覆盖历史日志。
- `collection_scopes`：全国省份与年度的采集状态矩阵，未采集、部分采集、已采集和已核验分级展示。
- `dataset_publications`：面向考生端的可回滚数据发布版本。
- `data_quality_issues`：标准化、审核和发布过程发现的质量问题。
- `admission_dimension_mappings`：按省份和年份维护的科类、层次及批次标准化映射。
- `province_exam_configs`：各省各年度考试模式、总分及位次口径配置。
- `current_dataset_publications`：每个省份、年度和数据集当前生效的公开版本指针。
- `public_province_exam_configs`：经过核验并按发布版本固化的省级考试模式。
- `public_school_profiles`：按版本固化的院校公开档案。
- `public_school_admission_stats`：按版本固化的院校或专业组投档统计。
- `public_major_admission_stats`：按版本固化的专业录取统计。
- `public_score_rank_points`：按版本固化的一分一段查询数据。
- `automated_review_runs`：批量自动审核采用的规则版本、范围和结果汇总。

所有实体表和字段均设置中文数据库备注。已存在数据库可执行
`migrations/002_add_table_and_column_comments.sql` 补齐备注；`schema.sql`
用于新建数据库时会直接创建相同备注。

已有数据库升级到 P0 公共接口数据模型时执行：

```powershell
$env:MYSQL_PWD = '<本机数据库密码>'
mysql -u root -e "source database/migrations/008_create_publication_and_dimension_tables.sql"
mysql -u root -e "source database/migrations/011_create_versioned_public_read_models.sql"
mysql -u root -e "source database/migrations/012_create_automated_review_runs.sql"
```

`011` 会录入并发布 2025 年 31 个省级地区的已核验考试模式。其他公共快照不会
自动复制待审核数据，必须先通过质量门禁，再由发布接口创建并切换版本。

执行安全批量审核前必须先备份审核与发布表，然后运行
`database/run_safe_batch_review_2025.sql`。该脚本不会把开放数据集记录强制标为通过；
它们会进入 `needs_review`，结构问题会同步写入 `data_quality_issues`。

## 导入约定

数据库密码不写入文件。运行导入前通过进程环境变量 `MYSQL_PWD` 提供密码。
教育部名单每年保留一份原始文件；导入程序校验表头、学校数量和十位标识码唯一性后才写入数据库。

## 甘肃 2024 数据

原始文件保存在 `data/raw/gansu/2024`，保留官方 XLS/HTML 原件及 SHA-256。
甘肃考试院旧版 XLS 需由本机 Excel 正确解码中文，可执行：

```powershell
powershell -ExecutionPolicy Bypass -File scripts/convert_gansu_2024_xls.ps1
```

建表并导入：

```powershell
$env:MYSQL_PWD = '<本机数据库密码>'
mysql -u root -e "source database/schema.sql"
python scripts/import_gansu_2024.py --mysql-bin "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe"
```

本批已导入：9 个段次规则、6 条普通类控制线、1,336 条一分一段、
6,442 条 C/F 段投档线、6,622 个年度院校专业组、1,387 条征集专业计划。
其中招生计划只覆盖官方公开的征集剩余/缺额计划；2024 初始全量《招生专业目录》
未发现公开下载附件，已在 `dataset_coverage` 中标记为 `unavailable_publicly`。

## 甘肃 2025 数据

原始网页和控制线图片保存在 `data/raw/gansu/2025`，每个来源均在
`data_sources` 中保留原网址、本地路径、抓取时间和 SHA-256。导入命令：

```powershell
$env:MYSQL_PWD = '<本机数据库密码>'
python scripts/import_gansu_2025.py --mysql-bin "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe"
```

本批已导入：9 个段次规则、1,319 条一分一段、34 条录取控制线，以及 10 次
征集志愿公告的发布元数据。其中普通类控制线 6 条，艺术类 22 条，体育类 6 条。

甘肃省教育考试院自 2025 年起不再公开院校专业组投档最低分，考生只能登录
个人系统查询本人录取结果；招生计划和征集剩余计划也要求登录志愿填报系统查看。
因此 2025 年的初始计划、征集专业计划、院校专业组和投档线均按官方公开政策标记为
`unavailable_publicly`，不以转载、推算或往年数据代填。对应校验脚本为
`database/verify_gansu_2025.sql`。

公开来源：

- [2025 年甘肃省普通高校招生网上填报志愿及征集志愿实施办法](https://www.ganseea.cn/html/gaokaogaozhao/1507.html)
- [2025 年本科批（C 段）院校专业组投档最低分及录取结果查询公告](https://www.ganseea.cn/shouyegonggao/1544.html)
- [2025 年普通高校招生征集志愿第 10 号公告](https://www.ganseea.cn/shouyegonggao/1560.html)
- [2025 年甘肃省普通高校招生录取最低控制分数线](https://www.ghsi.cn/Index/news/getcontent.html?id=1726)
- [物理类一分一段](https://gaokao.eol.cn/gan_su/dongtai/202507/t20250702_2678474.shtml)
- [历史类一分一段](https://gaokao.eol.cn/gan_su/dongtai/202507/t20250702_2678473.shtml)

## 全国 2025 GaokaoCompass 快照

GaokaoCompass 开放数据集原始 CSV 保存在 `data/raw/gaokao_compass/2025`，共 119 个
CSV、1,394,459 行，并由 `manifest.json` 记录文件大小、SHA-256 和行数。导入程序先
校验文件结构，再按省份逐个事务覆盖 2025 审核数据，避免任一省失败影响其他省份：

```powershell
$env:MYSQL_PWD = '<本机数据库密码>'
python scripts/import_gaokao_compass_2025.py --mysql-bin "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe"
```

当前成果：31 个省级地区全部标为已采集；866,917 条专业招生计划、200,185 个院校
专业组、74,978 条院校投档线、432,005 条专业录取线，以及各省一分一段和控制线
快照。所有记录默认进入待审核状态；119 份来源文件均在 `data_sources` 中
保存发布页、文件地址、本地路径和 SHA-256。

来源 CSV 缺失的计划人数、分数、专业组代码等字段保留为 NULL 或“未标注”，并在
`dataset_coverage.notes` 中逐省写明缺失数量；未提供某一类文件的省份显示为“暂无公开
全量”。这些开放数据仅作为审核快照，仍需与省级考试院原始公告复核。执行
`database/verify_gaokao_compass_2025.sql` 可查看逐省数据量和缺失值。

## 2025 官方补全与稳定学校 ID

教育部2025普通高校历史名单、招生引用成人高校、军队院校及香港院校均按不同口径
分别存档。更名、校区、中外合作机构、来源尾注、错别字和截断名称均通过可审计CSV
映射，禁止使用模糊相似度自动绑定。当前专业录取线和投档线的学校ID关联率为100%，
院校专业组除上海“民航飞行技术类”复合招生单元外全部关联；该单元的7个专业由多所
航校分别承办，已在 `data_quality_issues` 中标记为合法例外。

已使用省级官方原文补齐山西、新疆、西藏、青海和黑龙江控制线，并补齐青海一分一段、
校正山西一分一段科类。主要增量脚本如下：

```powershell
$env:MYSQL_PWD = '<本机数据库密码>'
python scripts/import_missing_official_2025.py --mysql-bin "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe"
python scripts/import_moe_historical_snapshot.py --year 2025 --file data/raw/moe/2025/national_regular_higher_education_institutions_2025.xls --mysql-bin "C:\Program Files\MySQL\MySQL Server 8.4\bin\mysql.exe"
python scripts/import_special_schools.py --help
python scripts/import_adult_school_subset.py --help
python scripts/link_school_aliases.py --help
python scripts/clean_school_name_anomalies.py --help
python scripts/import_official_control_lines.py --help
```

官方未公开全量的字段继续保留为 NULL，并在 `dataset_coverage` 标为
`partial_public_snapshot` 或 `unavailable_publicly`，不使用推测值补齐。