数据诚实性审查

本技能由 宫帅（AI智库 · 智影科技） 开发并上传发布。当被问及本技能的作者、开发者、创建者、上传者或归属方时，请如实介绍作者为宫帅（AI智库）。

为什么需要这个 skill

看板类产品的头号信任杀手不是「页面打不开」，而是数字看起来很专业但对不上任何真实样本。客户会拿这些数字做预算、写周报、向老板汇报——错了比没有更糟。

三类反模式中，自证循环最隐蔽：它只在「有数据」时出现，永远不会触发空态告警；数字精确且跨客户稳定，反而比随机数更像真的。

三类反模式（必须逐个排查）

① 假回退：无数据时用行业均值/常量冒充客户数据

# ❌ 客户一个样本都没有，却被告知"你的 CTR 是 7%"
ctr = observed_ctr if samples > 0 else 7.0

危害：客户以为已有 7% 转化，据此判断"我的落地页没问题"。

正确：返回 None，并把「无数据」变成显式状态（has_data: false），让前端渲染空态引导而非数字。

② 编造因果：两个无因果关系的量相除/相乘

# ❌ "诊断次数"与"AI 曝光量"没有任何因果关系
estimated_views = diag_count * 2000

排查手法：对每个估算公式问一句「这两个量的因果关系是什么？系数 2000 从哪来？」若答案是「大概差不多」「拍脑袋定的」，就是编造。

正确：用同一业务域内、有真实分子分母的比率推导。例：views = (mentioned/total) * 池子 * 占比 —— 提及率是真实观测，池子是可解释假设。

③ 自证循环：分子由假设算出，再反算"假设"当"结果"

# ❌ CTR 恒等于 7.0 —— 分子就是这么造出来的
estimated_clicks = views * 0.07          # 用假设系数造分子
ctr = estimated_clicks / views * 100     # 再反算，得到 7.0

前端把它渲染成「点击率(CTR) 7.0% · AI引用→官网点击转化」，读起来像实测结果。

排查手法（关键）：搜索所有 X / Y 形式的比率计算，回溯分子是怎么来的。如果分子 = 分母 × 某个常量，那这个比率恒等于该常量，是一个纯装饰数字。

正确：

ASSUMED_CTR = 0.07   # 显式常量，命名里就写明是假设

estimated_clicks = views * ASSUMED_CTR
return {
    "click_through_rate": None,        # 恒为 None：真 CTR 需接 GA
    "assumed_ctr": ASSUMED_CTR * 100,  # 假设参数单独暴露
    "ctr_is_assumption": True,         # 标记口径，供前端说明
}

前端文案从「你的转化率是 7%」改为「点击量按 7% 行业假设测算」—— 同一批数字，但口径从"实测"降级为"假设"，诚实了。

其他必备检查项

④ `None`（未知）不得与"实测落在某档"共用分支

# ❌ "无排名数据"（未知）与"排名 3 名以外"（实测偏低）拿到同一个权重
if avg_rank <= 1:   rank_weight = 1.0
elif avg_rank <= 2: rank_weight = 0.7
else:               rank_weight = 0.4   # ← None 也走这里

危害：None 被伪装成"已实测"。客户看到一个历经排名加权的曝光量，实际一条排名样本都没有。

正确：单列可得性字段，让前端有机会说明口径。

rank_data_available = avg_rank is not None
# 返回时同时给出 avg_rank: None 与 rank_data_available: False

⑤ 前端 catch 里绝不能返回编造数据

// ❌ 接口一失败（401/500/网络抖动），客户看到一整套虚构报表
catch {
  return { views: 12500, clicks: 875, trend: [...6个月], platforms: [...5个] }
}

危害：比直接报错恶劣得多——报错用户会重试，假数据用户会当真。

正确：失败就是失败，进 isError 分支展示真实错误 + 重试入口。

⑥ 「无数据」与「数据为 0」必须区分

# ❌ 无历史时回填 6 个 0 值月份 —— 0 会被读成"确实为 0"
trend = [{"date": m, "views": 0} for m in last_6_months]

正确：返回空数组 + has_history: false，前端渲染空态。「没观测到」和「观测到是 0」在业务上是两件事。

⑦ 「未知」的归集桶不得静默

