@taicode/common-server 3.8.0 → 4.0.0-beta.10

package/output/core/modules/system-routes/index.js

@@ -0,0 +1,205 @@
+import { catchIt, SystemError } from '@taicode/common-base';
+import { z } from 'zod';
+import { createSuccessResponse } from '../response/index.js';
+import { routerSchema } from '../schema/builders.js';
+/**
+ * 框架内置系统路由（`app/core/system-routes.ts`）——**框架自动注册、应用侧零注册**。
+ *
+ * 背景：各应用此前各自维护一份 `modules/system/router.ts`（account / release / notice /
+ * expense / open-trade / observai 各写一份），契约容易漂移。现收进框架 core，由 `registerSystemRoutesStep`
+ * 在 `routers` 阶段**之前**统一注册，从 `AppIdentity` + `ctx.services` + `ctx.readConfig` 派生。
+ *
+ * 与既有应用 router 对齐的契约（路径 / 方法 / 响应信封 / NoLogin 语义）：
+ *
+ * | 方法 | 路径 | 说明 | 信封 `data` |
+ * |------|------|------|-------------|
+ * | GET  | `/`              | 服务可用性 | `string`（`identity.service`） |
+ * | GET  | `/health`        | k8s probe（NoLoginRequired） | `{ healthy: true }` |
+ * | GET  | `/system/openapi`| OpenAPI 文档（NoLoginRequired，**原样返回、不套信封**） | — |
+ * | POST | `/system/health` | API 版健康检查 | `{ healthy: true }` |
+ * | POST | `/system/info`   | 版本 + 运行时信息（NoLoginRequired，**不得含管理员等内部配置**） | `{ version, runtime }` |
+ *
+ * 健康检查：遍历 `services` 的**可选** `health()`，任一失败 / 非 `true` → 整体不健康，
+ * 抛 `SystemError('UNKNOWN_ERROR', { operation: 'healthCheck' })`（错误码与信封稳定，不得改）。
+ *
+ * `readConfig` 为**请求期惰性读取**（出 spec 路径不跑 `config` 槽位，故任何读取都必须发生在
+ * 请求处理器内，而非注册期）。
+ */
+/**
+ * 响应信封助手：**直接用 `core/response` 的实现**。
+ *
+ * 这里曾经保留一份更窄的本地副本，理由写的是「框架的 `createSuccessResponse`
+ * 返回 `status: string` 过宽」——那其实是框架自己的类型缺陷（见 `core/modules/response`
+ * 里 `SuccessResponse` 的说明），修在源头之后副本就没有存在理由了。
+ *
+ * 同一个信封在一个仓里有多份实现，迟早会出现「某一份改了、其他没改」的局部不一致，
+ * 而它们的目标形状本应完全一样。
+ */
+/** 响应信封（成功 `status: 'SUCCESS'`；错误 `data: null`，`status` 放稳定错误码字符串） */
+function successEnvelope(data) {
+    return z.object({
+        status: z.enum(['SUCCESS']),
+        message: z.string(),
+        data,
+    });
+}
+/** 错误分支信封：`status` 放开为字符串（错误码集合不由框架枚举），`data` 恒为 `null` */
+function errorEnvelope() {
+    return z.object({
+        status: z.string(),
+        message: z.string(),
+        data: z.null(),
+    });
+}
+/** 200 / 400 / 500 三分支响应（与各应用 `responseSchema` 同形） */
+function responseEnvelopeSchema(data) {
+    return {
+        200: successEnvelope(data),
+        400: errorEnvelope(),
+        500: errorEnvelope(),
+    };
+}
+const RootSchema = routerSchema({
+    operationId: 'getRoot',
+    summary: '根路由',
+    tags: ['系统'],
+    description: '服务可用性检查（无需认证）',
+    response: responseEnvelopeSchema(z.string()),
+});
+const HealthCheckSchema = routerSchema({
+    operationId: 'healthCheck',
+    summary: '健康检查',
+    tags: ['系统'],
+    description: '检查服务及其依赖是否正常运行（无需认证，用于 k8s readiness/liveness probe）',
+    response: responseEnvelopeSchema(z.object({ healthy: z.boolean().describe('服务是否健康') })),
+});
+const SystemHealthCheckSchema = routerSchema({
+    operationId: 'systemHealthCheck',
+    summary: '健康检查（API）',
+    tags: ['系统'],
+    description: '检查服务及其依赖是否正常运行（API 调用版）',
+    response: responseEnvelopeSchema(z.object({ healthy: z.boolean().describe('服务是否健康') })),
+});
+const SystemInfoSchema = routerSchema({
+    operationId: 'getSystemInfo',
+    summary: '获取系统信息',
+    tags: ['系统'],
+    description: '获取系统版本、运行时配置等信息（无需认证）',
+    response: responseEnvelopeSchema(z.object({
+        version: z
+            .object({
+            app: z.string().describe('应用版本'),
+            name: z.string().describe('应用名称（`identity.service`）'),
+            title: z.string().describe('应用标题（`identity.title`）'),
+            node: z.string().describe('Node.js 版本'),
+            platform: z.string().describe('运行平台'),
+            buildTime: z.string().optional().describe('构建时间'),
+            gitCommit: z.string().optional().describe('Git 提交哈希'),
+        })
+            .describe('版本信息'),
+        runtime: z
+            .object({
+            serverUrl: z.string().nullable().describe('服务公网地址'),
+            cookieNames: z
+                .array(z.string())
+                .describe('Cookie 名称列表（取自已加载配置的 `server.cookieNames`）'),
+        })
+            .describe('运行时配置'),
+    })),
+});
+function readStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : undefined;
+}
+/** 遍历 services 的可选 `health()`：任一失败 / 非 `true` → false */
+async function checkHealth(services) {
+    for (const service of Object.values(services)) {
+        const health = service?.health;
+        if (typeof health !== 'function') {
+            continue;
+        }
+        const result = await catchIt(health());
+        if (result.isError()) {
+            return false;
+        }
+        if (result.value !== true) {
+            return false;
+        }
+    }
+    return true;
+}
+/** `/health` 与 `/system/health` 的共用处理器：不健康则抛 `UNKNOWN_ERROR`（k8s probe 依赖 5xx） */
+async function assertHealthy(services) {
+    const result = await catchIt(checkHealth(services));
+    const ok = result.isError() ? false : result.value;
+    if (!ok) {
+        throw new SystemError('UNKNOWN_ERROR', {
+            operation: 'healthCheck',
+            cause: result.isError() ? result.error : 'Service health check failed',
+        });
+    }
+}
+/** `GET /system/openapi` 的路由元信息 */
+const OpenApiSpecSchema = routerSchema({
+    operationId: 'getOpenApiDocument',
+    summary: '获取 OpenAPI 文档',
+    tags: ['系统'],
+    description: '返回本服务的 OpenAPI 文档（无需认证，原样返回、不套响应信封）',
+});
+/**
+ * 注册框架内置系统路由（5 个端点）。由 `registerSystemRoutesStep` 在 `server.routers(...)` **之前**调用，
+ * 保证框架路由先就位。
+ */
+export function registerSystemRoutes(app, options) {
+    const { identity, services, readConfig } = options;
+    // GET / —— 服务可用性（服务名取自身份块）
+    app.get('/', { config: { accessControls: ['NoLoginRequired'] }, schema: RootSchema }, async () => {
+        return createSuccessResponse(identity.service);
+    });
+    // GET /health —— k8s probe（保持 GET，NoLoginRequired）
+    app.get('/health', { config: { accessControls: ['NoLoginRequired'] }, schema: HealthCheckSchema }, async () => {
+        await assertHealthy(services);
+        return createSuccessResponse({ healthy: true });
+    });
+    // POST /system/health —— API 版健康检查
+    app.post('/system/health', { schema: SystemHealthCheckSchema }, async () => {
+        await assertHealthy(services);
+        return createSuccessResponse({ healthy: true });
+    });
+    // GET /system/openapi —— OpenAPI 文档出口（NoLoginRequired）
+    //
+    // **原样返回、不套信封**：文档是机器可读契约（各仓 `api-gen` / `openapi-ts` 直接消费），
+    // 包一层 `{ status, message, data }` 就不再是合法 OpenAPI 文档。
+    // 实现上返回**已序列化的 JSON 字符串**：Fastify 对 `string` payload 不触发
+    // `preSerialization`，`core/response` 的统一信封因而不会介入；`content-type` 显式设为
+    // `application/json` 保证客户端按 JSON 解析。
+    app.get('/system/openapi', { config: { accessControls: ['NoLoginRequired'] }, schema: OpenApiSpecSchema }, async (_request, reply) => {
+        const document = app.swagger();
+        return reply.type('application/json').send(JSON.stringify(document));
+    });
+    // POST /system/info —— 版本 + 运行时（请求期现读配置）
+    //
+    // ⚠️ **这是公开接口**（不含 `admin` 等内部配置）：任何从这里出去的字段都等于公开。
+    // 管理员用户名 / 内部账号列表这类信息**永远不返回**——它是撞库与提权的直接输入，
+    // 不是「运行时信息」。需要排查管理员配置走运维通道（日志 / 数据库），不走 HTTP。
+    //
+    // `NoLoginRequired` 与「它是公开接口」是同一件事的两半，必须成对声明：少了这一行，
+    // auth 中间件会把探活 / 版本查询挡成 400，客户端与探针都拿不到运行时信息。
+    app.post('/system/info', { config: { accessControls: ['NoLoginRequired'] }, schema: SystemInfoSchema }, async () => {
+        const server = readConfig('server');
+        return createSuccessResponse({
+            version: {
+                app: identity.version,
+                name: identity.service,
+                title: identity.title,
+                node: process.version,
+                platform: process.platform,
+                buildTime: process.env.BUILD_TIME,
+                gitCommit: process.env.GIT_COMMIT,
+            },
+            runtime: {
+                serverUrl: server?.url ?? server?.serverUrl ?? null,
+                cookieNames: readStringArray(server?.cookieNames) ?? [],
+            },
+        });
+    });
+}

