Jyotisha/docs/tasks/PROGRESS-api-not-configured-mislabel-20260904.md

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