# 故障 / Bug 解决方法论

> **第一性原理拆解** —— 让"修一个 bug"等于"修一类问题"，不再是"修一个症状"。

## 为什么需要这份文档

bug 解决最常见的失败模式：**停在层 2（直接原因）**。

例：用户报"晚上打卡 401" → 直接原因是"前端只判 token 字符串、不验有效性" → 改前端发 `/users/me` 校验 = 表面修复完成。

但真根因有 5 个叠加（env 名字漂移、依赖隐式 ESM 升级、4 套 Node 版本不一致、完工定义模糊、监控缺失）。**只修表面下次会以别的形式炸**——这就是 [工单 #242](http://43.130.59.228/FFAIWorkspace/workspace/issues/242) 一个表面 bug 牵出 8 个独立问题的根本机制。

约束本质：**应用层修好了 ≠ 真正修好了**。还需要工程化保险，让同类问题以后能被自动拦截。

---

## 3 层拆解（强制结构）

| 层 | 内容 | 例（#242） |
|---|---|---|
| 层 1：表面症状 | 用户/监控看到的现象 | 晚间打卡 401，UAT backend crash loop |
| 层 2：直接原因 | trace 到的具体代码 / 配置 | 前端只判 token 字符串；otplib 顶层 require ESM 包 |
| 层 3：元根因 | 治理层问题（契约 / 依赖 / 环境 / SOP / 监控） | env 名字四方漂移；transitive dep 升 ESM 没人发现 |

**铁律**：诊断到层 2 不许停。强制问"这个直接原因的元根因是什么？"

**元根因都是治理层问题**——不是某个具体代码 bug，是"机制没固化"。常见 5 类：

1. **契约面没固化** —— 真相源不唯一、派生位漂移、无自动校验
2. **依赖关系不可见** —— lockfile 变更、transitive dep 升级无监控
3. **环境一致性缺失** —— 本地/CI/UAT/PROD 多套环境点漂移
4. **完工定义模糊** —— grep 文件、命令成功代替"实测业务行为"
5. **监控告警缺失** —— 进程异常、依赖断、业务异常无人收到通知

> **5 条规则的完整阐述、适用范围、docs 落地状态、工程化保险依赖**详见 [`12-five-meta-rules.md`](./12-five-meta-rules.md)。本节只列分类，不展开。

---

## 行动准则

1. 不要停在层 2。直接原因找到后强制追到层 3。
2. **修复必须分两层并行**：
   - **应用层修复**：修当前坏掉的代码（4 环境验证）
   - **工程化保险**：让同类问题再出现时能自动拦截
3. **缺工程化保险 = 没真正修好**。靠 learning + 记忆约束的，是"靠人"不是"靠系统"。
4. 工程化保险做不到 100% 时，至少开 issue 跟踪，别留口头约定。

---

## 复盘模板（事故 / P0/P1 工单关闭强制）

任何 P0/P1 级别工单关闭前，复盘 doc / issue comment 必须包含以下 6 段：

```markdown
## 表面症状
（用户/监控看到的现象，含发生时间、影响范围）

## 直接原因（层 2）
（trace 到的代码 / 配置，给文件路径 + 行号）

## 元根因（层 3，至少 1 个）
- 契约面 / 依赖图 / 环境一致性 / 完工定义 / 监控告警 中的哪一类
- 为什么这个治理层缺失会导致今天这个 bug

## 应用层修复
（修当前坏掉的代码，列 PR/commit；本地/CI/UAT/PROD 4 环境验证结果）

## 工程化保险
（让同类型再出现时自动拦截。具体工具 / CI / 告警 / hook，
 做不完的开 issue 跟踪并在此引用 issue 号）

## 防复发评分
- 应用层：xx%
- 工程化保险：xx%
- 整体根源解决度：xx%（应用层 + 工程化保险的加权）
```

---

## 强制要求

- **任何 P0/P1 工单关闭** 必须满足：
  - 复盘 6 段齐
  - **至少识别 1 个元根因**
  - **至少 1 条工程化保险**（哪怕仅仅是"开 issue 跟踪"也算）
- AI 协作收到 bug 报告时，**默认按 3 层拆解走**，不直接跳代码改。
- 修完只要还有元根因没工程化保险覆盖，根源解决度 ≠ 100%，必须显式标。

---

## 参考案例

- [工单 #242](http://43.130.59.228/FFAIWorkspace/workspace/issues/242)：晚间打卡 401 → 5 元根因。本方法论的诞生案例。
- [工单 #249](http://43.130.59.228/FFAIWorkspace/workspace/issues/249)：#242 后续工程化保险三件套，覆盖 5 元根因的拦截工具。
- [工单 #251](http://43.130.59.228/FFAIWorkspace/workspace/issues/251)：5 条元根因规则融入工作流。

## 关联

- `.agents/skills/troubleshoot/SKILL.md` —— 故障排查技能（运行时诊断流程）
- `docs/standards/05-development-workflow.md` —— 开发工作流总入口
- `.learnings/ERRORS/` —— 历次 ERR 沉淀，#242 的 6 条 ERR 是模板示例