02 · 第二关：业务侦探社 · 逆向工程与语义层扎根

“不要问客户‘你们的需求是什么’，要问‘上个月这张对账单，你是怎么从系统导出来并手动修成合规报表的？’”
—— 一位百雀羚前线交付工程师的备忘录

001

⚔️ 本关作战任务（Context & Quest）

工作现场：百雀羚数字化运营与财务对账工作区
分析难点：“具有欺骗性的物理表结构”、“深藏在老员工脑中的隐性公式”、“手工 Excel 里的暗箱 VLOOKUP”
Text-First 阶段映射：
- Stage 2: Specifying & Decision（意图固化与规格书写）
- 核心工程准则：Rule 1: No Code Without Spec（无规格不写代码）
- 核心原则：Principle 2 (Spec as Source of Intent) 与 Principle 3 (Decision with Provenance)
通关目标：
1. 掌握“业务需求逆向工程（Reverse Requirements Engineering）”四步法；
2. 彻底厘清“物理存储模型 $\neq$ 业务领域模型”的深层工程本质；
3. 构建机器可读、人机共识的受控业务语义层（Semantic Layer），并将口径绘制为显性 DAG（有向无环图）；
4. 产出标准的 specs/SPEC-METRIC-GMV.md 规格工件与 ADR 架构决策；
5. 运行并通过 labs/lab02-semantic-reverse/ 实操实验。

💣 现场惨案还原（The Murder Scene）

真实案情回顾（参见：

项目进入第二周，团队拿到了客户 DBA 导出的 MySQL 数据库 DDL 和只读账号。新手工程师小张打开数据库工具，看到一张名为 dw_order_info 的表，欣喜若狂： “太标准了！表名是订单，里面有 order_id、channel_code、pay_amount。用户问‘上月天猫旗舰店 GMV 是多少’，写个 Prompt 让大模型生成 SQL： SELECT SUM(pay_amount) FROM dw_order_info WHERE channel_code = 'TMALL'; 这不就结了吗？AI 果然提效千倍！”

002

然而，在随后的业务核对中，这行看似合理的 SQL 暴露出了严重的业务口径偏差：财务负责人指出：“天猫上月官方结算净额为 1.10 亿，而系统统计出的数值为 1.28 亿，存在 1800 万的口径差额。”

团队深入数据库底层进行了系统梳理，才梳理出背后的口径成因：

状态枚举历史差异：dw_order_info 是一张沉淀多年的宽表，order_status 枚举中包含已取消与风控拦截记录，这些记录仍保留着原始金额；
退款扣减逻辑：业务口径的“净销售额”需要动态扣除 refund_amount，各渠道的退款沉淀形式各异；
代销结算折率：线下商超代销渠道在订单表记录的是标价，但合同遵循固定折率买断，运营人员每周在 Excel 里进行折率折算；
内部测试订单：早期留存的部分测试订单未被物理清理。

经验教训：物理数据库里的字段只是系统为了持久化妥协的存储产物；真正的业务意图深藏在日常核算规则与业务流程中。未做逆向工程与规格书写（Spec）就直接编码，极易带来大量返工。

🧠 核心心法与底层原理（The Mental Model）

1. 软件工程的本源：物理存储模型 $\neq$ 业务领域模型

在《数据密集型应用系统设计（DDIA）》中，Martin Kleppmann 指出：数据系统的物理演进往往落后于业务概念的演进。

物理存储模型（Physical Storage Model）：为磁盘 I/O、索引效率、事务隔离性而设计，通常包含历史兼容字段与冗余列；
业务领域模型（Domain Model）：业务人员沟通、决策、结算的真实意图，必须清晰、显式且达成共识。

FDE 的核心工作之一，就是在物理数据库与应用之间梳理出清晰的受控语义层（Semantic Layer）。

2. 业务逆向工程四步法（Reverse Engineering）

现场交付往往缺乏完备的数据字典，成熟的 FDE 团队通常采用逆向追溯法：

Step 1：锁定基准（Ground Truth）

