投研数据溯源与审计
投研数据和图表底稿最常见的问题不是"算错"，而是说不清这个数字从哪来：来源没写、取数日期没标、单位不统一、期间靠记忆、取数方法缺失。交付或复盘时，谁也复现不出这个数。这个技能只干机械活：读一份溯源清单，逐条核查 5 个要素齐不齐、数据是否过期，算一个溯源得分，并把待补清单列出来。
何时使用
| 用户说法 | 是否触发 |
|---|---|
| 帮我核查一下这份数据的溯源信息齐不齐 | 是 |
| 这些图表底稿的来源和口径都写了吗 | 是 |
| 哪几个数字缺来源 / 缺单位 / 缺期间 | 是 |
| 这批数据是不是过期了 / 挑出超过 180 天的条目 | 是 |
| 给我一份溯源得分和待补清单 | 是 |
| 帮我出一份审计意见 / 鉴证结论 | 否（本技能不构成审计意见或鉴证结论） |
| 帮我判断这个数字是不是真的 | 否（真伪需回源逐条核对，本技能不做） |
输入
一份溯源清单（JSON 文件，UTF-8），根含 as_of、可选 stale_days 与 records：
{
"as_of": "2026-09-23",
"stale_days": 180,
"records": [
{"metric": "营业收入", "value": 120, "source": "公司年报", "date": "2026-03-31",
"url": "https://example.com", "method": "直接摘录", "unit": "亿元", "period": "2025Q4"}
]
}
字段说明：
| 字段 | 含义 | 约束 |
|---|---|---|
as_of |
核查基准日 | 必填，YYYY-MM-DD；缺或非法 → 退出码 2 |
stale_days |
时效阈值（天） | 可选，缺省 180 |
records |
记录数组 | 必填，每条为一个溯源条目 |
source |
来源 | 5 要素之一 |
date |
取数日期 / 数据截止日 | 5 要素之一，YYYY-MM-DD |
unit |
单位 | 5 要素之一 |
period |
数据所属期间 | 5 要素之一 |
method |
取数方法 | 5 要素之一 |
url |
来源链接 | 可选；缺失仅提醒（warn） |
metric / value |
指标名 / 数值 | 展示用，不计入 5 要素 |
子命令
audit · 逐条核查（主功能）
python3 scripts/provenance_audit.py audit --input provenance.json
python3 scripts/provenance_audit.py audit --input provenance.json --json
逐条核查 5 要素齐备性与时效，输出每条 status（ok/missing/stale/error）、整体溯源得分与待补清单。
stale · 仅列过期条目
python3 scripts/provenance_audit.py stale --input provenance.json
python3 scripts/provenance_audit.py stale --input provenance.json --json
只列出 as_of - date > stale_days 的条目；有过期 → 退出码 1，无 → 0。
checklist · 溯源要素清单
python3 scripts/provenance_audit.py checklist
python3 scripts/provenance_audit.py checklist --json
输出每条记录需要哪些字段、各字段含义，以及核查规则口径。
规则表（机械核查）
| 规则 | 级别 | 触发条件 |
|---|---|---|
missing |
计缺失 | 5 要素（source/date/unit/period/method）任一为空 → 该条 status=missing |
stale |
计过期 | date 可解析且 as_of - date > stale_days（缺省 180）→ status=stale |
error |
计错误 | date 已填但无法按 YYYY-MM-DD 解析 → status=error |
warn_url |
仅提醒 | url 缺失 → warn，不计入得分、不触发退出码 1 |
score |
得分 | 已备要素数 ÷ 应备要素总数（记录数 × 5），百分比；无记录时约定 100% |
exit |
退出码 | 有任一 missing / stale / error → 1；全部 ok → 0 |
状态优先级：error > missing > stale > ok（同一记录命中多项时取前者）。
输出与退出码
- 退出码
0：无缺失、无过期、无日期错误； - 退出码
1：发现任一 missing / stale / error（warn 不触发）； - 退出码
2：用法或读取错误（文件不存在、缺子命令、未知子命令、JSON 解析失败、缺as_of、as_of非法、缺records）。
--json 输出（audit）：as_of/stale_days/total_records/expected_elements/present_elements/missing_elements/score_pct/counts{ok,missing,stale,error}/stale_count/error_count/warn_count/records[]/to_fill[]/ok。
使用示例
# 1. 全齐且新鲜的清单 → 得分 100%、退出码 0
python3 scripts/provenance_audit.py audit --input test-samples/prov_ok.json
# → 记录 3 条；应备要素 15，已备 15，缺失 0 → 溯源得分 100.00%，退出码 0
# 2. 3 条共缺 2 个要素 → 13/15
python3 scripts/provenance_audit.py audit --input test-samples/prov_missing.json
# → 已备 13 / 应备 15 → 溯源得分 86.67%，待补清单 2 条，退出码 1
# 3. 有过期条目
python3 scripts/provenance_audit.py stale --input test-samples/prov_stale.json
# → 过期条目 1 条（2025-06-01，距今 479 天 > 180），退出码 1
注意事项
- 只做机械核查：本技能只统计溯源要素「填没填」与「是否过期」，数字本身对不对、合不合理它一概不管。
- 得分不等于可信度：溯源得分只表示要素填得齐不齐，不代表数据可信度；100% 也可能数据是错的，只是字段填全了。
- 不判断数据真伪：真伪必须回源逐条核对，本工具不做；它也不核对单位与期间之间是否真的匹配，只核查字段是否已标注。
- url 只是提醒：缺 url 只记 warn，不计入得分、不触发退出码 1，因为很多内部底稿本就没有公开链接。
- 不联网、不写文件：默认只向 stdout 打印，不改输入文件、不访问网络。
边界声明
只做投研数据溯源要素（来源 / 日期 / 单位 / 期间 / 取数方法）的齐备性与时效一致性的机械核查；不构成审计意见或鉴证结论，不做任何合规、法律或财务结论；不判断数据真伪（真伪需回源逐条核对）、不做投资建议；溯源得分只表示「要素填得齐不齐」，不代表数据可信度；输入字段内容来自用户自填，可能不完整或有偏差，所有结果仅表示「按清单口径的核查」，需人工核对；不联网、不写文件、不修改输入。