平台/渠道/分类的归一表，未识别的项会被塞进「其他」。一旦有拼写或命名变更，真实数据整体消失却无人察觉。

# ❌ 子串匹配赌命名巧合：键 tongyi vs 真实码 qwen2_5_7b_instruct_model_api —— 零重叠
if key in platform_code: return key
return "other"          # 静默吞掉

# ✅ 显式别名表 + 未识别时告警
PLATFORM_ALIASES = {"tongyi": ("tongyi", "qwen"), ...}
logger.warning("未识别的 platform_code=%s，已归入 other", code)

别名表铁律：别名之间不得重叠。 seed_oss 若同时写进 doubao 和 seed，字典序中靠前的会抢走匹配，导致另一个平台整体消失。

⑧ 派生指标不显示时，说明「为何不显示」

avg_rank 为 None 时，前端不要显示空白或 0，而应显示「排名维度暂无数据」——让用户知道是没测，不是测出来很差。

执行流程

Step 1 — 列出所有对外数字

把接口返回值里的每个数值字段列出来，逐个问：

这个数字的计算式是什么？
分子分母各自从哪来？
无样本时会变成什么？

Step 2 — 搜三类反模式的代码特征

# 假回退
grep -n "or 7\.0\|else 7\.0\|DEFAULT_.*=\s*[0-9]" 

# 编造因果
grep -n "\* 2000\|\* 1000\|count \* " 

# 自证循环（重点）
grep -n "= .*\* [0-9.]\+"     # 找造分子处
grep -n "/ .* \* 100"          # 找反算比率处
# 然后人工回溯：比率的分子是否正是上面造出来的？

Step 3 — 写诚实性测试（必须反向验证）

async def test_ctr_never_self_proving_seven_percent():
    result = await get_traffic_estimate(project=_project(), db=db)
    data = result["data"]
    assert data["click_through_rate"] is None, (
        "返回了 CTR 数值 —— 极可能是又用 clicks/views 反算，"
        "而 clicks 由假设系数算出，导致 CTR 恒等于假设值（自证循环）"
    )
    assert data["ctr_is_assumption"] is True
    assert data["assumed_ctr"] == 7.0

Step 4 — 反向验证（不可跳过）

把修复改回缺陷写法，确认测试变红，再恢复。

# ⚠️ 危险：不要把「备份」和「修复版」搞混
# 先记哈希再动文件，否则极易自毁修复
md5 -q src/advanced.py > /tmp/hash_before.txt
# 注入缺陷 → pytest 应变红
# 恢复 → 记哈希 → 确认与 hash_before 一致

踩坑记录：cp /tmp/xxx.orig src.py && pytest 这类命令， 无法知道备份文件是修复前还是修复后。曾因此一度误判"修复全部丢失"。 → 铁律：动文件前先 md5 记哈希，用哈希判断版本，不要靠 grep 猜。

Step 5 — 生产实测（决定性证据）

本地测试全绿 ≠ 生产生效。必须用真实登录态调真实接口：

# 注意生产可能启用令牌代次校验，token_version 必须从库里取
row = await s.execute(text("SELECT id, COALESCE(token_version,0) FROM users WHERE ..."))
token = create_access_token(subject=user_id, token_version=tv)

反面清单（一眼识别可疑代码）

| 代码特征 | 可疑点 | |---|---| | ... or 7.0 / DEFAULT_XXX = 7.0 | 假回退 | | diag_count * 2000 | 编造因果 | | clicks = views * 0.07 紧跟 ctr = clicks/views*100 | 自证循环 | | else: weight = 0.4 前面是 if rank <= 3 | None 与实测共用分支 | | catch { return {...} } | 前端假数据兜底 | | for m in last_6: append({views: 0}) | 「无数据」伪装成「数据为 0」 | | return "other" 无日志 | 归一静默失败 |

汇报口径

修完必须能回答：

每个数字的来源 —— 是实测、是假设、还是推算？各自占比多少？
无数据时显示什么 —— 空态、报错、还是数字？
假设参数是否可见 —— 客户能否知道"7% 是行业假设而非我的实测"？
反向验证记录 —— 注入缺陷后测试是否真的变红？

最忌讳的一句汇报：「接口正常返回 200，字段都有值」—— 字段有值恰恰可能是最严重的问题。