避免空对空讨论指标定义；
获取客户已核准的最终对账单（如《2026年7月电商分渠道结算总盘.xlsx》），作为对齐的唯一基准。

Step 2：还原操作（Trace Operation）

了解业务人员日常的数据提取步骤；
观察业务人员在表格处理时手动排除了哪些特殊记录。

Step 3：提炼规则（Extract Rules）

分析计算公式中的加权扣减与映射转换关系；
提炼出物理库缺失的维度规则与业务状态。

Step 4：沉淀契约（Spec & DAG）

将提炼出的规则整理为标准规格书（Spec），并用 Mermaid 绘制出清晰无歧义的指标计算流程 DAG。

3. Text-First 规范落地：Spec as Source of Intent

根据 Text-First 原则 2（ai时代新思想/Text-First Agentic Engineering.md）：“Specification 是意图的权威来源，严禁在无 Spec 状态下直接催动 Agent 编码。”

在前线，FDE 梳理完口径后，必须在 Git 仓库落盘标准的 Spec 工件：

markdown

# specs/SPEC-METRIC-NET-REVENUE.md

## 1. 业务意图 (Intent)
- **指标名称**：各渠道月度净销售额（Net Revenue）
- **业务责任人**：财务运营部 张总监 (2026-08 签字确认)

## 2. 物理映射规则 (Physical Mapping)
- 数据源表：`orders`
- 强制准入过滤器 (Filters):
  - `is_internal_test = 0` (剔除内部测试)
  - `order_status = 1` (仅保留已支付完成单，剔除取消/超时)

## 3. 分渠道计算公式 DAG
- **天猫自营 (TMALL)**: `SUM((amount - refund_amount) * (1 - 0.05))`
- **京东自营 (JD)**: `SUM((amount - refund_amount) * (1 - 0.03))`
- **抖音自营 (DOUYIN)**: `SUM((amount - refund_amount) * (1 - 0.08))`
- **线下代销 (DAIXIAO)**: `SUM((amount - refund_amount) * 0.85)` (合同 85 折买断)

## 4. 黄金测试断言 (Golden Assertions)
- 输入：`fixtures/raw_orders.csv`
- 预期产出：`TMALL: 2726.50`, `JD: 5044.00`, `DOUYIN: 1978.00`, `DAIXIAO: 21250.00`

🛠️ 动手实验室（Hands-on Lab 02：编制对账单逆向追溯提示词工件）

在本实验中，你将接管现场真实的欺骗性 DDL 与带有暗坑的原始订单数据，编制一份包含清洗规则与指标计算 DAG 的提示词规格工件，指挥 AI 生成无误差的对账引擎。

实验信息

沙箱路径：labs/lab02-semantic-reverse/
任务目标：分析 context/order_ddl.sql、context/raw_orders.csv 与财务核准月报 context/manual_report.csv，在 starter/prompt.md 中编写结构化提示词工件（交代内部测试单剔除、代销 85 折买断与自营佣金退款规则），指挥 AI 生成 reconciler.py，并由 AI 依据本关 rubric.md 统一评分。

核心提示词与验收断言要点

在 labs/lab02-semantic-reverse/starter/prompt.md 中完整定义：

准入过滤规则：is_internal_test == 1 或 order_status != 1 必须剔除；
多渠道计算 DAG：自营扣佣金扣退款、代销按合同 85 折买断计算；
输出契约：导出 calculate_channel_metrics(csv_path) 函数，各渠道有效订单数、GMV 与净收入与财务核准月报绝对偏差 < 0.01 元。

触发 AI 评分

补全 starter/prompt.md 后，对 AI 说：

“用 fde-lab-scoring 技能，给 lab02-semantic-reverse 评分并写改进建议。”

AI 依据本关 rubric.md（含四处暗坑清单与黄金对账数值）逐维打分并给出改进建议：

text

# 📊 实验评分单 · lab02-semantic-reverse
致命漏项裁决：✅ 未命中（代销 85 折、测试单/无效单过滤均已交代）
黄金对账核对：TMALL 2726.50 / JD 5044.00 / DOUYIN 1978.00 / DAIXIAO 21250.00（净收入，误差 < 0.01 元）
五维合计：90 / 100 → 🎉 PASS

