From 4516dc64d8f58c28f37932d659c29656f453c82b Mon Sep 17 00:00:00 2001 From: Hermes Agent Date: Thu, 25 Jun 2026 11:18:48 +0800 Subject: [PATCH] =?UTF-8?q?docs(crowd=5Fdb):=20=E6=95=B0=E6=8D=AE=E8=B4=A8?= =?UTF-8?q?=E9=87=8F=E6=8F=90=E5=8D=87=E8=A7=84=E5=88=92=20-=20=E8=AF=84?= =?UTF-8?q?=E5=AE=A1=E5=90=8E=E4=BC=98=E5=8C=96=E7=89=88?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 评审发现: 1. P0 级风险: 新高考省份选科匹配缺失（7 个 S 级省） 2. P1 优先级调整: 特殊专业标注从 P2 升级为 P1 3. P2 优先级调整: 2026 分数线从 P1 降级为 P2 4. 新增改进项: alts 梯度质量、地域均衡性、专业冷热均衡 5. 遗漏风险: 选科匹配错误、专业停招、alts 梯度失衡 优先级矩阵（产品价值驱动）: - P0: 选科匹配度（推荐准确性） - P1: 特殊专业标注（信息差消除） + 一分一段表（位次匹配） - P2: 2026 分数线 + alts 梯度 + 地域均衡 + 专业冷热均衡 - P3: 港澳台招生 执行顺序优化: 1. Phase 0（P0）: 新高考省份选科匹配度修复 2. Phase 1（P1）: 特殊专业标注 3. Phase 2-4（P2）: 分数线 + alts 梯度 + 均衡性 4. Phase 5（P1）: 一分一段表 5. Phase 6（P3）: 港澳台 验收标准优化: - Phase 0: 7 省 100% recs 有 subject_requirements - Phase 1: ≥30% recs 有 program_type（原 10% 阈值过低） --- ...06-25-crowd-db-quality-enhancement-plan.md | 392 ++++++++++++++++++ 1 file changed, 392 insertions(+) create mode 100644 docs/plans/2026-06-25-crowd-db-quality-enhancement-plan.md diff --git a/docs/plans/2026-06-25-crowd-db-quality-enhancement-plan.md b/docs/plans/2026-06-25-crowd-db-quality-enhancement-plan.md new file mode 100644 index 0000000..f223b91 --- /dev/null +++ b/docs/plans/2026-06-25-crowd-db-quality-enhancement-plan.md @@ -0,0 +1,392 @@ +# CROWD_DB 数据质量与完整度提升规划（评审后优化版） + +> **创建时间**: 2026-06-25 +> **评审时间**: 2026-06-25 +> **当前状态**: 31 省 100% 达 high，但存在 8 类真实差距（含 1 个 P0 级风险） +> **优先级**: P0 > P1 > P2 > P3 +> **产品价值驱动**: 信息差消除 > 数据准确性 > 数据丰富度 + +--- + +## ⚠️ P0 级风险发现 + +### R0：新高考省份选科匹配缺失 + +**问题**: + +- 当前 recommendations 未标注选科要求（物理/历史/选科组合） +- 7 个新高考 S 级省（湖南/江苏/广东/山东/浙江/河北/福建）可能推荐错误 +- **影响**: 物理类考生可能收到历史类专业推荐，推荐无效 + +**示例**: + +``` +湖南物理类考生（选科：物理+化学+生物） +当前推荐：湖南大学汉语言文学（历史类专业） +问题：选科不匹配，推荐无效 +``` + +**优先级**: P0（影响推荐准确性，必须立即修复） + +**执行方案**: + +1. 扩展 recommendation 结构，增加 `subject_requirements` 字段 +2. 标注 7 个新高考 S 级省的选科要求 +3. 其他 24 省后续补齐 + +**数据结构扩展**: + +```json +{ + "name": "湖南大学", + "major": "计算机科学与技术", + "subject_requirements": { + "preferred_subject": "物理", + "reselect_subject": ["化学", "生物"], + "note": "首选物理，再选化学/生物" + }, + "program_type": null, + "frequency": 3, + "platforms": ["千问", "元宝", "百度"], + "predicted_increase": 5, + "alternatives": [...] +} +``` + +--- + +## 当前真实状态 + +### 已完成（Stage 0-4） + +- ✅ 31 省全国口径完成（23 省 + 4 直辖市 + 4 自治区） +- ✅ 31 省 100% 达 high（conf≥0.82, sr≥8, recs≥40, alts≥60, 3层分数带） +- ✅ 7 省达 S 级（湖南基线：10段/60+recs/120+alts） +- ✅ 31 省全部有省级官方入口 trusted_sources + +### 差距矩阵（评审后优化） + +| 优先级 | 差距 | 描述 | 影响省份 | 产品价值 | 预估工作量 | +| ------ | --------------- | ------------------------------------------ | -------------- | ------------------ | ---------- | +| **P0** | 选科匹配度 | 新高考省份选科要求未标注，可能导致推荐错误 | 7 省（新高考） | 推荐准确性 | 3-4h | +| **P1** | 特殊专业标注 | 定向培养/专项计划信息差未消除 | 31 省 | 信息差消除 | 3-4h | +| **P1** | 2026 一分一段表 | 真实位次匹配数据未接入 | 部分省 | 位次匹配准确性 | 需外部数据 | +| **P2** | 2026 分数线 | 分数带边界需更新（变化幅度通常 <10 分） | 7 省 | 分数匹配精确度 | 2-3h | +| **P2** | alts 梯度质量 | alts 数量达标但梯度合理性未验证 | 31 省 | 备选方案有效性 | 2-3h | +| **P2** | 地域均衡性 | 省会院校占比过高，缺少本地化选择 | 31 省 | 本地化推荐 | 2-3h | +| **P2** | 专业冷热均衡 | 热门/冷门专业分布未评估 | 31 省 | 扎堆风险提示准确性 | 1-2h | +| **P3** | 港澳台招生 | 独立招生体系未纳入 | 港澳台 | 覆盖范围扩展 | 2-3h | + +--- + +## 改进阶段规划 + +### Phase 1: 2026 分数线接入（P1，高优先） + +**目标**: 对已公布 2026 分数线的 7 省，更新 score_ranges 分数带 + +**省份清单**: + +- 湖南（物理类本科批 432, 特控线 481 / 历史类本科批 438, 特控线 496） +- 江苏（物理类本科批 448, 特控线 516 / 历史类本科批 474, 特控线 530） +- 广东（物理类本科批 445, 特控线 532 / 历史类本科批 428, 特控线 540） +- 山东（一段线 443, 二段线 150, 特控线 520） +- 浙江（一段线 492, 二段线 269, 特控线 595） +- 河南（理科一本 514, 二本 408 / 文科一本 529, 二本 445） +- 四川（理科一本 520, 二本 433 / 文科一本 529, 二本 457） + +**执行方案**: + +1. 每省根据 2026 分数线调整 score_ranges 分数带边界 +2. 更新 `data_year: 2026` +3. 更新 `last_updated: 2026-06-25` +4. 更新 `source_url` 指向官方公布页面 +5. 更新 `quality_note` 标注"2026 官方分数线已接入" + +**验收标准**: + +- 7 省 `data_year=2026` +- score_ranges 分数带边界与 2026 官方分数线一致 +- pytest crowd_db 全部通过 +- consistency check 通过 + +**预估耗时**: 2-3 小时（串行执行） + +--- + +### Phase 2: alts 池密度提升（P2，中优先） + +**目标**: 每条 recommendation 从 2 alts → 3-5 alts + +**执行方案**: + +1. 分析每省每段现有 recs 结构 +2. 为每条 rec 补充 1-3 条 alts（同省/邻省同档次院校） +3. 优先补充 S 级省份（7 省） +4. 其次补充 A 级省份（24 省） + +**分批策略**: + +- Batch 1: 7 个 S 级省（每省 +70 alts，目标 alts/rec=4.0） +- Batch 2: 24 个 A 级省（每省 +40 alts，目标 alts/rec=3.0） + +**验收标准**: + +- 7 个 S 级省 alts≥280（recs=70, alts/rec=4.0） +- 24 个 A 级省 alts≥120（recs=40, alts/rec=3.0） +- pytest 全部通过 + +**预估耗时**: 4-6 小时（可并行） + +--- + +### Phase 3: 特殊专业标注（P2，中优先） + +**目标**: 为 recommendations.major 增加特殊类型标注 + +**特殊类型清单**: + +- 定向培养（定向医学生、定向师范生、定向农科生） +- 专项计划（国家专项、地方专项、高校专项） +- 中外合作办学 +- 艺体类（音乐、美术、体育） +- 军警类（军校、公安院校） +- 师范类（公费师范生） + +**执行方案**: + +1. 扩展 recommendation 结构，增加 `program_type` 字段 +2. 扫描 31 省现有院校专业，识别特殊类型 +3. 补充标注（优先标注定向培养/专项计划） + +**数据结构扩展**: + +```json +{ + "name": "湖南师范大学", + "major": "汉语言文学", + "program_type": "公费师范生", + "frequency": 3, + "platforms": ["千问", "元宝", "百度"], + "predicted_increase": 5, + "alternatives": [...] +} +``` + +**验收标准**: + +- 至少 10% 的 recs 有 program_type 标注 +- pytest 通过 +- SCHEMA.md 更新结构说明 + +**预估耗时**: 3-4 小时 + +--- + +### Phase 4: 官方数据源接入（P1/P2，需外部依赖） + +**目标**: 接入 official_release 类型数据 + +**数据源清单**: + +1. **省级教育考试院**: 各省录取分数线、一分一段表 +2. **教育部阳光高考**: 招生章程、专业目录 +3. **高校官网**: 录取分数线、招生计划 + +**执行方案**: + +1. 编写爬虫/脚本抓取官方数据 +2. 转换为 crowd_db 格式 +3. 更新 `source_type: official_release` +4. 更新 `trusted_sources` 增加数据来源链接 + +**验收标准**: + +- 至少 1 个省 source_type=official_release +- 包含真实录取位次数据 +- pytest 通过 + +**预估耗时**: 需评估外部数据源可用性 + +--- + +### Phase 5: 港澳台招生体系（P3，低优先） + +**目标**: 扩展 loader 支持 港澳台 招生体系 + +**执行方案**: + +1. 调研港澳台招生体系特点 +2. 设计独立的 JSON 结构 +3. 扩展 loader.py 增加港/澳/台映射 +4. 创建初始数据文件 + +**验收标准**: + +- loader.list_supported_provinces() 返回 34 省（含港澳台） +- 港澳台 JSON 结构与 SCHEMA.md 一致 +- pytest 通过 + +**预估耗时**: 2-3 小时 + +--- + +## 执行顺序（评审后优化） + +### 立即执行（本轮） + +1. **Phase 0（P0）**: 新高考省份选科匹配度修复（7 个 S 级省，3-4h） + - 优先级提升原因：影响推荐准确性，必须立即修复 + - 数据结构扩展 + 7 省选科要求标注 + - 验收：7 省 100% recs 有 subject_requirements 字段 + +2. **Phase 1（P1）**: 特殊专业标注（31 省，可并行，3-4h） + - 优先级提升原因：定向培养/专项计划是"信息差"核心来源 + - 服务农村考生、贫困地区考生 + - 验收：≥30% recs 有 program_type 标注（原规划 10% 阈值过低） + +### 后续执行 + +3. **Phase 2（P2）**: 2026 分数线接入（7 省，串行，2-3h） + - 优先级降低原因：分数变化幅度通常 <10 分，对推荐影响有限 + +4. **Phase 3（P2）**: alts 梯度质量提升（31 省，并行，2-3h） + - 优化：从单纯数量提升改为"数量+梯度质量"双门槛 + - 增加 alts 梯度分布评估（冲刺/稳妥/保底比例） + +5. **Phase 4（P2）**: 地域均衡性 + 专业冷热均衡（31 省，并行，3-5h） + - 新增改进项：评审发现遗漏 + +### 需外部依赖 + +6. **Phase 5（P1）**: 2026 一分一段表接入 + - 需评估各省一分一段表公布情况和可获取性 + +7. **Phase 6（P3）**: 港澳台招生体系 + - 需产品决策 + +--- + +## 风险与约束（评审后补充） + +### 数据质量风险 + +- **R0**: 选科匹配错误导致推荐无效（**P0 级风险**） +- **R1**: 2026 分数线来源可靠性（需核实官方链接） +- **R2**: alts 扩充可能导致院校重复/不合理（需人工审核） +- **R3**: 特殊专业标注准确性（需院校招生章程核实） +- **R5**: 专业停招/撤销未及时更新 +- **R6**: 2026 分数线后续可能有微调（征集志愿等） +- **R7**: alts 梯度失衡导致用户误判 + +### 技术约束 + +- **C1**: loader.py 扩展需向后兼容 +- **C2**: score_ranges 分数带调整需保持连续性 +- **C3**: schema 变更需同步更新测试 +- **C4**: 新增字段（subject_requirements/program_type）需旧数据兼容 + +### 外部依赖 + +- **D1**: 省级教育考试院网站可访问性 +- **D2**: 高校招生章程公开度 +- **D3**: 录取位次数据可获取性 +- **D4**: 一分一段表可获取性（部分省需登录） + +--- + +## 验证框架 + +### 单元测试 + +- `test_crowd_db_data_quality.py`: HIGH_TRUST_PROVINCES 扩展 +- `test_provenance_query.py`: data_year=2026 验证 +- `test_high_trust_thresholds.py`: alts 密度门槛调整 +- **新增**: `test_subject_requirements.py`: 选科匹配度验证 +- **新增**: `test_program_type.py`: 特殊专业标注验证 + +### 集成测试 + +- `scripts/check_crowd_db_consistency.py`: 跨文档一致性 +- `python -m data.crowd_db.quality_summary --human`: 质量分布 +- **新增**: `scripts/check_subject_requirements_coverage.py`: 选科匹配覆盖率 +- **新增**: `scripts/check_alts_gradient.py`: alts 梯度分布评估 + +### 回归测试 + +- `pytest admin/tests tests data`: 全量测试 +- 三仓推送验证 + +--- + +## 成功标准（评审后优化） + +### Phase 0 完成（P0 级） + +- [ ] 7 个新高考 S 级省 100% recs 有 subject_requirements 字段 +- [ ] subject_requirements 字段结构正确（preferred_subject + reselect_subject） +- [ ] 选科匹配测试全部通过 +- [ ] pytest 全部通过 +- [ ] 三仓同步完成 + +### Phase 1 完成（P1 级） + +- [ ] ≥30% recs 有 program_type 标注（原规划 10% 阈值过低） +- [ ] 定向培养/专项计划/中外合作 等类型标注准确 +- [ ] SCHEMA.md 已更新结构说明 +- [ ] pytest 全部通过 + +### Phase 2 完成（P2 级） + +- [ ] 7 省 data_year=2026 +- [ ] 7 省 score_ranges 分数带边界正确 +- [ ] pytest 全部通过 + +### Phase 3 完成（P2 级） + +- [ ] alts 梯度分布合理（冲刺/稳妥/保底比例） +- [ ] alts 重复度检查通过 +- [ ] pytest 全部通过 + +### 整体目标 + +- [ ] **P0 级风险清零**（选科匹配度） +- [ ] **P1 级差距清零**（特殊专业标注 + 一分一段表） +- [ ] P2 级差距 < 50% +- [ ] 31 省数据完整性 ≥80%（定义：选科匹配 + 特殊类型标注 + 2026数据 + 梯度质量） + +--- + +## 产品价值总结 + +### 信息差消除（P0-P1） + +1. **选科匹配度**（P0）：消除新高考省份选科信息差，提升推荐准确性 +2. **特殊专业标注**（P1）：消除定向培养/专项计划信息差，服务农村/贫困地区考生 + +### 数据准确性（P1-P2） + +3. **2026 一分一段表**（P1）：真实位次匹配 +4. **2026 分数线**（P2）：分数带边界精确匹配 + +### 数据丰富度（P2） + +5. **alts 梯度质量**（P2）：备选方案有效性 +6. **地域均衡性**（P2）：本地化推荐 +7. **专业冷热均衡**（P2）：扎堆风险提示准确性 + +### 覆盖范围扩展（P3） + +8. **港澳台招生**（P3）：独立招生体系 + +--- + +## 下一步行动 + +**立即启动 Phase 0（P0 级风险修复）**: + +1. 扩展 recommendation 结构，增加 subject_requirements 字段 +2. 更新 SCHEMA.md 结构说明 +3. 为 7 个新高考 S 级省标注选科要求 +4. 补充测试验证 +5. 提交并三仓推送