# 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）。