CROWD_DB_DATA_QUALITY

最后更新: 2026-06-14 适用范围: data/crowd_db/*.json + skills/gaokao-spec-checker/scripts/... 反扎堆模块

1. 设计目标

data/crowd_db 当前有 27 省的结构化 JSON 文件。本设计目标:

区分“结构覆盖”与“高置信推荐数据覆盖”。
在不出现误导的前提下,允许其它省份逐步补齐。
报告、portal、咨询输出都必须显式声明该省的 data completeness level。

2. 字段约定

data/crowd_db/<province>.json 推荐数据:

{
  "province": "湖南",
  "data_completeness": "high",
  "confidence": 0.85,
  "score_buckets": [
    {"score": 500, "rank_estimate": 20000, "schools": [{"name": "...", "majors": [...]}]}
  ],
  "source": {"type": "official", "url": "...", "year": 2025},
  "last_updated": "2026-06-01"
}

字段说明:

data_completeness (required): 4 档之一
- high : 高置信, 推荐输出可作为强结论
- medium: 中置信, 推荐输出可作为参考结论
- low : 低置信, 推荐输出只能作为弱提示
- skeleton: 仅骨架, 不允许对外推荐结论
confidence (required, 0.0-1.0): 与 data_completeness 一致
source.type (required): 4 档之一
- official : 考试院 / 阳光高考
- report : 第三方权威报告
- estimate : 内部估算
- placeholder: 暂存占位, 不允许用于结论
source.year (required): 数据年份
last_updated (required, ISO8601)

3. 高置信数据完整性矩阵

省份	data_completeness	confidence	当前状态	推荐输出
湖南	high	≥ 0.8	实际数据, 多分数段	强结论
北京	medium	0.5-0.8	骨架, 部分数据	弱提示
上海	medium	0.5-0.8	骨架, 部分数据	弱提示
广东	medium	0.5-0.8	骨架, 部分数据	弱提示
浙江	medium	0.5-0.8	骨架, 部分数据	弱提示
其它 22 省	skeleton	< 0.5	仅省份规则	不允许推荐结论

4. 报告输出文案规则

skills/gaokao-spec-checker / 反扎堆报告 / gaokao_visual_report 输出:

data_completeness == high : 直接给出推荐结论
data_completeness == medium : 在结论前必须加 [置信度: 中] 标签
data_completeness == low : 只给弱提示, 禁止结论
data_completeness == skeleton: 报告必须写明“暂无该省的高质量推荐数据”

5. 强制不变量

data_completeness 与 confidence 必须一致
- high ⇒ confidence >= 0.80
- medium ⇒ confidence >= 0.50
- low ⇒ confidence < 0.50
- skeleton ⇒ confidence < 0.20
source.type 与 data_completeness 必须一致
- official ⇒ data_completeness in {high, medium}
- placeholder ⇒ data_completeness == skeleton
last_updated 必须在 source.year 之后 (或同一年)
高置信省 (high) 的 score_buckets 必须至少覆盖 5 个分数段

6. 实现侧

data/orders/loader.py 与 data/crowd_db/crowd_detector.py 加载时:

校验 data_completeness 与 confidence 一致
校验 source.type 与 data_completeness 一致
把 data_completeness 暴露给报告渲染器

7. 测试锁死

tests/test_crowd_db_data_quality.py 必须锁死:

data/crowd_db/湖南.json 的 data_completeness == high, 至少 5 个 score_buckets
其它 26 省的 data_completeness in {medium, skeleton}
任何省的 data_completeness 与 confidence 数值必须满足第 5 节不变量
报告渲染器在 data_completeness == skeleton 时必须输出 “暂无该省的高质量推荐数据”

8. 后续工作

持续补充中等置信省份的数据
把 gaokao_visual_report 改造成在结论前自动插入置信度标签
在反扎堆报告中显式标出该省份的 data_completeness

4.0 KiB Raw Blame History