---

### 文件 3：BUG-LESSONS.md（历次故障复盘 - 按根因分类）

```markdown
# 祈盟SDK 故障复盘 - 知识沉淀

> 按"根因"分类，不是按时间。
> 同样的根因在多个时间点出现 → 必须从架构层根治，不是修 Bug。

```

## 类别 1：批量查询无限制（高频根因）

### 案例 1.1：5/12 Redis 带宽打满

**症状**：直播平台 7000 用户查询，Redis 出口带宽 14h 被打满

**根因**：
- 上游调用方传 7000 个用户，接口直接查 Redis
- Redis 出口带宽 1Gbps 封顶
- 查询数据量超过带宽

**修复**（部分根治）：
- ✅ Redis 带宽升级到 5Gbps
- ✅ 接口加用户数限制 7000
- ❌ **没根治**：下次别的查询维度（角色/订单/充值）也会爆

**AI 启示**：
- 看到"批量查询" → 立即检查"是否有限流+分页"
- 看到"上游传 N 个参数" → 立即想"这个 N 上限在哪？"

### 案例 1.2：5/26 MySQL CPU 爆掉（同根因不同表象）

**症状**：抓取任务失败，连续重试，MySQL CPU 90%+ 持续 8 分钟

**根因**：
- 抓取脚本传 1 个游戏 ID + 7000 用户 ID
- 每个用户 200 个角色 → 2w 条 OR 条件 SQL
- MySQL 无法走索引合并优化 → 全表扫描

**修复**（部分根治）：
- ✅ 接口加 2000 条硬限
- ✅ 抓取改分批 1000 条
- ❌ **没根治**：2w 条 OR 条件 SQL 本身没改，**应该改临时表 JOIN**

**AI 启示**：
- 看到"OR 条件拼 SQL" → **立即**改成"IN 分批 + 服务层聚合"或"临时表 JOIN"
- 看到"批量查询失败重试" → **立即**想到"重试也会打死 DB"

---

## 类别 2：重试无退避（高频根因）

### 案例 2.1：5/26 MySQL 二次伤害（同事故的另一个根因）

**症状**：第一次请求超时后，**连续 5 次重试**，每次都打 DB

**根因**：
- 抓取脚本无脑 retry 5 次
- 每次重试都重新跑同一条 2w 条 SQL
- 重试相当于"给已死的 DB 浇油"

**修复**（**完全没做**）：
- ❌ 重试机制**至今未加退避**
- ❌ 没有熔断阈值

**AI 启示**：
- 看到 `for (int i = 0; i < 5; i++) retry()` → **立即**改为指数退避
- 看到"重试" → **立即**问"失败原因是瞬时还是持续？"

---

## 类别 3：缓存时长配置冲突（高频根因）

### 案例 3.1：6/16 Cookie 失效导致抓取中断

**症状**：11:40 抓取任务静默中断，无任何报错，订单数据缺失

**根因**：
- SDK 服务端 PHPSESSID = 14h
- 直播平台脚本缓存 Cookie = 24h
- 14h 后服务端 Session 失效，但客户端缓存还在
- 接口返回登录页，脚本误以为是"空数据"

**修复**（已闭环）：
- ✅ SDK 缓存有效期延长
- ✅ 直播平台加 Cookie 有效性校验
- ✅ 失效自动重新登录

**AI 启示**：
- 看到"客户端缓存" → **立即**问"服务端有效期是多少？客户端缓存 < 服务端有效期吗？"
- 看到"无校验的脚本任务" → **立即**加"每次执行前先校验缓存有效性"

---

## 类别 4：精度溢出（长期隐患）

### 案例 4.1：SDK 金额存储 double 精度问题（未根治）

**症状**：累计金额、提成计算出现微小误差（0.01 元级别）

**根因**：
- `amount DOUBLE(11,2)` 存储金额
- DOUBLE 是浮点数，无法精确表示 0.1/0.2 等值
- 累计计算后误差放大

**修复**（**没做**）：
- ❌ 长期遗留，**架构治理最低分项**
- 计划 v4.25 改 `DECIMAL(15,2)`

**AI 启示**：
- 看到 `DOUBLE` / `FLOAT` 存金额 → **立即**改为 `DECIMAL` 或 `BIGINT`（分）
- 看到"金额计算" → **立即**问"在数据库算还是在应用层算？"

---

## 类别 5：跨部门信息同步缺失（流程类）

### 案例 5.1：6/16 接口模式切换未通知

**症状**：5/26 上线新接口，5/26 晚用户反馈数据缺失，临时切换为爬虫，**只群里通知，没告知产品/发行**

**根因**：
- 接口/爬虫切换是重大变更
- 没有正式的"变更通知流程"

**修复**（部分）：
- ✅ 临时通知了
- ❌ 没有正式流程

**AI 启示**：
- 看到"切换数据源/接口" → **立即**触发"通知产品部 + 发行部"流程
- 看到"群里通知一下" → **立即**升级为"正式邮件 + 工单 + 文档记录"

---

## 类别 6：流程归口不清（架构治理类）

### 案例 6.1：4/13 P1 故障（流程类）

**症状**：需求私对接开发，验收无标准，数据异常无提报模板

**根因**：
- 没有 P0/P1/P2/P3 判定标准
- 没有数据异常提报模板
- 没有测试验收规范

**修复**（部分）：
- ✅ 4 级优先级标准
- ✅ 数据异常模板
- ❌ 测试验收规范未落地

**AI 启示**：
- 看到"需求无验收标准" → **立即**要求"先有验收标准，再写代码"
- 看到"私对接开发" → **立即**走"需求归口 = 产品部"