FDE 交付实战营

第四章数据诊断与 demo

4.1 数据诊断标准动作

承前：第 3 章结束时，SOW 已经签字：第一期做沉睡会员召回，验收标准是复购率相对对照组提升 1.5 个百分点。但在写第一行 Agent 编排代码之前，还有一道绕不开的工序——数据诊断。SOW 里那条"指标可信度受双轨 ID 映射覆盖率影响"的 caveat，就来自这里的诊断结论。这一节讲数据诊断的三个标准动作：分布与缺失、数据字典比对、样本抽查，以及怎么把"体检"做成一份能进 SOW 交付物清单的诊断报告（D2）。

4.1.1 为什么不能直接开写代码

新手 FDE 最常见的冲动是拿到表名就开接：先建连接、拉数据、写 prompt，跑通了再说。三个理由说明这个顺序是错的：

一，指标口径的每个要素都依赖数据实况。 3.4 节的复购率 SQL 里，order_type NOT IN ('RETURN','STAFF_TEST','TRANSFER') 这条剔除规则能不能执行，取决于 POS 同步库里 order_type 字段的取值分布里真的有这三类值、且没有第六种没人知道的类型。口径文档写了、数据里没有，等于没写。

二，Agent 的行为边界由数据质量决定。 沙盘里青禾的"会员标签塞备注"问题：如果 Agent 把备注字段里的 "VIP；宝妈；不要打电话（投诉过）" 当成结构化标签用，它会在深夜给投诉过的会员打电话。这类事故的根因都在"没先看数据"。

三，诊断报告本身就是交付物和免责资产。 SOW 的 D2 交付物是《沙盘数据诊断报告》。它向客户披露"数据现状 vs 项目假设"的差距，每一项差距要么触发修复动作、要么触发范围调整——白纸黑字的披露，是日后扯皮时乙方的护身符。你没诊断，问题就是你没发现；你诊断并披露了，问题就是双方共同决策待修的清单。

4.1.2 标准动作一：分布与缺失剖析

第一件事是给每张核心表做"全身体检"。目标不是逐行检查（不可能），是用统计手段快速建立画像：每个字段的分布长什么样、缺失率多少、有没有明显违反业务常识的模式。

标准剖析脚本（伪代码）通常长这样：

python

# ---- 剖析脚本思路（伪代码）----
def profile_table(table, key_fields):
    report = {}

    # 1. 总量与时间跨度
    report["row_count"] = count(table)
    report["date_range"] = (min(table.date_col), max(table.date_col))

    # 2. 逐字段剖析
    for field in table.fields:
        f = {}
        f["null_rate"]   = null_rate(table, field)      # 缺失率
        f["distinct"]    = n_distinct(table, field)      # 基数
        if is_numeric(field):
            f["min/median/max"] = quantiles(table, field, [0, .5, 1])
            f["p99_outlier_flag"] = p99_vs_max_ratio(table, field)  # 尾部异常
        if is_categorical(field):
            f["top_values"] = value_counts(table, field, top=20)
            f["unexpected"] = [v for v in f["top_values"]
                               if v not in EXPECTED_ENUMS.get(field, set())]
        # 时间字段：格式一致性
        if is_datetime(field):
            f["format_variants"] = detect_date_formats(sample(table, field))
        report[field] = f

    # 3. 主键与关联健康度
    report["pk_duplication"]  = duplication_rate(table, key_fields)
    report["fk_orphan_rate"]  = orphan_rate(table, "member_id",
                                            ref="member_master")
    return report

这段伪代码的每个分支都对应一类病：null_rate 高的字段不能进 Agent 的决策链路；unexpected 枚举值暴露隐性业务状态（比如 order_type 里突然出现 COMP——一问才知道是内部补偿单，口径会议没提过）；format_variants 大于 1 就是时间格式不统一的实锤；fk_orphan_rate 直接量化双轨 ID 的坑有多深。

跑完之后产出一张字段健康度矩阵：

表：pos_sync.order_detail （2.1 亿行，2021-03 至 2025-09）
字段            缺失率    基数      异常信号
──────────────────────────────────────────────────
order_id        0.0%     2.1亿     主键重复 0.03% ← 重复同步问题
member_id       1.2%     83万      外键孤儿 13%  ← 双轨ID未映射
order_type      0.0%     9种      枚举外值 'COMP' 占 0.4% ← 口径缺项
paid_amount     0.9%     -        0元订单占 6.2% ← 券后零单，口径待定
order_ts        0.1%     -        3 种日期格式混用 ← 系统换代期

一眼看出四个雷，这就是剖析脚本的价值：把"数据有点乱"这种模糊感觉，变成带数字的问题清单。

4.1.3 标准动作二：数据字典比对

第二个动作是拿客户给的（或根本没有的）数据字典，跟实际字段做比对。青禾的会员系统有一份 2019 年的数据字典，实际库里的表已经多出 47 个字段、字典里 12 个字段已被废弃。比对的方法很朴素：逐字段核对"字典定义 vs 字段实际内容 vs 一线用户的理解"，三者对不上的地方就是风险点。

