fix(api): requireDatabaseUrl 早失败守卫；typecheck 门禁；build 排除 test；池生命周期注释

Co-Authored-By: Claude Code <noreply@anthropic.com>

apps/api/src/db/client.ts

@@ -2,12 +2,10 @@ import './env.js'
 import { drizzle } from 'drizzle-orm/postgres-js'
 import postgres from 'postgres'
 import * as schema from './schema.js'
+import { requireDatabaseUrl } from './env.js'
 
-// DATABASE_URL_TEST ?? DATABASE_URL 的回退链是 Task 13 集成测试的接线：
-// 测试临时库优先，开发库兜底。env 加载见 ./env.ts（向上查找仓库根 .env）。
-export function getDb(
-  connectionString = process.env.DATABASE_URL_TEST ?? process.env.DATABASE_URL!,
-) {
+// 每次调用都会新建连接池、由调用方持有其生命周期；`db.$client.end()` 可关闭（drizzle-orm 0.45 已暴露）。
+export function getDb(connectionString = requireDatabaseUrl()) {
   const sql = postgres(connectionString, { max: 5 })
   return drizzle(sql, { schema })
 }

apps/api/src/db/env.ts

@@ -16,3 +16,17 @@ for (;;) {
   if (parent === dir) break
   dir = parent
 }
+
+// 早失败守卫：postgres(undefined) 会静默回退到 OS 用户@localhost:5432（postgres.js 源码行为），
+// 本机多 PG 实例时 select 1 仍会通过、迁移可能打错库，故必须在建客户端前拦截。
+// allowTestUrl（默认 true）：运行时连接允许 DATABASE_URL_TEST ?? DATABASE_URL 回退链（Task 13 集成测试接线）；
+// 传 false 则只认 DATABASE_URL——drizzle 迁移用它，保证迁移永不指向临时测试库。
+export function requireDatabaseUrl({ allowTestUrl = true }: { allowTestUrl?: boolean } = {}): string {
+  const url = (allowTestUrl ? process.env.DATABASE_URL_TEST : undefined) ?? process.env.DATABASE_URL
+  if (!url) {
+    throw new Error(
+      'DATABASE_URL not set — copy .env.example to <repo-root>/.env (searched upward from cwd)',
+    )
+  }
+  return url
+}