统一评分技能见 labs/_scoring/。

🥊 避坑指南与常见死法（Antipatterns & Pitfalls）

反模式一：轻信数据库字段命名与静态注释

现象：字段注释写着 is_deleted: 是否删除 (0否 1是)。
排查：历史迭代中逻辑调整，实际上使用了 order_status = 9 表示取消，注释未同步更新。
应对：使用 SQL 分组统计当前实际数据的枚举分布：SELECT order_status, is_deleted, count(*) FROM orders GROUP BY 1, 2;。

反模式二：试图强行统一存在客观差异的跨部门口径

现象：电商部门与财务部门对退款确认的时间点定义不同，开发试图强行折中。
应对：“口径隔离，显式命名”。在 Spec 中建立两个独立指标：财务口径_实收净额 vs 电商运营口径_盯盘GMV，由业务方在界面按需选择。

反模式三：仅凭口头对账，缺乏基准样例存盘

现象：口头沟通时认为“大体一致”，但未落盘测试样本。
应对：必须沉淀脱敏基准数据集，并将计算对账结果作为验收材料书面归档。

🏆 通关验收卡与装备获取（Checkpoint & Loot）

📋 本关通关自检清单

[x] 掌握了业务逆向工程四步法（基准、操作、规则、契约）；
[x] 理解了存储模型与领域模型的差异，掌握受控语义层设计；
[x] 遵循了 Text-First 核心准则：No Code Without Spec；
[x] 通过了 AI 依据 labs/lab02-semantic-reverse/rubric.md 的统一评分（🎉 PASS）。

🎁 本关掉落装备

装备名称：【口径破雾分析仪】
装备属性：业务规则洞察率 +100%，对账精度达到 0.01 元
装备描述：能够有效穿透物理数据库的表层字段，清晰还原出真实的业务核算与计算流程。

梳理清楚了业务口径，沉淀了可靠的指标规格！下一关我们将进入工程实现期，面对本地与线上环境的治理——《第三关：工程炼金术 · 开发环境治理与模型适配》！

Step 3：破译暗坑（Crack Formula）

按下快捷键 Ctrl + ~ 显示 Excel 所有公式；
凡是业务使用了 =VLOOKUP(...)、=SUMIFS(...) 或者乘以 0.85 的地方，全部高亮圈出。这正是系统物理库缺失的关键外键与业务规则！

Step 4：沉淀契约（Spec & DAG）

将逆向得出的公式翻译为标准规格书（Spec），并用 Mermaid 绘制出清晰无歧义的指标计算流程 DAG。

3. Text-First 规范落地：Spec as Source of Intent

根据 Text-First 原则 2（ai时代新思想/Text-First Agentic Engineering.md）：“Specification 是意图的权威来源，严禁在无 Spec 状态下直接催动 Agent 编码。”

在前线，FDE 梳理完口径后，必须在 Git 仓库落盘标准的 Spec 工件：

markdown

# specs/SPEC-METRIC-NET-REVENUE.md

## 1. 业务意图 (Intent)
- **指标名称**：各渠道月度净销售额（Net Revenue）
- **业务责任人**：财务运营部 张总监 (2026-08 签字确认)

## 2. 物理映射规则 (Physical Mapping)
- 数据源表：`orders`
- 强制准入过滤器 (Filters):
  - `is_internal_test = 0` (剔除内部测试)
  - `order_status = 1` (仅保留已支付完成单，剔除取消/超时)

## 3. 分渠道计算公式 DAG
- **天猫自营 (TMALL)**: `SUM((amount - refund_amount) * (1 - 0.05))`
- **京东自营 (JD)**: `SUM((amount - refund_amount) * (1 - 0.03))`
- **抖音自营 (DOUYIN)**: `SUM((amount - refund_amount) * (1 - 0.08))`
- **线下代销 (DAIXIAO)**: `SUM((amount - refund_amount) * 0.85)` (合同 85 折买断)

