数据口径核查员
做数据交付、报表复核或数据字典治理时，最常见的翻车点不是算错，而是口径没对齐：同一个「工业增加值」一个字段写「%」另一个写「亿元」，一个按「同比」一个按「累计」，或者字段只填了单位、期间类型和口径范围空着——声明本身就是残缺的，后面无论怎么对数都容易吵起来。
这个技能只干机械活：把一份数据字典/表头的口径声明读进来，逐字段看四要素齐不齐、取值常不常用，再看同一张表里同名指标有没有口径打架，把问题列成清单。
何时使用
| 用户说法 | 是否触发 |
|---|---|
| 帮我查一下这份数据字典的口径全不全 | 是 |
| 这张表的字段单位/期间类型有没有冲突 | 是 |
| 同名指标是不是有的按同比有的按累计 | 是 |
| 这几个字段的 period_type 是不是混用了 | 是 |
| 表头口径声明体检 / 字段口径一致性检查 | 是 |
| 两个数为什么对不上 / 帮我做口径差异归因 | 否（本技能不做差异归因、不判断哪个口径正确） |
| 帮我下个统计结论 / 这个口径对不对 | 否（本技能只核查声明齐备与一致，不判断正确性、不做结论） |
输入
一份数据字典/表头描述（JSON 文件，UTF-8），根含 table 与 fields：
{
"table": "月度工业数据",
"fields": [
{"name": "工业增加值", "unit": "%", "period_type": "同比", "frequency": "月", "scope": "规上"},
{"name": "工业增加值", "unit": "亿元", "period_type": "同比", "frequency": "月", "scope": "规上"}
]
}
字段说明：
| 字段 | 含义 | 约束 |
|---|---|---|
name |
指标名 | 必填；空 → error |
unit |
单位 | 任意字符串（如 %、亿元、万吨），但同名指标须一致 |
period_type |
期间类型 | 建议 同比/环比/累计/时点，超出仅提示 |
frequency |
频率 | 建议 日/周/月/季/年，超出仅提示 |
scope |
口径范围 | 建议 全口径/规上/重点/其他，超出仅提示 |
四要素（unit/period_type/frequency/scope）每缺一个各计一条 warn。
子命令
check · 逐字段核查 + 跨字段冲突（主功能）
python3 scripts/caliber_checker.py check --input fields.json
python3 scripts/caliber_checker.py check --input fields.json --json
逐条输出 [ERROR]/[WARN] 规则 目标：说明，末行汇总「问题 N 条（error X / warn Y）」。有 error → 退出码 1。
conflicts · 仅列口径冲突项
python3 scripts/caliber_checker.py conflicts --input fields.json
python3 scripts/caliber_checker.py conflicts --input fields.json --json
只列同名指标的 unit 不一致、period_type 混用两类冲突，输出冲突指标名与各取取值。
dimensions · 口径要素清单
python3 scripts/caliber_checker.py dimensions
python3 scripts/caliber_checker.py dimensions --json
列出口径要素清单与建议合法取值（unit 无白名单，仅要求同名一致）。
规则表（11 条：4 error + 7 warn）
| 规则 | 级别 | 范围 | 触发条件 |
|---|---|---|---|
missing_name |
error | 字段 | 字段缺 name（指标名） |
unit_conflict |
error | 同名指标 | 同名指标出现多个不同的 unit 取值 |
period_type_conflict |
error | 同名指标 | 同名指标出现多个不同的 period_type 取值 |
bad_field |
error | 字段 | 字段项不是对象 |
missing_unit |
warn | 字段 | 字段缺 unit（单位） |
missing_period_type |
warn | 字段 | 字段缺 period_type（期间类型） |
missing_frequency |
warn | 字段 | 字段缺 frequency（频率） |
missing_scope |
warn | 字段 | 字段缺 scope（口径范围） |
unusual_period_type |
warn | 字段 | period_type 不在建议取值（同比/环比/累计/时点）内 |
unusual_frequency |
warn | 字段 | frequency 不在建议取值（日/周/月/季/年）内 |
unusual_scope |
warn | 字段 | scope 不在建议取值（全口径/规上/重点/其他）内 |
> 说明：四要素「缺一记 warn」拆成 missing_unit、missing_period_type、missing_frequency、missing_scope 四条独立规则；unit 无建议取值白名单（任意字符串），仅参与同名一致性冲突核查。
输出与退出码
- 退出码
0：check无 error 级问题（可能仍有 warn）/conflicts、dimensions成功； - 退出码
1：check发现 error 级问题（缺 name / 同名指标口径冲突 / 字段项非对象）； - 退出码
2：用法或读取错误（文件不存在、缺子命令、未知子命令、缺--input、JSON 解析失败、输入结构非法）。
--json 输出：check → table/fields_total/issues[]/counts{error,warn}/total/valid；conflicts → table/conflicts[]/total；dimensions → dimensions[]。问题排序：先 error 后 warn。
使用示例
# 1. 核查一份合法数据字典
python3 scripts/caliber_checker.py check --input test-samples/fields_ok.json
# → 未发现问题（error 0 / warn 0），退出码 0
# 2. 核查一份埋了口径冲突的字典
python3 scripts/caliber_checker.py check --input test-samples/fields_conflict.json
# → 问题 2 条（error 1 / warn 1）：同名指标 unit 不一致（% / 亿元）、缺 scope；退出码 1
# 3. 只看冲突项
python3 scripts/caliber_checker.py conflicts --input test-samples/fields_conflict.json
# → 口径冲突 1 项：工业增加值 · 单位（unit）：% / 亿元
# 4. 看口径要素与建议取值
python3 scripts/caliber_checker.py dimensions
# → unit（单位）、period_type（同比/环比/累计/时点）、frequency（日/周/月/季/年）、scope（全口径/规上/重点/其他）
注意事项
- 只查「声明」，不查「数据」：本技能读的是数据字典/表头的口径声明，不接触实际数值，因此不判断哪个口径「正确」、不做统计结论、不做差异归因。两个数为什么对不上，是另一类工具（口径差异解释/对数）的事，不在本技能范围。
- 口径取值需人工确认：
period_type/frequency/scope的建议取值只是「常用值清单」，超出仅作 warn 提示，不代表该口径错误；是否正确须结合业务与官方定义人工确认。 - 单位一致性只做字符串比对：
%与百分比、亿元与万元会被判为不同值（提示冲突），单位换算关系需人工判断。 - 不联网、不写文件：默认只向 stdout 打印，不改输入文件、不访问网络。
边界声明
只做数据字典/表头口径声明的机械核查与提示（要素齐备性、非常用取值、同名指标口径冲突）；不判断哪个口径「正确」、不做统计结论、不做差异归因；与「数据口径差异解释/对数」类工具不同——本件只查口径声明是否齐备与一致，不解释两个数为什么对不上；口径取值需结合业务与官方定义人工确认；不联网、不写文件、不修改输入。
