# PROGRESS · 部署窗口 503 误标为「服务尚未配置」（2026-09-04）

工作树：`.worktrees/api-not-configured-mislabel-20260904`
分支：`codex/api-not-configured-mislabel-20260904`
基线：开工时 `origin/staging` @ `d2a209d3`（任务书写的是 `a75929c1`；staging 已含后续提交）。修复提交：`5483649b`。未改 `.gitea/workflows/**`、未动迁移、未升级依赖、未 bump Skill、未改 `createServerSupabaseClient` / `createAdminSupabaseClient` 抛错语义。

| 任务 | 状态 | BUG |
| --- | --- | --- |
| 共享 helper + 16 处替换 | 完成 | BUG-542 |
| 回归测试（agent + case 刷新） | 完成 | BUG-542 |
| BUG_HISTORY / CHANGELOG / 本文件 | 完成 | BUG-542 |

## 编号

开工时最大号 BUG-550。本单使用预留的 **BUG-542**。未占用 BUG-551 及之后。

## 实现要点

- `frontend/src/lib/api/service-unavailable.ts`：`jsonForSupabaseSetupFailure(error, routeName)`。仅 `isSupabaseConfigurationError` 返回「服务尚未配置」+「请先配置数据库环境变量。」；其它异常 `503` + `code=service_unavailable`，`console.error(routeName, error.name)`，不把 Error 对象打进日志。
- 16 处创建客户端的 catch 改为调用 helper（含 `consult/status` 的 server/admin 两段）。`birth-time-guide` / `birth-time-journey` 原先配置错误才 503、其它直接 throw，现与其余路由一样返回 `service_unavailable`。
- 未登录仍是 401。未改 health、未加重试。

## 测试

| 命令 | 结果 |
| --- | --- |
| `npx tsx --test tests/api-service-unavailable-20260904.test.ts` | 4 项；pass 4；fail 0（约 28s，agent 路由 mock 导入较重） |
| `npx tsx --test tests/self-hosted-error-copy.test.ts` | 1/1 |
| `grep -rn "服务尚未配置" frontend/src` | 只命中 `src/lib/api/service-unavailable.ts` |
| `npx tsc --noEmit` | 0 错 |
| 改动文件 eslint `--quiet` | 0 error |

Node 22 mock 契约：子进程 `mock.module(..., { namedExports })`（BUG-514）。本地 Node 24 会警告 `namedExports` 已弃用，不可改成 `exports`。

## 既有断言 / 文案变更（原值 / 新值 / 原因）

| 位置 | 原值 | 新值 | 原因 |
| --- | --- | --- | --- |
| 16 处 catch 对非配置异常 | `503`「服务尚未配置」或直接 throw | `503` `code=service_unavailable`「服务暂时不可用，请稍后重试」 | 决策记录 1：只有配置错误能说尚未配置 |
| `GET /api/models` 目录为空 | `error: "模型服务尚未配置"` | `error: "没有可用的咨询模型"` | 该句包含「服务尚未配置」子串，会撞验收 grep；这不是配置错误，是目录为空 |

未改既有测试断言。无既有测试把非配置异常锁成「服务尚未配置」。

## 遗留

未做浏览器真人走查。部署窗口的短暂 503 仍会出现，只是说法不再误导成环境变量丢失。未跑全量 `npm run lint` / `npm test`（任务书验收是 tsc + lint 0 error + 本单测试；改动文件 eslint 已 0 error）。

## 验收（Claude，2026-09-06，对照 `TASK-api-not-configured-mislabel-20260904.md`）

共用门禁（`origin/staging` @ `e2f4b55c`，含五单全部提交）：`tsc --noEmit` 0 错；`npm run lint` 0 error / 79 warning（全部既有）；`npx tsx --test tests/*.test.ts` 2770 项 / pass 2729 / fail 29 / skipped 12——29 条失败全为环境缺口（25 条 Docker / rsync / pyyaml 缺失的库测与部署套件；2 条 `--experimental-test-module-mocks` 子进程在本机 Node 20 下解析不到 `@/` 别名，CI 为 Node 22；2 条 `beam-avatar` / `chat-composer-queue` 渲染用例因验收工作树里一个多余的 `node_modules/node_modules` 软链造成双份 React，删链后单独重跑通过）；默认 `npm run build`（Turbopack）退出 0、`/` 为 `○ Static`、产物无 `/membership` 页；首屏 JS gzip-9（预渲染 `index.html` 引用脚本去重求和，与 09-02 口径一致）`d2a209d3` 519,437 B → `e2f4b55c` 522,617 B，**+3,180 B / +0.61%**，五单合计在 ±2% 内。执行方进度里「`next build --webpack` 停在 `dossierResponse` 导出类型」一事：`dc6598d7` 已去掉该 `export`，本次默认构建不再出现。

| 项 | 结论 | 依据 |
| --- | --- | --- |
| 5.1 共享 helper，只在 `isSupabaseConfigurationError` 时说「服务尚未配置」 | 通过 | `lib/api/service-unavailable.ts::jsonForSupabaseSetupFailure`；其余异常 503 `service_unavailable` + `console.error(routeName, errorName)`，不打印 message |
| 5.2 16 处路由替换、无遗漏 | 通过 | `grep -rn "服务尚未配置" frontend/src` 只命中 helper |
| 5.3 测试 `tests/api-service-unavailable-20260904.test.ts` | 环境缺口 | 4 条中 2 条走 `--experimental-test-module-mocks` 子进程，本机 Node 20 解析不到 `@/`（与既有 `report export` 用例同一模式）；CI Node 22 应绿，以门禁结果为准 |
| 5.4 BUG-542 记录、CHANGELOG | 通过 | `docs/BUG_HISTORY.md` BUG-542 |

**结论：通过**（2 条测试留 CI 复核）。修复 SHA `5483649b`。