# 志愿通数据审核台

用于查看和审核全国院校基础库及各省 2024—2025 年公开招录数据。项目由 Spring Boot
后端、Vue 3 前端和 MySQL 数据库组成。

## 已实现的数据分类

- 省年范围：31 个省级地区按 2022—2026 年分别建档；未收集为灰色、部分收集为黄色、已收集为绿色、已核验为蓝色。
- 全国院校：教育部稳定代码、名称、地区、主管部门、层次、性质和外部代码。
- 招生规则：甘肃 A— I 段、招生类别、志愿模式、专业组选报数和征集次数。
- 招生计划：计划发布批次、院校专业组、组内专业计划、批次、科目要求和计划人数。
- 成绩与录取：一分一段、省级控制线、院校专业组投档线、专业录取线和位次。
- 数据治理：来源网址、附件、原始文件路径、SHA-256、公开覆盖范围和数据缺口。
- 人工审核：待审核、通过、需复核、驳回四种状态及完整审核历史。

全国 2025 审核快照来自 GaokaoCompass 开放数据集，已覆盖 31 个省级地区，共导入
866,917 条专业招生计划、193,564 个院校专业组、68,567 条院校投档线、432,005 条
专业录取线和 26,708 条一分一段。来源未提供的分类或字段会以灰色缺口、NULL 或
“未标注”呈现，不以推算值补齐；所有开放数据默认待审核，须与考试院原始公告复核。

## 启动

数据库已经建好并导入数据。后端密码不写入配置文件，请在 PowerShell 中运行：

```powershell
$env:DB_PASSWORD = '<MySQL root 密码>'
cd "D:\Look at the mountain\backend"
mvn spring-boot:run
```

另开一个 PowerShell：

```powershell
cd "D:\Look at the mountain\frontend"
npm install
npm run dev
```

浏览器访问 `http://127.0.0.1:5173`。前端开发服务器会把 `/api` 请求代理至
`http://127.0.0.1:8080`。

## 构建与验证

```powershell
cd backend
mvn test
mvn package

cd ..\frontend
npm run build
```

主要接口：

- `GET /api/dashboard`：统计和覆盖概览。
- `GET /api/metadata`：筛选项元数据。
- `GET /api/collection-scopes`：全国省份与年份采集状态和分类数据量。
- `GET /api/data/{dataset}`：分页、关键词、分类、匹配状态、审核状态和分数范围查询。
- `GET /api/data/{dataset}/{id}`：完整字段、来源和审核历史。
- `PUT /api/reviews/{entityType}/{entityKey}`：提交审核结论。
- `GET /api/v1/meta/admission-contexts`：查询省份、考试模式、科类和数据可用性。
- `GET /api/v1/score-ranks/convert`：按省份、年份和科类进行分数位次互换。
- `GET /api/admin/v1/publications/datasets`：查询支持发布校验的数据集。
- `POST /api/admin/v1/publications/validate`：执行只读的发布前质量门禁。
- `GET /api/admin/v1/publications`：查询历史版本和当前生效版本。
- `POST /api/admin/v1/publications`：通过质量门禁后生成不可变公共快照。
- `POST /api/admin/v1/publications/{id}/publish`：原子切换当前公共版本，也用于回滚。
- `POST /api/admin/v1/publications/{id}/withdraw`：撤回指定版本。

新增 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"
```

`011` 创建带版本号的公共查询快照和当前版本指针，并录入、发布 2025 年全国
31 个省级地区的已核验考试模式。待审核的招录数据不会被迁移脚本自动公开。

分数转位次示例：

```text
GET /api/v1/score-ranks/convert?province=河北省&year=2025&subject=PHYSICS&score=650
```

数据库说明见 [database/README.md](database/README.md)。

P0 考生端的模块边界、数据发布方案、核心表和首批接口见
[docs/p0-backend-blueprint.md](docs/p0-backend-blueprint.md)。

当前已实现接口的参数、响应字段、示例和限制见
[docs/api-reference.md](docs/api-reference.md)。