02 · 一份数据集是怎么来的

   坑 1：状态表存的是【最终态】，不是【当时态】  ⭐⭐

     订单表里 status = '已退款'
     但你要预测的是「下单那一刻会不会退款」
     → 如果你直接 join 订单表当特征，你用了未来   → 泄漏（第14章）

     ✅ 正解：用【变更流水表】而不是【状态快照表】
        没有流水表？那就必须记录每个字段的 valid_from / valid_to

   坑 2：补写与重放

     支付回调失败会重试，日志里同一笔出现 3 次
     对账任务夜里会补写昨天缺的记录 → 昨天的数据今天才全
     → 如果你 T+0 就取数，永远少一截 ⚠️

   坑 3：软删除

     is_deleted = 1 的行还躺在表里
     很多人写 SQL 时忘了加过滤 → 训练集里混着已撤销的业务

   [ ] 表里有没有 update_time？它和 create_time 差多少？
       —— 差得越多，说明这行被改过越多次，越不能当"当时态"用 ⭐
   [ ] 按天统计行数，看最近 3 天是不是明显偏低（= 还在补写）
   [ ] grep 一遍所有 is_deleted / is_valid / status 类的列，
       确认你的 SQL 都过滤了
   [ ] 主键真的唯一吗？（第 6 章）

   ①客户端 SDK          ②网关/采集层           ③数仓 ODS→DWD
   ─────────────        ─────────────         ──────────────
   谁改：客户端开发       谁改：数据工程          谁改：数仓
   改什么：               改什么：                改什么：
   · 上报时机 ⭐⭐         · 采样率 ⭐            · 字段重命名
   · 参数增删            · 去重策略              · 口径重算
   · 事件名合并          · 丢弃规则              · 补数/回溯
   通知你吗：不会         通知你吗：可能          通知你吗：偶尔

   ⭐ 你在第 ③ 层看到的表，是三层改动叠加后的产物。
      表结构没变，不代表①②没变。

   埋点上报量太大 → 数据团队开采样：只上报 10%
   → 你的"曝光次数"特征全部 ÷10（但你不知道）
   → 更糟的是：采样往往【不是随机的】
      常见做法是按 user_id 哈希取模 → 只保留 10% 的【用户】
      → 用户级特征的分布没变，但【全站聚合特征】全错 ⭐

   ⚠️ 而且采样率会随大促临时调整，事后再调回来
      → 你的历史数据里有一段是 10%，一段是 100%

import numpy as np
import pandas as pd

def fingerprint(df: pd.DataFrame, cols, day_col="dt"):
    """给每个 (日期, 字段) 算一组分布指纹。schema 不变但语义变了，会在这里露出来。"""
    out = []
    for day, g in df.groupby(day_col):
        for c in cols:
            s = g[c]
            rec = {"dt": day, "col": c, "n": len(s), "null_rate": s.isna().mean()}
            if pd.api.types.is_numeric_dtype(s):
                q = s.quantile([0.05, 0.5, 0.95]).values
                rec.update({"p05": q[0], "p50": q[1], "p95": q[2],
                            "zero_rate": (s == 0).mean()})
            else:
                vc = s.value_counts(normalize=True)
                rec.update({"n_uniq": s.nunique(),
                            "top1": vc.index[0] if len(vc) else None,
                            "top1_share": vc.iloc[0] if len(vc) else np.nan})
            out.append(rec)
    return pd.DataFrame(out)

def diff_fingerprint(fp: pd.DataFrame, ref_day, cur_day, tol=0.15):
    """比较两天的指纹，列出可疑变化。tol 是相对变化阈值。"""
    a = fp[fp.dt == ref_day].set_index("col")
    b = fp[fp.dt == cur_day].set_index("col")
    alerts = []
    for c in a.index.intersection(b.index):
        # ⭐ 绝对量的变化最能暴露"上报时机变了"——比率类指标会互相抵消，看不出来
        if abs(b.loc[c, "n"] - a.loc[c, "n"]) / max(a.loc[c, "n"], 1) > tol:
            alerts.append((c, "行数突变", a.loc[c, "n"], b.loc[c, "n"]))
        for k in ("null_rate", "p50", "p95", "zero_rate", "top1_share", "n_uniq"):
            if k in a.columns and pd.notna(a.loc[c, k]) and pd.notna(b.loc[c, k]):
                base = abs(a.loc[c, k]) + 1e-9
                if abs(b.loc[c, k] - a.loc[c, k]) / base > tol:
                    alerts.append((c, k, a.loc[c, k], b.loc[c, k]))
        # ⭐ 众数换人 = 枚举漂移或口径重定义，几乎从不是正常波动
        if "top1" in a.columns and a.loc[c, "top1"] != b.loc[c, "top1"]:
            alerts.append((c, "众数变了", a.loc[c, "top1"], b.loc[c, "top1"]))
    return pd.DataFrame(alerts, columns=["col", "signal", "ref", "cur"])

