01 · 第一关：新手村破局 · 前期沟通与排期防御战

“当客户微笑着对你说‘这个需求很简单，用 AI 搞搞下周就能上线吧？’——请注意，关键风险信号已经出现。”
—— 一位百雀羚前线交付工程师的备忘录

---

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

• 交付现场：百雀羚项目立项现场与商务签约会议室
• 潜在风险：“Demo 带来的过度乐观”、“需求范围随意蔓延”、“忽略外部依赖的倒排期”
• 典型沟通诉求：
  • “你们的大模型不是能自动写代码吗？怎么还要搞一个月？”
  • “数据库账号下周肯定给你开，你们这周先把代码写完！”
  • “这个指标很简单的，全公司人都知道，你们看着办就行。”
• 本关核心目标：
  1. 客观厘清“原型 Demo”与“生产级交付”之间的工程量鸿沟；
  2. 搭建并推行 “三维就绪度评估矩阵（Readiness Assessment Gate）”；
  3. 规范排期机制，推行 “条件触发式动态排期契约（T+N 模型）”；
  4. 落地“业务侧 + 工程侧”的双轨协同模式；
  5. 动手运行并通过 labs/lab01-readiness-contract/ 实操推算器。

---

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

真实案情回顾（参见：01-前期沟通阶段遇到的问题/001-过度低估业务复杂度和项目排期.md）

百雀羚数字化项目刚立项时，团队内外曾一度对交付周期持有较乐观的估计。

前期销售与预研工程师在总部用开源大模型和几份脱敏测试数据，做了一个非常漂亮的 PPT 演示：

• 输入：“分析 2026 年 7 月防晒乳在华东区的销售走势”；
• 智能体用 2 秒钟生成了 SQL，并在界面上实时画出了漂亮的销售折线图。

甲方高管看后龙颜大悦，当场拍板：“太棒了！我们下个月正好有秋季订货会，就定在 4 周后全量上线！” 现场工程师也在“AI 生产力大爆发”的幻觉刺激下，胸脯拍得震天响：“没问题！两周写代码，一周联调，剩下一周喝咖啡准备上线！”

然而，进驻前线的第一天，噩梦般的倒计时就开始了：

骨牌一：真实表结构比想象脏十倍

进场拿到只读账号后，大家打开数据库一看，全傻眼了：

• 一个核心订单表有 130 多个字段，其中 40 个字段是 reserved_1, ext_str2 这种毫无意义的历史预留字段；
• 表中历史数据居然包含了大量的“测试下单”、“员工内购”和“未核销退货”，完全没有打标记。

骨牌二：外部依赖阻塞高达 70%

想要拉取精准口径，必须对接阿里云上的自建数据库。 然而，专线网络开通需要走客户内部的“跨部门安全合规审批”：

• 申请表提交后，审批流在财务、IT 运维、法务部门之间流转了整整 12 个工作日；
• 在这 12 天里，原本承诺的“两周开发期”被完全吞噬，工程师除了在本地干瞪眼，什么也干不了。

骨牌三：恶性通宵与信誉透支

眼看预定的上线日临近，团队只能被迫通宵加班。 由于前置环境和口径没对齐，仓促上线的系统在订货会上频频打脸：高管问出的数据和财务大盘相差了整整一千万，项目瞬间被推向公关危机的边缘。

---

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

1. 拆解 Demo 与 Production 的物理鸿沟

为什么 Demo 可以在两天内跑通，而真实系统需要两个月？ 用分布式系统的工程视角来看，Demo 是“无状态、无边界、无对抗”的真空实验，而 Production 则是“有状态、强合规、充满脏数据对抗”的泥潭：

评估维度	玩具 Demo（POC 阶段）	工业级生产交付（Production）
数据纯度	人工清洗过的 CSV，字段含义唯一	5 年历史遗留表，字段复用、枚举漂移、脏数据交织
网络拓扑	单机 localhost 或畅通公网	跨 VPC 子网隔离、堡垒机中继、反向代理 60s 握手超时
容错要求	偶尔报错刷新一下即可	严禁毒性静默吞错，Fail-Fast 秒级定位，高可用审计
外部依赖	零外部阻断，依赖自己说了算	跨部门权限审批、专线审批、业务最终仲裁人缺位
排期构成	90% 纯编码工时	30% 业务逆向 + 30% 核心工程 + 40% 外部依赖与对账

---

2. 三维就绪度前置评估门禁（Readiness Gate）

在 FDE 的字典里，没有无条件的排期，只有带门禁的契约。 在进入任何实质性编码前，必须通过三维体检表对客户现场进行全面勘探：