package/output/core/resource.d.ts

@@ -0,0 +1,56 @@
+import type { ResourceLifecycle, ResourceUnit } from './types.js';
+/**
+ * 构造资源单元（唯一的正当方式）。
+ *
+ * ## 为什么需要外壳
+ *
+ * 资源多是**第三方对象**：`PrismaClient`、Redis client、HTTP 连接池⋯⋯它们的形状改不了。
+ * service 可以直接在对象上挂 `init()`（因为 service 是本仓自己写的），资源不行——
+ * `prisma.setup = …` 是在改别人的类型，运行期也未必允许。
+ *
+ * 所以 `setup()` 挂在**框架私有外壳**上，`value` 原样保留：
+ *
+ * ```ts
+ * resources: (ctx) => ({
+ *   database: defineResource(createPrisma(ctx.env.DATABASE_URL), {
+ *     async setup() { await pushSchema(ctx.env.DATABASE_URL) },
+ *   }),
+ * })
+ * ```
+ *
+ * 消费方读 `ctx.resources.database` 拿到的是 `PrismaClient` 本身
+ * （`ResourcesView` 会解包），不是 `ResourceUnit<PrismaClient>`。
+ *
+ * ## 单元是可选的
+ *
+ * 裸对象照旧可用（无 `setup`、无解包开销）：`resources: () => ({ database: prisma })`。
+ * 只有需要「装配期准备」的资源才包一层。
+ *
+ * ## `setup` 何时跑、谁跑
+ *
+ * - **何时**：`resources` 槽位构造完成后、`config` 槽位之前；按**对象声明序**逐项 `await`。
+ *   排在 `config` 前是硬要求——`config` 常从数据库读（如 `SystemConfig` 表），库没准备好
+ *   它就连不上。
+ * - **谁**：框架。`startServer` / `createTestServer` 都调；`generateOpenApi` 不调
+ *   （出 spec 不构造资源）。应用**永不手调**。
+ * - **失败**：立即中断装配并把错误抛给入口（已构造的资源照常释放）。资源准备失败后
+ *   `config` / `services` 都没有意义，所以不吞。
+ *
+ * ## 不要在里面写 `if (ENV === 'test')`
+ *
+ * 准备动作本身应当是**状态驱动**的：`prisma db push` / `migrate deploy` 都会自己比对现状、
+ * 只补差量，生产与测试跑同一份代码。需要区分环境的细节应当从 `ctx.env` 取，而不是让
+ * 「跑不跑这个函数」变成环境分支。
+ *
+ * ## 用例间重置不在本文件
+ *
+ * 「清表 / 清缓存 / 重新插入样本数据」不适合挂在资源上：资源只知道有哪些表、哪些 key，
+ * 不知道**谁往里写了什么**。写在资源上就变成了「新增一个 model 就得回去改一次清库清单」，
+ * 漏改只会安静地变脏。
+ *
+ * 所以它单独成机制：**`packages/server/testdata/*.ts|js`，每个脚本自带 `load()` / `cleanup()`**，
+ * 由框架在 `development` / `test` 下自动装载并执行（见 `core/test-support/testdata.ts`）。
+ * 数据脚本自己知道要插入什么，也就自己知道怎么删干净。
+ */
+export declare function defineResource<Value>(value: Value, lifecycle?: ResourceLifecycle): ResourceUnit<Value>;
+//# sourceMappingURL=resource.d.ts.map