# 用法：fp = fingerprint(df, ["impression", "price", "channel"]); diff_fingerprint(fp, "2026-03-11", "2026-03-12")

   看到一份标注数据，必须问清六件事：

   ① 标注指南是哪一版？现在线上用的是哪一版？  ⭐⭐（第1章那个事故）
   ② 每条标了几遍？一致性（Kappa）是多少？      （第10章）
   ③ 标注员是谁？外包还是业务专家？流失率多少？
   ④ 样本是怎么抽的？随机还是按某种规则挑的？    （第15章）
   ⑤ 有没有"不确定"这个选项？它被怎么处理了？
   ⑥ 标注时标注员能看到什么？会不会看到答案？    ⚠️ 泄漏

   ⭐ 六个问题里，第①和第②决定了这份数据的【天花板】：
      标注员之间都对不齐的东西，模型不可能学对。

   ⚠️ 外部数据里有没有混进你的目标？

   典型：买了一份"企业风险评分"来做信贷模型
        结果这份评分本身就用了【是否已逾期】做输入
        → 你的模型 AUC 从 0.76 跳到 0.91
        → 上线后崩到 0.68（新客户还没逾期，评分是空的）

   ✅ 查法：把外部特征单独拿出来训一个模型，
      如果【单它一个】就能到 0.85+，几乎一定有问题（第14章）

   最常见的三种合成：
   ① 规则生成（faker、模板）      —— 分布完全由你的想象决定
   ② 过采样/SMOTE                —— ⚠️ 在特征空间插值，可能造出物理上不存在的样本
   ③ 生成模型（GAN/扩散/LLM）     —— 边缘分布很像，但【条件依赖结构】常常错

   ⭐ 一个必做的检验：训练一个"真假判别器"
      把真实数据标 1、合成数据标 0，训一个分类器
      · AUC ≈ 0.5  → 合成得很好
      · AUC ≈ 0.99 → 合成数据有明显指纹，模型会学到"这是合成的"这件事本身

   系统：信息流推荐的 CTR 预估模型，日均请求 2.6 亿
   训练数据：曝光日志 × 点击日志 join，曝光为负样本、点击为正样本

   3 月 12 日，产品上线了一个"曝光质量优化"：
     曝光定义： item 进入视口          （旧）
              → item 在视口内停留 ≥1s  （新）
   目的：让报表里的 CTR 更"真实"，对齐竞品口径
   埋点字段名：impression        —— 没改
   埋点参数： 类型、必填性       —— 没改
   通知了谁：产品群、数据看板群   —— 算法团队不在里面 ⚠️

   ⭐ 训练侧的连锁反应：
      曝光（负样本）少了 34%，点击（正样本）几乎没变
      → 正样本比例 4.1% → 6.2%，涨了 51%
      → 模型预估的绝对值整体抬高约 1.5 倍
      → 而下游的【竞价出价】和【冷启动流量阈值】是按绝对预估值配的固定阈值
      → 阈值全部失效：低质内容被判定为"高预估 CTR"，拿到了大量流量

   发现延迟 = 19 天
   ⚠️ 而模型的所有技术指标在这 19 天里都是正常甚至变好的：
      离线 AUC 0.712 → 0.719（因为正负比更平衡，AUC 反而好看）
      线上 CTR 报表 4.1% → 6.3%（分母变小）
      服务成功率、延迟、特征缺失率 —— 全部正常

   19 天 × 2.6 亿请求 ≈ 49 亿次受影响的曝光
   低质内容分发占比从 3.2% 涨到 11.7%
   次日留存 -0.9pp（事后用断点回归估的，见《模型上线之后》13）
   重建训练集 + 回溯 60 天曝光 + 重训 + 灰度：14 人日
   ⭐ 真正的修复只用了 14 人日；19 天全花在"没人知道"上

   | 字段 | 来源层 | 产出方 | 口径定义链接 | 更新频率 | 最近变更 | 我们的用途 |
   |------|--------|--------|-------------|---------|---------|-----------|
   | impression | 埋点 | 客户端-Feed组 | wiki/xxx | 实时 | 2026-03-12 ⚠️ | 负样本 |
   | order_amt  | 业务 | 交易服务    | wiki/yyy | T+1   | 2025-11-03 | 特征 |
   | risk_score | 外购 | XX数据      | 合同附件3 | 月更   | 未知 ⚠️    | 特征 |

   ⭐ 「最近变更」那一列如果写着"未知"，就是一个待办事项。
   ⭐ 这张表本身就是第 3 章数据契约的雏形，也是第 17 章血缘的人工版。