## 4. 黄金测试断言 (Golden Assertions)
- 输入：`fixtures/raw_orders.csv`
- 预期产出：`TMALL: 2726.50`, `JD: 5044.00`, `DOUYIN: 1978.00`, `DAIXIAO: 21250.00`

🛠️ 动手实验室（Hands-on Lab 02：对账单逆向追溯实战）

“纸上得来终觉浅，绝知此事要躬行。”
在本实验中，你将接管一份暗藏 4 处业务暗坑的真实订单数据，运用本章心法完成全自动对账。

实验信息

沙箱路径：labs/lab02-semantic-reverse/
前置依赖：Python 3.10+
测试通过基准：四个渠道的订单量、GMV 与净销售额与业务人工核准月报分文不差。

核心演练代码剖析

打开 labs/lab02-semantic-reverse/starter/reconciler.py：

python

# 必须贯彻的业务清洗与加权结算逻辑：
if is_test == 1 or status != 1:
    continue  # 剔除测试单与非成功订单

if channel == "DAIXIAO":
    # 线下代销暗坑：合同 85 折买断
    results[channel]["gmv"] += amount * 0.85
    results[channel]["net_revenue"] += (amount - refund) * 0.85
else:
    # 线上自营渠道：扣除退款并扣减平台技术服务费
    results[channel]["gmv"] += amount
    results[channel]["net_revenue"] += (amount - refund) * (1.0 - fee_rate)

触发 AI 评分

补全 starter/prompt.md 后，对 AI 说：

“用 fde-lab-scoring 技能，给 lab02-semantic-reverse 评分并写改进建议。”

AI 依据本关 rubric.md 的黄金对账数值校验你提示词的完备度：

text

# 📊 实验评分单 · lab02-semantic-reverse
黄金对账核对：TMALL 2726.50 / JD 5044.00 / DOUYIN 1978.00 / DAIXIAO 21250.00（净收入，误差 < 0.01 元）
最终结论：🎉 PASS（无一分钱误差）

统一评分技能见 labs/_scoring/。

🥊 避坑指南与常见死法（Antipatterns & Pitfalls）

死法一：相信数据库字段名和表注释

现象：注释写着 is_deleted: 是否删除 (0否 1是)。
真相：开发在三年前换了逻辑，物理删除了部分数据，同时又用 order_status = 9 表示软删除，导致 is_deleted 字段已经荒废三年。
解法：永远用 SQL 分组统计当前实际数据的枚举分布：SELECT order_status, is_deleted, count(*) FROM orders GROUP BY 1, 2;。

死法二：试图强行统一跨部门口径

现象：电商部认为退货在寄回时就算退款；财务部认为只有货仓签收并开具冲红发票才算退款。工程师试图在系统里写一套“大家都能妥协”的折中逻辑。
下场：两边部门都不认账，系统变成两头挨骂的四不像。
解法：“口径隔离，显式命名”。在 Spec 中建立两个独立指标：财务口径_实收净额 vs 电商运营口径_盯盘GMV，由用户在前端自由切换。

死法三：口头对账，不留黄金基准

现象：微信上问业务对账对了没，业务回了个“大体差不多就行”。
下场：上线当天暴雷，业务反口：“我说的差不多是指几百块，你们差了几万块也叫差不多？！”
解法：必须保存脱敏测试基准集，并将计算对账结果作为验收附件打印签字。

🏆 通关验收卡与装备获取（Checkpoint & Loot）

📋 本关通关自检清单

[x] 掌握了业务逆向工程四步法（终局、操作、暗坑、契约）；
[x] 理解了存储模型与领域模型的鸿沟，掌握受控语义层设计；
[x] 遵循了 Text-First 核心工程准则：No Code Without Spec；
[x] 通过了 AI 依据 labs/lab02-semantic-reverse/rubric.md 的统一评分（🎉 PASS）。

🎁 本关掉落装备

装备名称：【口径破雾分析仪】
装备属性：业务规则洞察率 +100%，对账精度达到 0.01 元
装备描述：能够有效穿透物理数据库的表层字段，清晰还原出真实的业务核算与计算流程。