package/output/core/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../source/core/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,iBAAiB,GAAG,YAAY,CAAC,KAAK,CAAC,CAEtG"}

package/output/core/resource.js

@@ -0,0 +1,56 @@
+/**
+ * 构造资源单元（唯一的正当方式）。
+ *
+ * ## 为什么需要外壳
+ *
+ * 资源多是**第三方对象**：`PrismaClient`、Redis client、HTTP 连接池⋯⋯它们的形状改不了。
+ * service 可以直接在对象上挂 `init()`（因为 service 是本仓自己写的），资源不行——
+ * `prisma.setup = …` 是在改别人的类型，运行期也未必允许。
+ *
+ * 所以 `setup()` 挂在**框架私有外壳**上，`value` 原样保留：
+ *
+ * ```ts
+ * resources: (ctx) => ({
+ *   database: defineResource(createPrisma(ctx.env.DATABASE_URL), {
+ *     async setup() { await pushSchema(ctx.env.DATABASE_URL) },
+ *   }),
+ * })
+ * ```
+ *
+ * 消费方读 `ctx.resources.database` 拿到的是 `PrismaClient` 本身
+ * （`ResourcesView` 会解包），不是 `ResourceUnit<PrismaClient>`。
+ *
+ * ## 单元是可选的
+ *
+ * 裸对象照旧可用（无 `setup`、无解包开销）：`resources: () => ({ database: prisma })`。
+ * 只有需要「装配期准备」的资源才包一层。
+ *
+ * ## `setup` 何时跑、谁跑
+ *
+ * - **何时**：`resources` 槽位构造完成后、`config` 槽位之前；按**对象声明序**逐项 `await`。
+ *   排在 `config` 前是硬要求——`config` 常从数据库读（如 `SystemConfig` 表），库没准备好
+ *   它就连不上。
+ * - **谁**：框架。`startServer` / `createTestServer` 都调；`generateOpenApi` 不调
+ *   （出 spec 不构造资源）。应用**永不手调**。
+ * - **失败**：立即中断装配并把错误抛给入口（已构造的资源照常释放）。资源准备失败后
+ *   `config` / `services` 都没有意义，所以不吞。
+ *
+ * ## 不要在里面写 `if (ENV === 'test')`
+ *
+ * 准备动作本身应当是**状态驱动**的：`prisma db push` / `migrate deploy` 都会自己比对现状、
+ * 只补差量，生产与测试跑同一份代码。需要区分环境的细节应当从 `ctx.env` 取，而不是让
+ * 「跑不跑这个函数」变成环境分支。
+ *
+ * ## 用例间重置不在本文件
+ *
+ * 「清表 / 清缓存 / 重新插入样本数据」不适合挂在资源上：资源只知道有哪些表、哪些 key，
+ * 不知道**谁往里写了什么**。写在资源上就变成了「新增一个 model 就得回去改一次清库清单」，
+ * 漏改只会安静地变脏。
+ *
+ * 所以它单独成机制：**`packages/server/testdata/*.ts|js`，每个脚本自带 `load()` / `cleanup()`**，
+ * 由框架在 `development` / `test` 下自动装载并执行（见 `core/test-support/testdata.ts`）。
+ * 数据脚本自己知道要插入什么，也就自己知道怎么删干净。
+ */
+export function defineResource(value, lifecycle) {
+    return lifecycle ? { value, ...lifecycle } : { value };
+}

