🧪 实战示例：官网询价需求，从 PRD 走到上线

这是一份按当前工作流（编号文档链 01-09）编排的完整示例，不是历史记录逐条复述；业务细节做了简化脱敏。
场景：客户在官网提交询价 → 单据落到 TMS → 客服跟进报价，本次要新增“官网来源”标识和询价明细回写。
文档按目标编号书写：03 / 07 / 08 / 09 的编号命名目前正在统一中。

🗺️ 全景：一条需求要过九道关

flowchart TD
    S0["材料: PRD.html / 原型 / 测试环境"] --> S1["01 grill-me<br/>拷问需求 → 需求分析"]
    S1 --> S2["02 codebase-onboarding<br/>抓包 + 定位代码与表 → 代码库全景"]
    S2 --> S3["03 doc-tech-solution<br/>技术方案"]
    S3 --> S4{"04 tech-solution-review<br/>评审通过?"}
    S4 -->|"不通过"| S3
    S4 -->|"通过"| S5["05 doc-implementation-log<br/>分批实现 + 边做边记"]
    S5 --> S6["06 code-review ×2<br/>规范 + 业务"]
    S6 --> S7["07 自测清单 + 执行自测"]
    S7 --> S8["08 联调文档 → 前端联调 → 提测"]
    S8 --> B{"测试通过?"}
    B -->|"有 Bug"| BH["bug-hunter<br/>三重证据收敛"]
    BH --> S5
    B -->|"通过"| S9["09 上线清单 → 发布交付"]

📥 第 0 步｜材料先入库（markitdown）

一句话：先把看不了、搜不到的材料，变成 AI 能读的 Markdown。

把 docs/官网询价/ 下的 PRD.html、原型截图、旧接口文档转成 Markdown，
输出到 docs/requirements/官网询价/00-source/

• 输入：HTML PRD、原型图、旧版接口文档、测试环境地址与账号
• 产出：可检索的需求文本，后面所有分析都引用它
• 卡点：材料缺哪块直接列出来，不靠猜

🧭 第 1 步｜抓包定位现状（codebase-onboarding）

一句话：别从代码猜业务，先让 AI 在测试环境里把真实请求抓出来。

用 Playwright MCP 打开 TMS 测试环境，走一遍“新建询价单 → 提交 → 列表查看”，
把请求、响应和页面关键字段抓下来，再按接口路径定位 Controller → Service → Mapper

动作	具体做法	产出
打开测试环境	Playwright MCP 起 Chrome，录下关键请求	接口清单 + 请求响应样例
定位代码	用接口路径 Grep 出调用链	Controller → Service → Mapper
摸数据结构	抓包字段反查表与字段，DDL 只认 ~/.agents/sql/	数据模型与索引说明
汇总	技术栈、模块、业务域、外部依赖、风险点	02-codebase-analysis.md

⚠️ 测试环境只读：不改数据、不动配置；字段含义以 DDL 注释和真实抓包为准。

❓ 第 2 步｜把需求问到没有歧义（grill-me）

一句话：需求阶段的每一个“应该”，都要变成一个明确的答案。

维度	我的追问示例	为什么问
目标与范围	官网询价单进系统是新建单据，还是挂到已有客户下？	决定主流程与数据归属
业务规则	同一手机号重复提交，覆盖还是并存？	决定幂等与去重策略
数据与字段	预计月单量分 5 档，落库用字典还是枚举？	决定表结构与字典初始化
接口与依赖	官网侧要不要状态回写？失败怎么重试？	决定对接方式与异常处理
验收标准	什么算做完？列表能否按来源筛选？	作为验收与自测依据

有些问题光靠讨论定不了，就让 AI 出只读 SQL，我在 DataGrip 执行后把结果贴回来：

-- 看历史来源分布和空值情况，判断是否需要默认值
select source, count(*) as cnt from web_inquiry group by source;

产出 01-requirements-analysis.md：功能点、边界、异常流程、待确认问题表。

📐 第 3 步｜方案与评审（doc-tech-solution + tech-solution-review）

一句话：方案先写清楚，再让人挑刺；评审不过就不进编码。

方案要覆盖：改动范围、业务流程图、表结构与字段变更、接口契约、任务拆分、兼容与回滚。

评审按六个维度过一遍：需求覆盖、架构一致性、数据层设计、边界异常、过度设计、可回滚性。

评审提出的问题	级别	处理结果
批量回写没分批，有锁表风险	🔴 P0	改 id 游标分页，每批 500
新增表缺公共字段与 NOT NULL 约束	🔴 P0	按 mysql-create-field.md 补齐
想加一层“询价中台”抽象	🟢 P2	砍掉：当前只有两个来源，够用就行

