docs: document upstream model config failure

progress.md

@@ -1318,3 +1318,23 @@
   - `06-tasks.md` T-606 验收新增「视觉一致性」：抽共享 CSS 变量（`brand.css`），**首页与现有 portal（dashboard/记录/充值/API Key）一起套同一套 token**，不是只做漂亮首页。
   - `docs/README.md` 导航登记 brand.md。
 - 桌面端 cmbot（独立项目）：品牌层对齐（logo/主色/术语），UI 渐进靠拢、单独排期，不阻塞 T-606。
+
+## 2026-07-06 线上缺陷：标题生成返回「上游模型配置不可用」
+
+- 背景：线上已拉取最新代码 `7854b50` 并重启 `cmhub-web.service` / `cmhub-generate.service`；用 `api_key.txt` 第二个 Key 按文档 demo 测试 `POST /api/v1/generate/title`。
+- 复现结果：
+  - `GET https://cm.833729.com/api/v1/balance`：成功，返回 `user=admin`、`points_balance=1010`，并包含最新代码新增的 `account.username/display_name`。
+  - `GET https://cm.833729.com/api/v1/models`：成功，`title-standard` 存在，`operation_type=title`，`pricing_status=priced`，默认单价 1 点。
+  - `POST https://cm.833729.com/api/v1/generate/title`：返回 `502`，错误体为 `{"error":{"code":"upstream_error","message":"上游模型配置不可用"}}`。
+  - 失败后复查余额仍为 1010，确认未扣点。
+- 判定：API Key、base URL、请求 payload、能力别名和计费规则均正常；问题在服务端 `title-standard` 对应 `AiModel` 的运行配置，不应要求桌面端继续修改 payload。
+- 解决方案：
+  - 检查线上 `.env` 的 `AI_KEY_ENCRYPTION_KEY` 是否存在、有效且与导入/保存 `AiModel.api_key_encrypted` 时一致。
+  - 在 django-admin 检查 `ModelAlias(title-standard)` 是否 active、`operation_type=title`、指向 active 的 `AiModel`。
+  - 检查对应 `AiModel` 的 `url`、`model`、`api_type`、`capabilities` 和 API Key 是否完整；标题模型至少要有 `text` 能力。
+  - 若解密失败或 key 曾变更，用当前 `AI_KEY_ENCRYPTION_KEY` 重新保存 API Key，或重新执行 `import_ai_models`。
+  - 修复后重启两个 systemd 服务，跑 `python3.12 manage.py smoke_ai_generation title`，再用 API Key 验证 `/balance`、`/models`、`/generate/title`。
+- 文档变更：
+  - `docs/api.md`：补充 `upstream_error` + 「上游模型配置不可用」的判定口径。
+  - `docs/deployment.md`：新增 AI 上游配置故障处理步骤、shell 诊断命令和验收路径。
+  - `docs/current-state.md`：记录线上复现结果，并把真实 AI blocker 从“待验证”改为“已复现模型配置不可用，需修模型运行配置”。