package/output/core/test-support/database.d.ts

@@ -0,0 +1,89 @@
+/**
+ * 测试数据库安全检查（强制规则见 `@taicode/skills` 的 `test-database-isolation`）。
+ *
+ * 两道闸门，缺一不可：
+ *
+ * | 闸门 | 拒绝条件 | 缺失后的后果 |
+ * | --- | --- | --- |
+ * | 环境闸门 | `ENV` 不是可清理环境 | 生产 runner 上误跑破坏性测试 |
+ * | schema 闸门 | 目标 schema 不以 `_test` 结尾 | 绕过命名约定后仍能同步 / 清理应用 schema |
+ *
+ * 不需要「应用目标 vs 测试目标」比对：测试目标只由 `DATABASE_URL` **派生**得到（schema
+ * 追加 `_test`，幂等），再由 schema 闸门只放行 `*_test`。两条合起来，测试目标结构上不可能
+ * 是应用目标；再拿两个连接串互相比较，比的也只是同一份派生结果。
+ *
+ * ## 为什么在框架里
+ *
+ * 这套逻辑此前在 `account` / `expense` / `release` / `observai` 各写一遍，互相抄、互相漂移。
+ * 它保护的是**数据不丢**，属于「项目可以决定怎么实现，但不能决定要不要实现」的那类规则——
+ * 所以实现只能有一份，由框架提供；各仓的 `vitest.config.ts` / `global-setup.ts` 只调用，不复制。
+ *
+ * ## 为什么用 `throw` 而不是 `process.exit`
+ *
+ * 本模块被两类进程共用：
+ *
+ * - `createTestServer`（vitest worker 内）：退出码由 vitest 决定，抛错即该文件失败；
+ * - `vitest.config.ts` / `global-setup.ts`（配置与全局初始化）：抛错同样以非零状态结束进程。
+ *
+ * 抛错在两处都能得到「立刻失败」，而 `process.exit(1)` 在 worker 内会杀掉整个进程池、
+ * 丢掉其余文件的报告。错误信息本身必须足够定位，不能靠退出码表达。
+ */
+/** 测试 schema 的强制后缀（`account` → `account_test`） */
+export declare const TEST_SCHEMA_SUFFIX = "_test";
+/**
+ * 一个连接串的**全部**连接维度。
+ *
+ * 比较必须覆盖四个维度：只比字符串会误判（`localhost:5432` 与 `localhost:5432/` 不同、
+ * `?schema=` 与默认端口都能让「不同字符串」指向同一 schema）。
+ */
+export interface DatabaseTarget {
+    hostname: string;
+    /** 已按默认端口补齐 */
+    port: string;
+    /** 路径部分（不含开头的 `/`） */
+    database: string;
+    /** `?schema=`，缺省 `public` */
+    schema: string;
+}
+/** 解析连接串的连接维度（解析失败即抛错：配置错误不该被当成「不同的目标」放过去） */
+export declare function resolveDatabaseTarget(connectionString: string): DatabaseTarget;
+/**
+ * 打印用的连接串（**密码一律替换为 `***`**）。
+ *
+ * 报错要能定位「连的是哪儿」，但不能把密码写进 CI 日志。
+ */
+export declare function maskDatabaseUrl(connectionString: string): string;
+/**
+ * 由应用连接串派生测试连接串：只改 schema，`host` / `port` / `database` 保持与应用一致。
+ *
+ * 派生是**幂等**的（`account` → `account_test`，`account_test` → `account_test`），
+ * 这样重复调用不会产生 `account_test_test`。
+ *
+ * 应用 schema 本身就以 `_test` 结尾时**直接拒绝**：此时派生结果与应用目标完全相同，测试会
+ * 清空应用数据。这是唯一需要「应用目标」才能发现的情况，所以把它固化成派生的一步——不需要
+ * 调用方额外传应用连接串、也不需要另开一道闸门。
+ */
+export declare function deriveTestDatabaseUrl(appDatabaseUrl: string): string;
+/** 环境闸门（实现在 `core/env.ts`，这里**只转出**：判定只有一份） */
+export { CLEANABLE_ENVS, assertCleanableEnvironment } from '../env.js';
+/** schema 闸门：目标 schema 必须以 `_test` 结尾（在**任何**同步 / 迁移 / 清理之前执行） */
+export declare function assertTestDatabaseSchema(testDatabaseUrl: string): void;
+/** `resolveTestDatabase()` 入参 */
+export interface TestDatabaseResolutionOptions {
+    /** 环境标记（`ENV`）；非可清理环境直接拒绝 */
+    env: string;
+    /** 显式测试连接串（`TEST_DATABASE_URL`）；优先级最高 */
+    testDatabaseUrl?: string;
+}
+/**
+ * 结算测试连接串，并**顺序**跑两道闸门：环境 → schema 命名。
+ *
+ * 顺序是刻意的：环境闸门决定「这台机器能不能做破坏性操作」，schema 闸门决定「目标名字是否
+ * 表示测试库」。
+ *
+ * 派生规则：显式 `testDatabaseUrl` 优先；否则由 `process.env.DATABASE_URL` 派生（schema
+ * 追加 `_test`，**幂等**）；两者都没有即拒绝——「猜一个连接串」在会清理数据的场景里不可接受。
+ */
+export declare function resolveTestDatabase(options: TestDatabaseResolutionOptions): string;
+export declare function parseConnectionString(connectionString: string): URL;
+//# sourceMappingURL=database.d.ts.map