---

3. 条件触发式契约排期模型（Trigger-based Scheduling）

坚决对“从立项之日起，固定 30 天后上线”的盲目倒排期说不！ 成熟的 FDE 团队在合同与协议中只签署动态契约公式：

$$T_{\mathrm{上}\mathrm{线}}=T_0+N_{\mathrm{工}\mathrm{时}}+\sum {\mathrm{\Delta }}_{\mathrm{阻}\mathrm{断}\mathrm{等}\mathrm{待}}$$

其中：

• $T_0$（生效锚点）：严格定义为**“客户提供完整核准样本、且生产网络连通性探针全绿之日”**；在 $T_0$ 到达前，所有倒计时时钟处于暂停（PAUSED）状态；
• $N_{\mathrm{工}\mathrm{时}}$（净开发工时）：由工程团队评估的确定性研发周期；
• ${\mathrm{\Delta }}_{\mathrm{阻}\mathrm{断}\mathrm{等}\mathrm{待}}$（外部顺延条款）：当遇到客户跨部门审批延迟、账号权限收回、口径推翻等非技术因素时，上线日期自动等额（甚至加倍）顺延。

---

4. 现场交付“双轨协同”协作模式

在复杂交付场景中，推行**“双轨协同”**能够有效提升交付质量：

• 业务侧 FDE（Business FDE）：
  • 核心职责：业务口径对接、客户预期管理、对账结果核验；
  • 核心工作：与业务部门紧密对齐，将隐性业务规则整理为结构化的 Markdown 规范，推动范围冻结与验收确认。
• 工程侧 FDE（Platform / Systems FDE）：
  • 核心职责：系统稳定性保障、离线容器流水线维护、性能优化；
  • 核心工作：跨 VPC 网络连通性验证、Docker 离线镜像封装、Pydantic 强类型网关、全链路 Trace 监控。

---

🛠️ 动手实验室（Hands-on Lab 01：三维就绪度推算器）

现在，让我们编写一套可用于交付前期的排期推算与风险评估工具。

实验信息

• 沙箱路径：labs/lab01-readiness-contract/
• 任务目标：分析 context/client_survey.json 中客户真实的就绪度缺陷（28% 脏数据、专线审批 12 天、口径未冻结），在 starter/prompt.md 中编写结构化提示词工件，指挥 AI 生成带门禁加权评分与 T+N 动态顺延的推算器 contract.py。

触发 AI 评分

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

“用 fde-lab-scoring 技能，给 lab01-readiness-contract 评分并写改进建议。”

AI 依据本关 rubric.md（含未就绪禁开工门禁、T+N 顺延要点）逐维打分并给出改进建议，直到 🎉 PASS。统一评分技能见 labs/_scoring/。

---

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

1. 沉没成本误区：“已经答应客户了，只能加班硬顶”

• 反模式：明知数据未准备好、网络未开通，仍使用假数据仓促开工。
• 潜在风险：基于假数据开发的代码在接入真数据时往往需要大量返工，增加无谓损耗。
• 工程准则：前置卡点不可妥协。未满足基本准入条件时，应先推动前置治理，确保开发地基牢固。

2. 仲裁责任人缺位：“不同部门口径冲突，无明确裁决”

• 反模式：各部门意见不一时开发反复改动逻辑，两头受阻。
• 工程准则：在前期沟通中明确：“业务口径以指定业务责任人的书面确认为准”，跨部门分歧由客户内部协调一致后再行对接。

3. 需求范围蔓延（Scope Creep）

• 反模式：随意在前期承诺不属于当前范围的额外需求。
• 工程准则：推行严谨的 MVP Scope Freeze（范围冻结）。首期聚焦在最核心的业务场景，超出部分纳入后续阶段规划。

---

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

📋 本关通关自检清单

• [x] 客观认识到了原型验证与生产交付的差异；
• [x] 掌握了三维就绪度审查模型（数据、环境、业务）；
• [x] 理解了条件触发（T+N）动态排期的契约思想；
• [x] 通过了 AI 依据 labs/lab01-readiness-contract/rubric.md 的统一评分（🎉 PASS）。

🎁 本关掉落装备

• 装备名称：【契约守护者的排期罗盘】
• 装备属性：抗非技术延期能力 +100%，项目节奏把控力 +80%
• 装备描述：帮助团队在前期沟通中以客观事实和数据支撑合理的项目节奏，保护项目有序推进。

建立了明确的排期契约后，下一关我们将深入实际数据与计算口径——《第二关：业务侦探社 · 逆向工程与语义层扎根》！