diff --git a/DEV_GUIDE.md b/DEV_GUIDE.md
index 541bf1fa..d0d362e0 100644
--- a/DEV_GUIDE.md
+++ b/DEV_GUIDE.md
@@ -209,7 +209,30 @@ git add ent/       # 生成的文件也要提交
 
 ---
 
-### 坑 10：PR 提交前检查清单
+### 坑 10：前端测试看似正常，但后端调用失败（模型映射被批量误改）
+
+**典型现象**：
+- 前端按钮点测看起来正常；
+- 实际通过 API/客户端调用时返回 `Service temporarily unavailable` 或提示无可用账号；
+- 常见于 OpenAI 账号（例如 Codex 模型）在批量修改后突然不可用。
+
+**根因**：
+- OpenAI 账号编辑页默认不显式展示映射规则，容易让人误以为“没映射也没关系”；
+- 但在**批量修改同时选中不同平台账号**（OpenAI + Antigravity/Gemini）时，模型白名单/映射可能被跨平台策略覆盖；
+- 结果是 OpenAI 账号的关键模型映射丢失或被改坏，后端选不到可用账号。
+
+**修复方案（按优先级）**：
+1. **快速修复（推荐）**：在批量修改中补回正确的透传映射（例如 `gpt-5.3-codex -> gpt-5.3-codex-spark`）。
+2. **彻底重建**：删除并重新添加全部相关账号（最稳但成本高）。
+
+**关键经验**：
+- 如果某模型已被软件内置默认映射覆盖，通常不需要额外再加透传；
+- 但当上游模型更新快于本仓库默认映射时，**手动批量添加透传映射**是最简单、最低风险的临时兜底方案；
+- 批量操作前尽量按平台分组，不要混选不同平台账号。
+
+---
+
+### 坑 11：PR 提交前检查清单
 
 提交 PR 前务必本地验证：