package/output/core/test-support/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,UAAU,CAAA;AAQzC;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,eAAe;IACf,IAAI,EAAE,MAAM,CAAA;IACZ,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,6BAA6B;IAC7B,MAAM,EAAE,MAAM,CAAA;CACf;AAED,8CAA8C;AAC9C,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,cAAc,CAS9E;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,gBAAgB,EAAE,MAAM,GAAG,MAAM,CAShE;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAcpE;AAED,+CAA+C;AAC/C,OAAO,EAAE,cAAc,EAAE,0BAA0B,EAAE,MAAM,WAAW,CAAA;AACtE,kEAAkE;AAClE,wBAAgB,wBAAwB,CAAC,eAAe,EAAE,MAAM,GAAG,IAAI,CAUtE;AAED,iCAAiC;AACjC,MAAM,WAAW,6BAA6B;IAC5C,6BAA6B;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,6BAA6B,GAAG,MAAM,CAiBlF;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,GAAG,GAAG,CASnE"}

package/output/core/test-support/database.js

@@ -0,0 +1,131 @@
+/**
+ * 测试数据库安全检查（强制规则见 `@taicode/skills` 的 `test-database-isolation`）。
+ *
+ * 两道闸门，缺一不可：
+ *
+ * | 闸门 | 拒绝条件 | 缺失后的后果 |
+ * | --- | --- | --- |
+ * | 环境闸门 | `ENV` 不是可清理环境 | 生产 runner 上误跑破坏性测试 |
+ * | schema 闸门 | 目标 schema 不以 `_test` 结尾 | 绕过命名约定后仍能同步 / 清理应用 schema |
+ *
+ * 不需要「应用目标 vs 测试目标」比对：测试目标只由 `DATABASE_URL` **派生**得到（schema
+ * 追加 `_test`，幂等），再由 schema 闸门只放行 `*_test`。两条合起来，测试目标结构上不可能
+ * 是应用目标；再拿两个连接串互相比较，比的也只是同一份派生结果。
+ *
+ * ## 为什么在框架里
+ *
+ * 这套逻辑此前在 `account` / `expense` / `release` / `observai` 各写一遍，互相抄、互相漂移。
+ * 它保护的是**数据不丢**，属于「项目可以决定怎么实现，但不能决定要不要实现」的那类规则——
+ * 所以实现只能有一份，由框架提供；各仓的 `vitest.config.ts` / `global-setup.ts` 只调用，不复制。
+ *
+ * ## 为什么用 `throw` 而不是 `process.exit`
+ *
+ * 本模块被两类进程共用：
+ *
+ * - `createTestServer`（vitest worker 内）：退出码由 vitest 决定，抛错即该文件失败；
+ * - `vitest.config.ts` / `global-setup.ts`（配置与全局初始化）：抛错同样以非零状态结束进程。
+ *
+ * 抛错在两处都能得到「立刻失败」，而 `process.exit(1)` 在 worker 内会杀掉整个进程池、
+ * 丢掉其余文件的报告。错误信息本身必须足够定位，不能靠退出码表达。
+ */
+import { assertCleanableEnvironment } from '../env.js';
+/** 测试 schema 的强制后缀（`account` → `account_test`） */
+export const TEST_SCHEMA_SUFFIX = '_test';
+/** 连接串未写端口时按协议默认端口补齐后再比较（PostgreSQL 默认 5432） */
+const DEFAULT_POSTGRES_PORT = '5432';
+/** 连接串未写 `?schema=` 时的实际 schema（PostgreSQL 默认 `public`） */
+const DEFAULT_DATABASE_SCHEMA = 'public';
+/** 解析连接串的连接维度（解析失败即抛错：配置错误不该被当成「不同的目标」放过去） */
+export function resolveDatabaseTarget(connectionString) {
+    const parsed = parseConnectionString(connectionString);
+    return {
+        hostname: parsed.hostname,
+        port: parsed.port || DEFAULT_POSTGRES_PORT,
+        database: parsed.pathname.replace(/^\//, ''),
+        schema: parsed.searchParams.get('schema') ?? DEFAULT_DATABASE_SCHEMA,
+    };
+}
+/**
+ * 打印用的连接串（**密码一律替换为 `***`**）。
+ *
+ * 报错要能定位「连的是哪儿」，但不能把密码写进 CI 日志。
+ */
+export function maskDatabaseUrl(connectionString) {
+    const parsed = tryParseConnectionString(connectionString);
+    if (!parsed) {
+        return '<无法解析的连接串>';
+    }
+    if (parsed.password) {
+        parsed.password = '***';
+    }
+    return parsed.toString();
+}
+/**
+ * 由应用连接串派生测试连接串：只改 schema，`host` / `port` / `database` 保持与应用一致。
+ *
+ * 派生是**幂等**的（`account` → `account_test`，`account_test` → `account_test`），
+ * 这样重复调用不会产生 `account_test_test`。
+ *
+ * 应用 schema 本身就以 `_test` 结尾时**直接拒绝**：此时派生结果与应用目标完全相同，测试会
+ * 清空应用数据。这是唯一需要「应用目标」才能发现的情况，所以把它固化成派生的一步——不需要
+ * 调用方额外传应用连接串、也不需要另开一道闸门。
+ */
+export function deriveTestDatabaseUrl(appDatabaseUrl) {
+    const parsed = parseConnectionString(appDatabaseUrl);
+    const schema = parsed.searchParams.get('schema') ?? DEFAULT_DATABASE_SCHEMA;
+    if (schema.endsWith(TEST_SCHEMA_SUFFIX)) {
+        throw new Error(`[test-database] 应用连接串的 schema 已是 "${schema}"（以 ${TEST_SCHEMA_SUFFIX} 结尾），` +
+            `派生出的测试目标会与应用目标完全相同（${maskDatabaseUrl(appDatabaseUrl)}）。` +
+            '应用运行时 schema 绝不能以 _test 结尾：请修正 DATABASE_URL，而不是放宽守卫。');
+    }
+    parsed.searchParams.set('schema', `${schema}${TEST_SCHEMA_SUFFIX}`);
+    return parsed.toString();
+}
+/** 环境闸门（实现在 `core/env.ts`，这里**只转出**：判定只有一份） */
+export { CLEANABLE_ENVS, assertCleanableEnvironment } from '../env.js';
+/** schema 闸门：目标 schema 必须以 `_test` 结尾（在**任何**同步 / 迁移 / 清理之前执行） */
+export function assertTestDatabaseSchema(testDatabaseUrl) {
+    const { schema } = resolveDatabaseTarget(testDatabaseUrl);
+    if (schema.endsWith(TEST_SCHEMA_SUFFIX)) {
+        return;
+    }
+    throw new Error(`[test-database] 拒绝使用 schema "${schema}"：测试 schema 必须以 ${TEST_SCHEMA_SUFFIX} 结尾` +
+        `（当前目标 ${maskDatabaseUrl(testDatabaseUrl)}）。`);
+}
+/**
+ * 结算测试连接串，并**顺序**跑两道闸门：环境 → schema 命名。
+ *
+ * 顺序是刻意的：环境闸门决定「这台机器能不能做破坏性操作」，schema 闸门决定「目标名字是否
+ * 表示测试库」。
+ *
+ * 派生规则：显式 `testDatabaseUrl` 优先；否则由 `process.env.DATABASE_URL` 派生（schema
+ * 追加 `_test`，**幂等**）；两者都没有即拒绝——「猜一个连接串」在会清理数据的场景里不可接受。
+ */
+export function resolveTestDatabase(options) {
+    assertCleanableEnvironment(options.env);
+    const explicit = options.testDatabaseUrl || process.env.TEST_DATABASE_URL;
+    const base = process.env.DATABASE_URL;
+    const testDatabaseUrl = explicit || (base ? deriveTestDatabaseUrl(base) : '');
+    if (!testDatabaseUrl) {
+        throw new Error('[test-database] 无法确定测试连接串：TEST_DATABASE_URL 与 DATABASE_URL 都为空。' +
+            '会清理数据库的测试必须显式指向一个独立的 *_test schema。');
+    }
+    assertTestDatabaseSchema(testDatabaseUrl);
+    return testDatabaseUrl;
+}
+export function parseConnectionString(connectionString) {
+    const parsed = tryParseConnectionString(connectionString);
+    if (!parsed) {
+        throw new Error(`[test-database] 无法解析连接串 "${connectionString}"：测试连接目标必须可读，` +
+            '否则无法安全地派生 / 校验。检查 DATABASE_URL / TEST_DATABASE_URL 是否为合法 URL。');
+    }
+    return parsed;
+}
+function tryParseConnectionString(connectionString) {
+    try {
+        return new URL(connectionString);
+    }
+    catch {
+        return null;
+    }
+}

package/output/core/test-support/database.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.test.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/database.test.ts"],"names":[],"mappings":""}

package/output/core/test-support/database.test.js

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, it } from 'vitest';
+import { CLEANABLE_ENVS, assertCleanableEnvironment } from '../env.js';
+import { assertTestDatabaseSchema, deriveTestDatabaseUrl, maskDatabaseUrl, resolveDatabaseTarget, resolveTestDatabase, } from './database.js';
+/** 稳定的测试夹具（含密码，用于验证脱敏） */
+const APP_URL = 'postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=account';
+/** 每个用例自行还原 env（`resolveTestDatabase` 会读 `process.env` 作为兜底） */
+const ORIGINAL_ENV = { ...process.env };
+afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+});
+describe('resolveDatabaseTarget', () => {
+    it('解析出四个连接维度（端口与 schema 按协议默认值补齐）', () => {
+        expect(resolveDatabaseTarget(APP_URL)).toEqual({
+            hostname: 'db.internal',
+            port: '5432',
+            database: 'taicode-labs',
+            schema: 'account',
+        });
+    });
+    it('未写端口时按 5432 补齐（否则 localhost 与 localhost:5432 会被误判为不同目标）', () => {
+        expect(resolveDatabaseTarget('postgresql://postgres@localhost/db').port).toBe('5432');
+    });
+    it('未写 schema 时按 public 补齐', () => {
+        expect(resolveDatabaseTarget('postgresql://postgres@localhost/db').schema).toBe('public');
+    });
+    it('连接串无法解析即抛错（不能把解析失败当成「不同的目标」放过去）', () => {
+        expect(() => resolveDatabaseTarget('not-a-url')).toThrow(/无法解析连接串/);
+    });
+});
+describe('deriveTestDatabaseUrl', () => {
+    it('只改 schema，host / port / database 保持与应用完全一致', () => {
+        const derived = resolveDatabaseTarget(deriveTestDatabaseUrl(APP_URL));
+        expect(derived).toEqual({
+            hostname: 'db.internal',
+            port: '5432',
+            database: 'taicode-labs',
+            schema: 'account_test',
+        });
+    });
+    it('应用 schema 已以 _test 结尾时拒绝：派生结果会与应用目标完全相同', () => {
+        // 这是唯一需要「应用目标」才能发现的情况，因此固化成派生的一步。
+        expect(() => deriveTestDatabaseUrl('postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=account_test')).toThrow(/派生出的测试目标会与应用目标完全相同/);
+    });
+    it('保留密码与查询参数里的其它键', () => {
+        const derived = new URL(deriveTestDatabaseUrl(`${APP_URL}&sslmode=require`));
+        expect(derived.password).toBe('secret');
+        expect(derived.searchParams.get('sslmode')).toBe('require');
+    });
+});
+describe('maskDatabaseUrl', () => {
+    it('隐藏密码（报错要能定位目标，但不能把密码写进 CI 日志）', () => {
+        const masked = maskDatabaseUrl(APP_URL);
+        expect(masked).not.toContain('secret');
+        expect(masked).toContain('***');
+        expect(masked).toContain('db.internal');
+    });
+    it('无法解析时给出占位而不是抛错（它只用于报错信息）', () => {
+        expect(maskDatabaseUrl('not-a-url')).toBe('<无法解析的连接串>');
+    });
+});
+describe('assertCleanableEnvironment（环境闸门）', () => {
+    it.each(CLEANABLE_ENVS)('放行可清理环境 %s', (env) => {
+        expect(() => assertCleanableEnvironment(env)).not.toThrow();
+    });
+    it('拒绝生产环境，并在错误里写明当前值与可接受值', () => {
+        expect(() => assertCleanableEnvironment('production')).toThrow(/ENV="production"/);
+    });
+    it('拒绝未设置的空值（默认放行等于把守卫关掉）', () => {
+        expect(() => assertCleanableEnvironment('')).toThrow(/<未设置>/);
+    });
+});
+describe('assertTestDatabaseSchema（schema 闸门）', () => {
+    it('放行 *_test', () => {
+        expect(() => assertTestDatabaseSchema('postgresql://postgres@localhost/db?schema=account_test')).not.toThrow();
+    });
+    it('拒绝非 *_test（在同步 / 迁移 / 清理之前就失败）', () => {
+        expect(() => assertTestDatabaseSchema(APP_URL)).toThrow(/account/);
+    });
+});
+describe('resolveTestDatabase（两道闸门串联 + 派生）', () => {
+    it('无任何变量时拒绝（猜测连接串在会清理数据的场景里不可接受）', () => {
+        delete process.env.DATABASE_URL;
+        delete process.env.TEST_DATABASE_URL;
+        expect(() => resolveTestDatabase({ env: 'development' })).toThrow(/无法确定测试连接串/);
+    });
+    it('显式 TEST_DATABASE_URL 优先于派生', () => {
+        process.env.DATABASE_URL = APP_URL;
+        process.env.TEST_DATABASE_URL = 'postgresql://postgres:secret@db.internal:5432/taicode-labs?schema=explicit_test';
+        expect(resolveTestDatabase({ env: 'development' })).toContain('explicit_test');
+    });
+    it('没有显式变量时由 DATABASE_URL 派生', () => {
+        process.env.DATABASE_URL = APP_URL;
+        delete process.env.TEST_DATABASE_URL;
+        expect(resolveDatabaseTarget(resolveTestDatabase({ env: 'development' })).schema).toBe('account_test');
+    });
+    it('顺序：环境闸门先于 schema 闸门（生产环境下不先抱怨 schema 名）', () => {
+        process.env.TEST_DATABASE_URL = APP_URL;
+        expect(() => resolveTestDatabase({ env: 'production' })).toThrow(/拒绝在 ENV="production"/);
+    });
+    it('通过闸门后返回可用的测试连接串', () => {
+        process.env.DATABASE_URL = APP_URL;
+        delete process.env.TEST_DATABASE_URL;
+        const resolved = resolveTestDatabase({ env: 'development' });
+        expect(resolveDatabaseTarget(resolved)).toEqual({
+            hostname: 'db.internal',
+            port: '5432',
+            database: 'taicode-labs',
+            schema: 'account_test',
+        });
+    });
+});