最有用的技巧是三角验证：同一字段，问 IT（它技术上存什么）、问运营（他们以为它是什么）、看真实数据（它实际是什么）。三个答案的差值 = 口径混乱度。例如会员系统的 tag 字段：IT 说是"枚举标签"，运营说是"随便填的备注"，实际数据显示 73% 的取值含分号和自由文本——三角验证当场定罪，这就是 4.2 节要展开的"标签当备注"模式。

4.1.4 标准动作三：样本抽查

统计剖析看分布，样本抽查看内容。每个核心表随机抽 50-100 行（外加按异常信号定向抽样），人肉读一遍。这一步没法完全自动化，因为要抓的是机器不好判的"语义级脏数据"：

备注字段里的 "王总介绍"（人名进数据）；
手机号字段里的 1380000****（脱敏和明文混存）;
同一会员在两套系统里性别不一致（M vs 女）。

抽查的产出是bad case 样本集——这批样本有两个去处：进诊断报告做证据展示，进第 7 章的评估集做回归测试用例。一次劳动，两处复用。

4.1.5 诊断报告怎么写

D2 交付物《数据诊断报告》的结构，照"问题 → 证据 → 影响 → 建议 → 决策"五段式写：

问题 #04  会员双轨 ID 未全量映射
证据      外键孤儿率 13%（8.7 万订单无法关联会员主档）
          样本抽查：新旧系统同手机号 611 对，ID 不同
影响      复购率分母低估约 11%；召回名单漏掉约 9% 目标会员
建议      修复：按手机号+姓名+注册时间三级规则建映射表（约 15 人天）
决策      ☑ 客户 IT 接受修复，M1 里程碑前完成 ← 已同步变更单

注意最后两行：建议必须带人天估算，决策必须留痕。 诊断报告不是学术文章，它是一份推动决策的文件。每条问题落一个"修复/绕过/接受风险"的三选一决策，SOW 的范围、成本、里程碑由此获得真实的调整依据。

4.1.7 诊断的规模感：怎么在两亿行上做体检

有人会问：2.1 亿行的表，逐字段跑分布，客户环境扛得住吗？这里补一点工程常识。

诊断脚本的设计原则是采样分层：总量类指标（行数、时间跨度）走全量 count；分布类指标走分层采样——按月分层，每月抽 1%（或者直接用 TABLESAMPLE），分层采样能防"最近三个月数据格式变了而随机采样没抽到"的漏检；主外键健康度（重复率、孤儿率）必须全量算，因为这类问题低频但致命，采样会漏。

时长控制的经验值：核心 5 张表的完整剖析，一个熟练 FDE 加一台能跑 SQL 的客户环境，2-3 个工作日出报告初稿。如果超过一周还没出，通常卡的不是计算，是权限申请和数据出口审批——这也是要提前排进项目时间表的依赖项（客户义务条款里"提供只读账号"对应的就是它）。在金融、政务类客户，一个只读账号走完审批可能就要两周，诊断排期要把它当第一风险项管理。

最后一个提醒：剖析脚本本身要进版本库、随项目交付。半年后第二期扩展门店，第一件事是重跑这套脚本对比两次的健康度矩阵——诊断可复跑，数据治理才有度量衡。很多项目二期返工时诊断脚本找不到了，只能从头再摸一遍，等于第一次诊断白做。

4.1.8 要点总结

代码之前先诊断：口径要素依赖数据实况，Agent 行为边界由数据质量决定，诊断报告是乙方的免责资产。
三个标准动作：分布与缺失剖析（统计画像）→ 数据字典比对（三角验证）→ 样本抽查（语义级脏数据）。
剖析脚本四类探针：缺失率/基数/分布分位数/主外键健康度，把"数据乱"变成带数字的问题清单。
样本抽查产出的 bad case 双重复用：进诊断报告做证据，进评估集做回归用例。
诊断报告五段式（问题/证据/影响/建议/决策），每条问题逼出一个三选一决策并留痕——诊断的目的不是描述世界，是改变决策。

参考资料

The AI Was the Easy Part: What is a Forward Deployed Engineer for Supply Chain? — Samir Saci — 真实 FDE 案例：无文档系统里做字段侦探工作，"可靠的数据表是输出不是输入"。
dbt Semantic Layer — dbt Developer Hub — 指标口径集中管理的官方文档，诊断结论需回流到语义层注册表。
OpenAI launches the OpenAI Deployment Company — OpenAI — 官方交付流程：FDE 的第一步工作是把模型连接到客户数据，连接前必先诊断。
Sensors Data 神策数据 — 全链路用户行为分析 — 国内数据服务商对"数据接入前的口径与埋点治理"的实践，与本章诊断动作互为印证。

第四章 数据诊断与 demo ​

4.1 数据诊断标准动作 ​

4.1.1 为什么不能直接开写代码 ​

4.1.2 标准动作一：分布与缺失剖析 ​

4.1.3 标准动作二：数据字典比对 ​

4.1.4 标准动作三：样本抽查 ​

4.1.5 诊断报告怎么写 ​

4.1.7 诊断的规模感：怎么在两亿行上做体检 ​

4.1.8 要点总结 ​

参考资料 ​