工程复盘模板：从事实、判断到改进行动

# 好做法：纯事实描述
timeline:
  - time: "2026-06-20T14:32:00+08:00"
    event: "监控告警：订单服务 P99 延迟超过 3s"
  - time: "2026-06-20T14:35:00+08:00"
    event: "值班人员开始排查，发现数据库连接池耗尽"
  - time: "2026-06-20T14:52:00+08:00"
    event: "扩容连接池后恢复，持续 20 分钟"
 
# 坏做法：混入主观判断
timeline:
  - time: "2026-06-20T14:32:00+08:00"
    event: "由于数据库配置不当，导致系统变慢"
  # ❌ "配置不当"是结论，不是事实。事实阶段不应出现归因

# 好做法：具体描述有效实践
## 做得好的地方
1. 告警在 3 分钟内触达值班人员，MTTD（平均检测时间）符合 SLA
2. 值班人员按 Runbook 执行了连接池扩容操作，未做临时 patch
3. 恢复后立即建立了事后分析文档，没有拖过 48 小时
 
# 坏做法：笼统表扬
## 做得好的地方
1. 大家反应很快
2. 团队协作不错
# ❌ 没有具体行为，下次无法复现

# 问题：数据库连接池耗尽
 
## 5 Whys 分析
1. **为什么连接池耗尽？**
   → 慢查询占用了大量连接，释放速度跟不上请求速度
2. **为什么有慢查询？**
   → 新上线的报表查询缺少索引，全表扫描
3. **为什么缺少索引的查询能上线？**
   → SQL Review 流程跳过了这个查询，因为它是通过 ORM 动态生成的
4. **为什么 ORM 生成的查询不经过 SQL Review？**
   → Review 流程只覆盖手写 SQL，未覆盖 ORM 查询
5. **为什么流程存在这个盲区？**
   → 半年前引入新 ORM 框架时，没有同步更新 Review 规则
 
## 根因
SQL Review 流程未覆盖 ORM 动态生成的查询，导致缺少索引的慢查询进入生产环境。

# 好做法：三维度追问
1. 因何爆发？—— 直接技术原因
2. 因何未拦截？—— 检测/预防机制的缺口
3. 因何无系统性防范？—— 制度/流程/工具层面的缺失
 
# 坏做法：停在技术修复
1. 因何爆发？—— 慢查询
2. 解决方案：加索引
# ❌ 加了索引还会有下一个慢查询。问题在于流程缺口，不在单条 SQL

# 好做法：具体、可追踪
actions:
  - id: ACTION-001
    description: "在 SQL Review 规则中增加 ORM 动态查询的扫描配置"
    owner: "@zhangsan"
    priority: P0
    deadline: "2026-07-05"
    tracker: PROJ-1234
    verification: "CI 中 ORM 生成的 SQL 能触发慢查询检测"
    status: in_progress
 
  - id: ACTION-002
    description: "为报表查询添加复合索引 (tenant_id, created_at)"
    owner: "@lisi"
    priority: P0
    deadline: "2026-06-28"
    tracker: PROJ-1235
    verification: "报表查询 P95 < 500ms"
    status: done
 
# 坏做法：模糊、无人跟
actions:
  - "优化数据库性能"
  - "加强代码审查"
  - "完善监控告警"
# ❌ 没有 Owner、没有 Deadline、没有验收标准，永远不会被执行

# 30 天后检查模板
review_at: "2026-07-25"
actions_status:
  - id: ACTION-001
    status: done
    effect: "SQL Review 已覆盖 ORM 查询，拦截了 3 条潜在慢查询"
  - id: ACTION-002
    status: done
    effect: "报表查询 P95 从 2.1s 降到 320ms"
  - id: ACTION-003
    status: blocked
    reason: "依赖基础设施团队提供查询分析引擎，已排入 Q3"

// 坏做法：直接强转，不处理 null
let username = response["username"] as! String
// ❌ 如果 username 为 null 或类型不对，直接 crash
 
// 好做法：防御性解析
struct UserResponse: Codable {
    let username: String?
    let email: String?
    let nickname: String?
 
    enum CodingKeys: String, CodingKey {
        case username, email, nickname
    }
 
    init(from decoder: Decoder) throws {
        let container = try decoder.container(keyedBy: CodingKeys.self)
        // 所有可选字段都提供默认值
        self.username = try container.decodeIfPresent(String.self, forKey: .username) ?? ""
        self.email = try container.decodeIfPresent(String.self, forKey: .email) ?? ""
        self.nickname = try container.decodeIfPresent(String.self, forKey: .nickname) ?? "用户"
    }
}
// ✅ 即使后端返回 null，客户端也不会崩溃

actions:
  - "建立 API 变更的跨端通知机制：后端修改接口必须在跨端周会同步"
  - "客户端所有 API 响应字段必须使用 Codable + decodeIfPresent"
  - "新增 API 变更 Checklist，包含：向前兼容 / 可选字段 / 跨端通知"

-- 坏做法：只加索引，不改流程
CREATE INDEX idx_report_tenant_created
ON orders (tenant_id, created_at);
-- ❌ 解决了当前慢查询，但下一条 ORM 生成的慢查询还会出问题
 
-- 好做法：加索引 + 在 CI 中检测 ORM 慢查询
CREATE INDEX idx_report_tenant_created
ON orders (tenant_id, created_at);
 
-- 同时在 CI 管道中增加 ORM SQL 分析步骤
-- ci/sql-review.yml
sql_review:
  sources:
    - type: manual    # 手写 SQL
      path: "db/migrations/"
    - type: orm       # ORM 生成的 SQL
      config: "config/orm-review.yml"
      rules:
        - max_execution_time: 500ms
        - require_index: true
        - reject_full_table_scan: true

meeting_agenda:
  - item: "回顾上次 Action 完成情况"
    time: "5min"
    owner: "Scrum Master"
  - item: "快速过数据：本迭代交付量、Bug 数、关键指标"
    time: "5min"
    owner: "Tech Lead"
  - item: "做得好的（每人 1-2 条）"
    time: "5min"
    owner: "全员"
  - item: "待改进的（每人 1-2 条）"
    time: "5min"
    owner: "全员"
  - item: "选出 Top 3 改进项，指定 Owner 和 Deadline"
    time: "10min"
    owner: "Tech Lead 主持"