git-learn/skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md

SM Flow 执行复盘 - 山东商客意向单同步接口

项目: yingke-platform
需求: 385 山东公司商机信息同步接口
执行日期: 2026-06-23
复盘人: Claude Code

---

执行概况

• 需求规模: 中等（3个接口 + Kafka消费 + 数据库变更）
• 总耗时: 约 2 小时（含多次返工）
• 返工次数: 4-5 次重大返工
• 最终状态: 核心代码完成，但验签/解密/查询接口未实现

---

发现的问题

1. 前置调研不足，导致多次返工

问题表现

返工点	初次实现（错误）	返工后（正确）	浪费时间
RequestMsg 结构	自创 SyncIntentOrderReq/Resp	使用项目标准 RequestMsg<T>	15 分钟
Kafka 发送方式	SendMessageTunnel + TaskTypeEnum	ykMqTemplate + @YkMsg	20 分钟
Consumer 模块位置	order-service 模块	web 模块（参考案例位置）	10 分钟
透传字段结构	Map → DTO → 最终平铺	应一次到位平铺到 Msg	15 分钟

根本原因: apply 阶段直接开始写代码，没有充分调研现有代码模式。

改进建议

在 apply 阶段前增加强制调研步骤（pre-apply research checkpoint）：

1. 阅读所有参考实现（设计文档中明确提到的）

   • 完整阅读参考代码，而不是凭想象
   • 提取关键模式：请求结构、Kafka 使用、模块划分

2. Grep 关键技术栈

   grep -r "@YkMsg" --include="*.java"
   grep -r "ykMqTemplate" --include="*.java"
   grep -r "RequestMsg<" --include="*.java"
   

3. 形成"技术栈清单"文档（临时产物）

   - 项目使用 RequestMsg<T> 作为统一请求包装
   - Kafka 消息使用 @YkMsg + MsgData + ykMqTemplate.sendAsync()
   - Consumer 统一放在 web 模块的 manager/stream/consumer
   

4. 调研时间要求: 不少于 15 分钟，复杂需求可延长至 30 分钟

---

2. 设计文档与实现偏离，缺少一致性检查

问题表现

设计文档要求	实际实现	偏离程度
Controller 层 SM3 验签	只有 TODO 注释	❌ 核心功能缺失
Service 层 AES256-GCM 解密	只有 TODO 注释	❌ 核心功能缺失
queryIntentOrder 调用一体化客服	空实现	❌ 核心功能缺失
syncIntentOrder 同步调用	改为 Kafka 异步	⚠️ 架构差异（可能合理）

根本原因: apply 阶段没有"设计-实现对齐检查点"。

改进建议

在 apply 阶段中增加对齐检查点（alignment checkpoint）：

1. 每完成 1 个接口/模块，立即对比设计文档

   • 逐条核对设计文档的任务清单
   • 标记"已完成/部分完成/TODO"

2. 核心功能不允许"TODO 占位"直接通过

   • 加密/解密、验签、核心业务逻辑必须实现或明确标注"待联调"
   • 区分"框架完整但待联调"（✅） vs "空实现"（❌）

3. 架构差异必须显式记录并询问用户

   • 设计说同步，实现改异步 → 必须记录原因并确认
   • 创建 decisions.md 记录所有偏离设计的架构决策

---

3. 分步验证不足，一次写太多代码

问题表现

• 一次性写完 Controller + Service + Kafka + Consumer，然后发现 RequestMsg 结构错了
• 没有"写一点 → 编译 → 确认方向"的小步迭代

改进建议

强制分步验证（incremental validation）：

1. Controller 层先行

   • 只写 Controller + 最小 Service 骨架
   • 确认请求/响应结构正确
   • 编译通过后再继续

2. Kafka 发送独立验证

   • 写完发送逻辑，先打印 JSON 确认消息格式
   • 再写 Consumer

3. Consumer 最后实现

   • 基于已确认的消息格式实现

---

4. 参考案例利用不充分

问题表现

• 设计文档明确提到"参考 AddIntentOrderOutSystemDealTunnel"
• 但实际执行时，直到用户提醒才去看参考实现
• 之前都在凭想象写，导致返工

改进建议

强制参考案例优先（reference-first approach）：

1. grill 阶段就应该找出所有参考案例

   • 不要只记录"参考 XXX"，而是实际阅读并提取模式

2. apply 前必须完整阅读参考实现

   • 不是"扫一眼"，而是逐行理解关键逻辑
   • 提取可复用的代码片段

