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

验收（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。