02 · 第二关：业务侦探社 · 逆向工程与语义层扎根 ​

⚔️ 本关作战任务（Context & Quest） ​

💣 现场惨案还原（The Murder Scene） ​

真实案情回顾（参见： ​

🧠 核心心法与底层原理（The Mental Model） ​

1. 软件工程的本源：物理存储模型 ≠ 业务领域模型 ​

2. 业务逆向工程四步法（Reverse Engineering） ​

Step 1：锁定基准（Ground Truth） ​

Step 2：还原操作（Trace Operation） ​

Step 3：提炼规则（Extract Rules） ​

Step 4：沉淀契约（Spec & DAG） ​

3. Text-First 规范落地：Spec as Source of Intent ​

🛠️ 动手实验室（Hands-on Lab 02：编制对账单逆向追溯提示词工件） ​

实验信息 ​

核心提示词与验收断言要点 ​

触发 AI 评分 ​

🥊 避坑指南与常见死法（Antipatterns & Pitfalls） ​

反模式一：轻信数据库字段命名与静态注释 ​

反模式二：试图强行统一存在客观差异的跨部门口径 ​

反模式三：仅凭口头对账，缺乏基准样例存盘 ​

🏆 通关验收卡与装备获取（Checkpoint & Loot） ​

📋 本关通关自检清单 ​

🎁 本关掉落装备 ​

Step 3：破译暗坑（Crack Formula） ​

Step 4：沉淀契约（Spec & DAG） ​

3. Text-First 规范落地：Spec as Source of Intent ​

🛠️ 动手实验室（Hands-on Lab 02：对账单逆向追溯实战） ​

实验信息 ​

核心演练代码剖析 ​

触发 AI 评分 ​

🥊 避坑指南与常见死法（Antipatterns & Pitfalls） ​

死法一：相信数据库字段名和表注释 ​

死法二：试图强行统一跨部门口径 ​

死法三：口头对账，不留黄金基准 ​

🏆 通关验收卡与装备获取（Checkpoint & Loot） ​

📋 本关通关自检清单 ​

🎁 本关掉落装备 ​

02 · 第二关：业务侦探社 · 逆向工程与语义层扎根

⚔️ 本关作战任务（Context & Quest）

💣 现场惨案还原（The Murder Scene）

真实案情回顾（参见：

🧠 核心心法与底层原理（The Mental Model）

1. 软件工程的本源：物理存储模型 $\neq$ 业务领域模型

2. 业务逆向工程四步法（Reverse Engineering）

Step 1：锁定基准（Ground Truth）

Step 2：还原操作（Trace Operation）

Step 3：提炼规则（Extract Rules）

Step 4：沉淀契约（Spec & DAG）

3. Text-First 规范落地：Spec as Source of Intent

🛠️ 动手实验室（Hands-on Lab 02：编制对账单逆向追溯提示词工件）

实验信息

核心提示词与验收断言要点

触发 AI 评分

🥊 避坑指南与常见死法（Antipatterns & Pitfalls）

反模式一：轻信数据库字段命名与静态注释

反模式二：试图强行统一存在客观差异的跨部门口径

反模式三：仅凭口头对账，缺乏基准样例存盘

🏆 通关验收卡与装备获取（Checkpoint & Loot）

📋 本关通关自检清单

🎁 本关掉落装备

Step 3：破译暗坑（Crack Formula）

Step 4：沉淀契约（Spec & DAG）

3. Text-First 规范落地：Spec as Source of Intent

🛠️ 动手实验室（Hands-on Lab 02：对账单逆向追溯实战）

实验信息

核心演练代码剖析

触发 AI 评分

🥊 避坑指南与常见死法（Antipatterns & Pitfalls）

死法一：相信数据库字段名和表注释

死法二：试图强行统一跨部门口径

死法三：口头对账，不留黄金基准

🏆 通关验收卡与装备获取（Checkpoint & Loot）

📋 本关通关自检清单

🎁 本关掉落装备