3. 参考案例模式提取清单（临时文档）

   ## AddIntentOrderOutSystemDealTunnel 关键模式
   
   1. Consumer 方法签名: `public void onXXX(XXXMsg msgBO)`
   2. 调用链: msg → AES加密 → OnlineOpportunityApi → 回填状态
   3. 异常处理: try-catch → updateStatus(EXCEPTION) → throw
   4. 成功判断: isSyncSuccess() 三层校验
   

---

5. grill 阶段澄清不够深入

问题表现

• grill 阶段问了业务问题（省份校验、透传字段），但没有问技术实现问题
• 导致后续实现时才发现技术栈不熟悉

改进建议

grill 阶段增加技术实现澄清：

除了业务澄清，还应该包括：

1. 技术栈确认问题

   • "项目现有的 Kafka 消息怎么定义和发送？"
   • "RequestMsg/ResponseMsg 的标准用法是什么？"
   • "类似接口的 Controller/Service 是怎么写的？"

2. 参考实现确认

   • "设计文档提到的参考实现是哪些文件？"
   • "这些参考实现的核心模式是什么？"

3. 技术风险识别

   • "有哪些技术点我不熟悉，需要先调研？"

---

改造建议汇总

方案 A: 在现有 9 阶段中增强（保守）

clarify → context → propose → grill+ → specify → audit → commit → pre-apply+ → apply+ → archive
                                  ↑                                      ↑        ↑
                           增加技术澄清                             增加调研  增加检查点

修改点：

1. grill 阶段：增加技术实现澄清问题模板
2. apply 阶段前：增加 pre-apply research checkpoint（15-30分钟）
3. apply 阶段中：增加 alignment checkpoint（每完成1个模块对比设计文档）

方案 B: 新增独立调研阶段（激进）

clarify → context → propose → grill → research → specify → audit → commit → apply → archive
                                                    ↑
                                          新增独立调研阶段

新阶段 research：

• 输入: proposal + 参考实现列表
• 输出: 技术栈清单 + 参考模式提取 + 风险评估
• 时间: 15-30 分钟
• 产物: research.md（临时文档，archive 时删除）

research.md 结构：

# 技术调研 - [需求名称]

## 参考实现分析

### AddIntentOrderOutSystemDealTunnel
- 文件位置: web/manager/stream/consumer/...
- 关键模式:
  - Consumer 定义: @YkMqConsumer + MsgData 子类
  - 调用链: ...

## 技术栈清单

- 请求结构: RequestMsg<T> / ResponseMsg<T>
- Kafka: @YkMsg + ykMqTemplate.sendAsync()
- 加密: AESUtil.encryptAES() (AES-128 ECB)

## 风险点

- AES256-GCM 工具类不存在，需要新建
- 验签逻辑没有现成拦截器，需要在 Service 层实现

推荐方案

方案 A（渐进增强）：

1. 对现有流程影响小
2. 实施成本低
3. 可以立即生效

具体实施：

• 修改 phase-contracts.md 的 grill 和 apply 阶段规范
• 增加 checkpoint 描述
• 更新 question pool 增加技术澄清问题

---

其他建议

1. 增加"快速失败"机制

当发现以下情况，立即暂停并询问用户：

• 需要创建的类/接口在参考实现中有类似的（防止重复造轮）
• 实现方式与设计文档明显偏离
• 连续返工超过 2 次（说明方向可能错了）

2. 产物可观测性增强

在 apply 阶段，定期输出：

## 实现进度（每 30 分钟更新）

✅ Controller 层（已完成）
  - ShandongSyncController.syncIntentOrder
  - 请求结构使用 RequestMsg<ShandongIntentOrderData>
  
🚧 Service 层（进行中）
  - ShandongSyncService 接口完成
  - 实现类 70% 完成
  - ⚠️ 验签解密未实现（TODO）
  
⏳ Kafka 层（待开始）

3. 设计文档质量要求

设计文档应该包含：

• ✅ 参考实现的具体文件路径（而不是只说"参考 XXX"）
• ✅ 关键技术栈的使用示例（而不是只说"使用 Kafka"）
• ✅ 数据流图（清晰展示同步/异步边界）

---

总结

核心问题: apply 阶段"想当然"开始写代码，缺少充分调研和分步验证。

解决方向: 在 apply 前增加强制调研步骤，在 apply 中增加对齐检查点。

预期效果: 返工次数从 4-5 次降低到 0-1 次，实现质量与设计文档一致性提升。

立即可做: 修改 phase-contracts.md 的 grill 和 apply 阶段规范即可生效。