产出 03-technical-solution.md + 04-solution-review.md；评审通过后才定档，定档版本才允许进编码。

🔨 第 4 步｜分批实现（doc-implementation-log）

一句话：按文档分批做，边做边记账；编译不过不算完成。

换会话或换 agent 时先交接（conv-handoff / cross-agent-sync），接手方先核对当前代码和工作区，避免两边同时改同一片代码。

批次	内容	依赖	结果
1	DDL + 字典初始化 SQL	无	脚本交付，由我执行
2	Entity / Mapper / Service	批次 1	编译通过
3	官网询价接口 + 回写逻辑	批次 2	编译通过
4	列表筛选与导出	批次 3	编译通过，未自测

产出 05-implementation-log.md：每个任务的改动文件、编译结果、未验证项、风险与下一步。

🔀 中途需求变了就走 change-handler 分级：L1 直接改、L2 按当前阶段做最小代价调整、L3 回退到 04 重新评审。

🔍 第 5 步｜两道代码审查（code-review-skill-main / business）

一句话：一个查“做好了没”，一个查“做对了没”。

每批写完先做一次简版自查：改动有没有越出方案范围、编译过没过；四批都完成后，再上两道正式审查。

审查	看什么	本次典型发现
code-review-skill-main 规范审查	分层、DTO/VO、枚举、SQL、性能、并发、可维护性	Service 里出现循环查库，改成批量查询
code-review-skill-business 业务审查	对照需求与方案，验证逻辑覆盖与接口契约	重复提交没做幂等，补唯一键 + 前置校验

产出 06-code-review.md：P0 必须修完，P1/P2 记录处理结论；修完重新编译。

✅ 第 6 步｜自测（doc-self-test-checklist）

一句话：先喂真实数据，再生成清单；生成清单不等于执行过自测。

#	场景	入参	期望	断言	结果
1	新增官网询价	必填字段 + 月单量 300-500	200 并返回单号	落库来源 = 官网	✅
2	同手机号重复提交	同上	按约定去重	仅一条有效单据	⚠️ 修正后通过
3	月单量不传	少传字段	400 或按默认值	不落空值	✅

产出 07-self-test-checklist.md；测试数据不足时先补数据或标成前置条件，不编造参数。

🔗 第 7 步｜联调与提测（doc-frontend-integration）

一句话：给前端的文档必须和当前代码一致，不能靠口头传。

文档包含：接口路径、字段说明、示例请求与响应、错误码、调用顺序、环境地址；前端联调通过后进入提测。

🐛 第 8 步｜测试期 Bug 闭环（bug-hunter）

一句话：每个结论都要有日志、代码或数据兜底。

flowchart LR
    A["现象 + 日志 + 请求报文"] --> B["追代码链路"]
    B --> C["生成只读诊断 SQL"]
    C --> D["我执行并回传结果"]
    D --> E{"证据支持根因?"}
    E -->|"否"| B
    E -->|"是"| F["修复 + 编译 + 回归"]

轮次	假设	证据	结论
1	字段映射错位	抓包与日志字段一致	排除
2	状态回写失败	数据 status=0，且无回写日志	锁定：异常未捕获导致中断
3	修复后回归	重跑自测用例 1-3	通过，关闭

🚦 第 9 步｜发布（doc-release-checklist）

一句话：发布清单是给发布人员的操作手册，必须含回滚。

清单内容	本次示例
数据库变更	DDL（新增表/字段）+ DML（字典初始化），分批与顺序写清楚
配置与开关	新增开关的默认值与生效范围
发布顺序	先发服务，再执行 SQL，最后开开关
验证方法	按自测清单抽 3 条核心用例验一遍
回滚方案	关开关 → 回滚服务 → 执行回滚 SQL

📊 复盘：这套流程真正省在哪

环节	以前	现在	关键变化
需求确认	反复口头问，边界容易漏	五维度一次问清并留档	grill-me + 01 文档
现状摸底	自己翻代码翻半天	抓包反查，链路一次摸清	Playwright MCP + 02 文档
方案返工	编码中才发现设计问题	编码前评审拦下	04 评审卡点
交付文档	手写 4-8 小时	按模板生成 + 人工复核	07 / 08 / 09
Bug 排查	靠经验猜	三重证据逐步收敛	bug-hunter

三条体会：

• 卡点比速度重要：评审不过不进编码、编译不过不算完成、生成清单不等于执行自测。
• 事实优先：字段、枚举、状态一律以抓包、DDL 和真实查询为准。
• 留痕即效率：实现日志是自测和交接的事实来源，交接前必须更新。