@taicode/common-server 4.0.0-beta.4 → 4.0.0-beta.6

package/output/core/env.js

@@ -29,6 +29,34 @@ const ENV_FILE_LAYERS = ['.env.dev', '.env', '.env.local'];
 const TEST_ENV_FILE_LAYERS = ['.env.test', '.env.test.local'];
 /** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
 export const DEFAULT_LOG_LEVEL = 'info';
+/**
+ * 允许执行**破坏性 / 不可逆**操作的环境（`ENV` 取值）。
+ *
+ * 覆盖两类动作，两者共用同一份判定：
+ *
+ * - 测试数据库清理（`assertTestDatabaseSchema` 那道闸门的同伴）；
+ * - `testdata/` 脚本的 `load()` / `cleanup()`（`test-support/testdata.ts`）。
+ *
+ * `development` 是本地开发，`test` 是 vitest 入口显式声明的环境开关。除此之外一律拒绝——
+ * 只看 `NODE_ENV`、CI 标志或变量名都不构成证明：`NODE_ENV=test` 完全可能连着生产库。
+ */
+export const CLEANABLE_ENVS = ['development', 'test'];
+/**
+ * 环境闸门：非可清理环境立即失败。
+ *
+ * **不在分支里「跳过清理」**——把破坏性动作降级成静默 no-op，会让同一份代码在生产和测试里
+ * 走两条不同的路径，测试结果随即失去意义。要禁就整体失败。
+ *
+ * 报错必须带上当前值：漏配 `ENV` 时的症状否则会变成「莫名其妙不许跑」。
+ */
+export function assertCleanableEnvironment(env) {
+    if (CLEANABLE_ENVS.includes(env)) {
+        return;
+    }
+    throw new Error(`[env-gate] 拒绝在 ENV="${env || '<未设置>'}" 下执行会清理数据的操作：` +
+        `只接受 ${CLEANABLE_ENVS.join(' / ')}。` +
+        '会写入 / 清理 / truncate / reset 数据库的操作绝不能指向非开发环境。');
+}
 /**
  * 首次 import 时的真实环境变量快照（此时还没有任何 .env 文件被加载）。
  * 加载结束后原样恢复，实现「外部注入 > .env.local > .env > .env.dev」。

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

@@ -30,13 +30,6 @@
  */
 /** 测试 schema 的强制后缀（`account` → `account_test`） */
 export declare const TEST_SCHEMA_SUFFIX = "_test";
-/**
- * 允许运行「会清理数据库」的测试的环境（`ENV` 取值）。
- *
- * `development` 是本地开发，`test` 是 vitest 入口显式声明的环境开关。除此之外一律拒绝——
- * 只看 `NODE_ENV`、CI 标志或变量名都不构成证明：`NODE_ENV=test` 完全可能连着生产库。
- */
-export declare const CLEANABLE_ENVS: readonly string[];
 /**
  * 一个连接串的**全部**连接维度。
  *
@@ -71,8 +64,8 @@ export declare function maskDatabaseUrl(connectionString: string): string;
  * 调用方额外传应用连接串、也不需要另开一道闸门。
  */
 export declare function deriveTestDatabaseUrl(appDatabaseUrl: string): string;
-/** 环境闸门：非可清理环境立即失败（不在分支里「跳过清理」——那会让结果不可重复） */
-export declare function assertCleanableEnvironment(env: string): void;
+/** 环境闸门（实现在 `core/env.ts`，这里**只转出**：判定只有一份） */
+export { CLEANABLE_ENVS, assertCleanableEnvironment } from '../env.js';
 /** schema 闸门：目标 schema 必须以 `_test` 结尾（在**任何**同步 / 迁移 / 清理之前执行） */
 export declare function assertTestDatabaseSchema(testDatabaseUrl: string): void;
 /** `resolveTestDatabase()` 入参 */

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

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,kDAAkD;AAClD,eAAO,MAAM,kBAAkB,UAAU,CAAA;AAEzC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,SAAS,MAAM,EAA4B,CAAA;AAQxE;;;;;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,8CAA8C;AAC9C,wBAAgB,0BAA0B,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAU5D;AAED,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"}
+{"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

@@ -28,15 +28,9 @@
  * 抛错在两处都能得到「立刻失败」，而 `process.exit(1)` 在 worker 内会杀掉整个进程池、
  * 丢掉其余文件的报告。错误信息本身必须足够定位，不能靠退出码表达。
  */
+import { assertCleanableEnvironment } from '../env.js';
 /** 测试 schema 的强制后缀（`account` → `account_test`） */
 export const TEST_SCHEMA_SUFFIX = '_test';
-/**
- * 允许运行「会清理数据库」的测试的环境（`ENV` 取值）。
- *
- * `development` 是本地开发，`test` 是 vitest 入口显式声明的环境开关。除此之外一律拒绝——
- * 只看 `NODE_ENV`、CI 标志或变量名都不构成证明：`NODE_ENV=test` 完全可能连着生产库。
- */
-export const CLEANABLE_ENVS = ['development', 'test'];
 /** 连接串未写端口时按协议默认端口补齐后再比较（PostgreSQL 默认 5432） */
 const DEFAULT_POSTGRES_PORT = '5432';
 /** 连接串未写 `?schema=` 时的实际 schema（PostgreSQL 默认 `public`） */
@@ -87,15 +81,8 @@ export function deriveTestDatabaseUrl(appDatabaseUrl) {
     parsed.searchParams.set('schema', `${schema}${TEST_SCHEMA_SUFFIX}`);
     return parsed.toString();
 }
-/** 环境闸门：非可清理环境立即失败（不在分支里「跳过清理」——那会让结果不可重复） */
-export function assertCleanableEnvironment(env) {
-    if (CLEANABLE_ENVS.includes(env)) {
-        return;
-    }
-    throw new Error(`[test-database] 拒绝在 ENV="${env || '<未设置>'}" 下运行会清理数据库的测试：` +
-        `只接受 ${CLEANABLE_ENVS.join(' / ')}。` +
-        '会写入 / 清理 / truncate / reset 数据库的测试绝不能指向非开发环境。');
-}
+/** 环境闸门（实现在 `core/env.ts`，这里**只转出**：判定只有一份） */
+export { CLEANABLE_ENVS, assertCleanableEnvironment } from '../env.js';
 /** schema 闸门：目标 schema 必须以 `_test` 结尾（在**任何**同步 / 迁移 / 清理之前执行） */
 export function assertTestDatabaseSchema(testDatabaseUrl) {
     const { schema } = resolveDatabaseTarget(testDatabaseUrl);

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

@@ -1,5 +1,6 @@
 import { afterEach, describe, expect, it } from 'vitest';
-import { CLEANABLE_ENVS, assertCleanableEnvironment, assertTestDatabaseSchema, deriveTestDatabaseUrl, maskDatabaseUrl, resolveDatabaseTarget, resolveTestDatabase, } from './database.js';
+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` 作为兜底） */

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

@@ -11,7 +11,7 @@ import type { ConfigEnv } from '../env.js';
  */
 export declare function loadRuntimeEnvironment(): ConfigEnv;
 /**
- * 结算**测试**数据库目标：加载测试层 → 闸门 → 结算 → 回写 `process.env.DATABASE_URL`。
+ * 结算**测试**数据库目标：加载测试层 → 闸门 → 结算 → 把测试连接串注入返回的 env 快照。
  *
  * **`createTestServer` 的私有步骤，不对外导出。** 导出它等于让调用方自己决定「什么时候跑
  * 闸门、按什么顺序」，而顺序本身就是安全前提。
@@ -22,10 +22,15 @@ export declare function loadRuntimeEnvironment(): ConfigEnv;
  *   → 环境闸门（ENV 必须可清理）
  *   → 结算（显式 TEST_DATABASE_URL 优先，否则由 DATABASE_URL 派生 +_test，幂等）
  *   → schema 闸门（必须以 _test 结尾）
- *   → 回写 process.env.DATABASE_URL
+ *   → 把测试连接串写进**返回的 env 快照**（不碰全局 process.env）
  * ```
  *
- * 隔离比较不在这里：本进程读到的 `DATABASE_URL` 此时就是测试目标，比对恒等于「自比自」。
+ * **为什么不再改写 `process.env.DATABASE_URL`**：那是进程级副作用——同一进程里并行跑多个
+ * `createTestServer`（或测试与被测代码共享进程）时会互相覆写，谁最后写谁赢。测试目标应当
+ * 只属于**本次装配**：框架把它注入到返回的 `env` 快照里，`resources` 槽位从 `ctx.env.DATABASE_URL`
+ * 读取（框架契约：资源只读 `ctx.env`，不读 `process.env`），因此每个实例各连各的，互不干扰。
+ *
+ * 隔离比较不在这里：返回的 `env.DATABASE_URL` 此时就是测试目标，比对恒等于「自比自」。
  * 防止测试清空应用数据靠的是**派生 + `_test` schema 闸门**——派生只会追加后缀，schema 闸门
  * 只放行 `*_test`，所以测试目标结构上不可能是应用目标。
  */

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

@@ -1 +1 @@
-{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/environment.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,IAAI,SAAS,CAElD;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAU/C"}
+{"version":3,"file":"environment.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/environment.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAE1C;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,IAAI,SAAS,CAElD;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAO/C"}

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

@@ -14,7 +14,7 @@ export function loadRuntimeEnvironment() {
     return loadEnvironment();
 }
 /**
- * 结算**测试**数据库目标：加载测试层 → 闸门 → 结算 → 回写 `process.env.DATABASE_URL`。
+ * 结算**测试**数据库目标：加载测试层 → 闸门 → 结算 → 把测试连接串注入返回的 env 快照。
  *
  * **`createTestServer` 的私有步骤，不对外导出。** 导出它等于让调用方自己决定「什么时候跑
  * 闸门、按什么顺序」，而顺序本身就是安全前提。
@@ -25,18 +25,21 @@ export function loadRuntimeEnvironment() {
  *   → 环境闸门（ENV 必须可清理）
  *   → 结算（显式 TEST_DATABASE_URL 优先，否则由 DATABASE_URL 派生 +_test，幂等）
  *   → schema 闸门（必须以 _test 结尾）
- *   → 回写 process.env.DATABASE_URL
+ *   → 把测试连接串写进**返回的 env 快照**（不碰全局 process.env）
  * ```
  *
- * 隔离比较不在这里：本进程读到的 `DATABASE_URL` 此时就是测试目标，比对恒等于「自比自」。
+ * **为什么不再改写 `process.env.DATABASE_URL`**：那是进程级副作用——同一进程里并行跑多个
+ * `createTestServer`（或测试与被测代码共享进程）时会互相覆写，谁最后写谁赢。测试目标应当
+ * 只属于**本次装配**：框架把它注入到返回的 `env` 快照里，`resources` 槽位从 `ctx.env.DATABASE_URL`
+ * 读取（框架契约：资源只读 `ctx.env`，不读 `process.env`），因此每个实例各连各的，互不干扰。
+ *
+ * 隔离比较不在这里：返回的 `env.DATABASE_URL` 此时就是测试目标，比对恒等于「自比自」。
  * 防止测试清空应用数据靠的是**派生 + `_test` schema 闸门**——派生只会追加后缀，schema 闸门
  * 只放行 `*_test`，所以测试目标结构上不可能是应用目标。
  */
 export function prepareTestDatabase() {
     const loaded = loadEnvironment({ mode: 'test' });
     const databaseUrl = resolveTestDatabase({ env: loaded.ENV });
-    // 强制改写：之后任何读 `process.env.DATABASE_URL` 的代码都指向测试目标
-    process.env.DATABASE_URL = databaseUrl;
-    // 快照必须在回写之后：调用方读到的 `env.DATABASE_URL` 就是测试目标
-    return resolveConfigEnv();
+    // 只注入到本次装配的 env 快照，**不改写全局 process.env.DATABASE_URL**（避免进程级串扰）
+    return { ...resolveConfigEnv(), DATABASE_URL: databaseUrl };
 }

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

@@ -1,5 +1,5 @@
-import type { ConfigEnv } from '../env.js';
-import type { ClientsView, LoggerLike, ResourcesView, Server } from '../types.js';
+import type { AppEnv, ClientsView, LoggerLike, ResourcesView, Server } from '../types.js';
+import type { TestDataUnit } from './testdata.js';
 import type { FastifyInstance } from 'fastify';
 /**
  * `createTestServer()` ——**测试对象的唯一构造方式**。
@@ -29,7 +29,7 @@ import type { FastifyInstance } from 'fastify';
  *
  * `startServer` 会 listen 并装信号处理器；测试用 `app.inject()`，且 vitest worker 收不到
  * SIGTERM。除此之外（env 分层 → resources → config → clients → services → `init()` →
- * middlewares → 系统路由 → routers、七步关闭）**逐行相同**。
+ * middlewares → 系统路由 → routers、八步关闭）**逐行相同**。
  *
  * ## 参数就是那个 `Server`，没有第二个参数
  *
@@ -44,32 +44,56 @@ import type { FastifyInstance } from 'fastify';
  * 因此返回装配期**已经构造完成**的各槽位产物，而不是让调用方重新跑一遍工厂——重新构造就等于
  * 测试里又拼了一份，与生产接线脱钩。
  *
- * **不额外包方法**：没有 `close()`、没有 `getDatabase()`、没有 `reset()`。`app` 就是原生
- * `FastifyInstance`，关闭就是 `await app.close()`，走同一套七步流程；连接串就是
- * `env.DATABASE_URL`。多包一层 `close()` 只是在已有接口上再加一个同义名，反而让「用哪个」变成
- * 需要记的事。
+ * **不包同义方法**：没有 `close()`、没有 `getDatabase()`。`app` 就是原生 `FastifyInstance`，
+ * 关闭就是 `await app.close()`，走同一套八步流程；连接串就是 `env.DATABASE_URL`。多包一层
+ * `close()` 只是在已有接口上再加一个同义名，反而让「用哪个」变成需要记的事。
+ *
+ * **唯一的例外是 `resetTestData()`**：它不是现有接口的同义名，生产入口没有对应物。测试数据的
+ * 装载 / 清理只能在测试里被驱动，而只有测试入口知道「什么时候要一份干净基线」。所以这里提供
+ * 一个方法把 `testdata/` 下那批脚本串起来——调用方仍然不需要知道有哪些脚本、怎么清。
  */
-export interface TestServer<R, C, CL, S> {
+export interface TestServer<Resources, Config, Clients, Services, Env> {
     /** 原生 Fastify 实例（已 `ready()`，用 `inject` 发请求；关闭用 `app.close()`） */
     readonly app: FastifyInstance;
     /**
-     * 装配后的固定约定 env。
+     * 装配后的 env 快照（框架固定约定 + 应用声明的扩展字段 `Env`，`AppEnv<Env>`）。
      *
-     * **测试断言「连的是哪个库」就看这里**：`env.DATABASE_URL` 在装配前已被改写成
-     * `*_test` 目标，它就是本次实际连的连接串。不额外给一个 `databaseUrl` 字段——
-     * 同一份事实出现两次，迟早会有人读到另一个。
+     * **测试断言「连的是哪个库」就看这里**：`env.DATABASE_URL` 在装配前已结算成 `*_test`
+     * 目标，它就是本次实际连的连接串。不额外给一个 `databaseUrl` 字段——同一份事实出现两次，
+     * 迟早会有人读到另一个。应用扩展的 env（如 `REDIS_KEY_PREFIX`）也在这里、且有类型。
      */
-    readonly env: ConfigEnv;
-    /** `resources` 槽位产物（`false` 键已按 `Live<T>` 剔除） */
-    readonly resources: ResourcesView<R>;
+    readonly env: AppEnv<Env>;
+    /** `resources` 槽位产物（`false` 键已按 `Live<Value>` 剔除） */
+    readonly resources: ResourcesView<Resources>;
     /** `config` 槽位产物（`Awaited<>` 归一） */
-    readonly config: Awaited<C>;
+    readonly config: Awaited<Config>;
     /** `clients` 槽位产物 */
-    readonly clients: ClientsView<CL>;
+    readonly clients: ClientsView<Clients>;
     /** `services` 槽位产物（已 `init()` 过；测试直接拿它调方法，不 mock） */
-    readonly services: Awaited<S>;
+    readonly services: Awaited<Services>;
     /** 日志器（与 `app.log` 同一个；关闭阶段仍可用） */
     readonly log: LoggerLike;
+    /**
+     * `testdata/` 目录下已装载的脚本（**执行序**：`dependsOn` 拓扑序，同层按文件名升序；
+     * 目录不存在则为空数组）。
+     *
+     * 装配时已经自动 `load()` 过一次。需要单独的细粒度控制时用这里列的脚本自跑
+     * `loadTestData({ env: testServer.env.ENV, units })`；绝大多数用例只需 `resetTestData()`。
+     */
+    readonly testData: readonly TestDataUnit[];
+    /**
+     * 重置测试数据：先整体 `cleanup`（文件名**逆序**），再整体 `load`（**正序**）。
+     *
+     * 惯例是在 `beforeEach` 调：用例前重置，上一条中途失败也不会污染下一条。
+     * 没写 `testdata/` 的服务调它没有任何副作用（空脚本集）。
+     *
+     * **环境闸门**：本实例装配时的 `ENV` 必须 ∈ `CLEANABLE_ENVS`（`development` / `test`），
+     * 否则**直接抛错**、一个脚本都不跑（不是静默跳过）。判据是装配快照，事后改
+     * `process.env.ENV` 不会改变结论——闸门守的是「这个实例实际是在什么环境里装起来的」。
+     *
+     * 失败会**直接抛出**（数据没清干净时静默继续只会制造伪绿）。
+     */
+    resetTestData(): Promise<void>;
 }
 /**
  * 构造测试对象。
@@ -84,11 +108,17 @@ export interface TestServer<R, C, CL, S> {
  *     → 回写 process.env.DATABASE_URL
  * → resources → core → config → clients → services → init() → middlewares
  *   → 系统路由 → routers → 关闭钩子 → ready()
+ *   → 装载 testdata/ 脚本并整体 load()
  * ```
  *
+ * `testdata/` 的 `load()` 排在 `ready()` 之后有一个硬性理由：脚本用的是被装配出来的真实资源
+ * （资源模块自己建连接、自己连库），而仓库里不提供「从这里拿资源」的通道——数据脚本应当
+ * 自己建自己那份客户端，所以它只依赖 env。排在最后也让失败语义最干净：装载失败时
+ * 装配已完成、可正常 `app.close()` 释放。
+ *
  * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于
  * 「自比自」。真正拦住「测试清空应用库」的是派生 + schema 闸门——派生只会给 schema 追加
  * `_test`，schema 闸门只放行 `*_test`，所以测试目标结构上不可能是应用目标。
  */
-export declare function createTestServer<R, C, CL, S>(server: Server<R, C, CL, S>): Promise<TestServer<R, C, CL, S>>;
+export declare function createTestServer<Resources, Config, Clients, Services, Env>(server: Server<Resources, Config, Clients, Services, Env>): Promise<TestServer<Resources, Config, Clients, Services, Env>>;
 //# sourceMappingURL=test-server.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"test-server.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/test-server.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACjF,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC;IACrC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,SAAS,CAAA;IACvB,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,CAAC,CAAC,CAAA;IACpC,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IAC3B,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,CAAC,CAAA;IACjC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;IAC7B,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;CACzB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CA8CjH"}
+{"version":3,"file":"test-server.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/test-server.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzF,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAA;AACjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,WAAW,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG;IACnE,kEAAkE;IAClE,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAA;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IACzB,qDAAqD;IACrD,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IAC5C,oCAAoC;IACpC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC,MAAM,CAAC,CAAA;IAChC,qBAAqB;IACrB,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,OAAO,CAAC,CAAA;IACtC,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAA;IACpC,mCAAmC;IACnC,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;IACxB;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,YAAY,EAAE,CAAA;IAC1C;;;;;;;;;;;OAWG;IACH,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC,CAwD3M"}

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

@@ -1,7 +1,8 @@
 import { initServiceUnits } from '../boot/lifecycle.js';
-import { buildClients, buildConfig, buildResources, buildServices, createBootContext, installShutdownHook, registerCoreStep, registerMiddlewares, registerRouters, registerSystemRoutesStep, } from '../boot/steps.js';
+import { buildClients, buildConfig, buildResources, buildServices, createBootContext, installShutdownHook, registerCoreStep, registerMiddlewares, registerRouters, registerSystemRoutesStep, resolveAppEnv, setupResources, } from '../boot/steps.js';
 import { maskDatabaseUrl } from './database.js';
 import { prepareTestDatabase } from './environment.js';
+import { discoverTestDataModules, loadTestData, resetTestData } from './testdata.js';
 /**
  * 构造测试对象。
  *
@@ -15,18 +16,27 @@ import { prepareTestDatabase } from './environment.js';
  *     → 回写 process.env.DATABASE_URL
  * → resources → core → config → clients → services → init() → middlewares
  *   → 系统路由 → routers → 关闭钩子 → ready()
+ *   → 装载 testdata/ 脚本并整体 load()
  * ```
  *
+ * `testdata/` 的 `load()` 排在 `ready()` 之后有一个硬性理由：脚本用的是被装配出来的真实资源
+ * （资源模块自己建连接、自己连库），而仓库里不提供「从这里拿资源」的通道——数据脚本应当
+ * 自己建自己那份客户端，所以它只依赖 env。排在最后也让失败语义最干净：装载失败时
+ * 装配已完成、可正常 `app.close()` 释放。
+ *
  * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于
  * 「自比自」。真正拦住「测试清空应用库」的是派生 + schema 闸门——派生只会给 schema 追加
  * `_test`，schema 闸门只放行 `*_test`，所以测试目标结构上不可能是应用目标。
  */
 export async function createTestServer(server) {
-    // 闸门 + 结算 + 改写全在框架内部，顺序不由调用方决定
-    const env = prepareTestDatabase();
+    // 闸门 + 结算测试连接串全在框架内部，顺序不由调用方决定；**不改写全局 process.env**（见
+    // `prepareTestDatabase`）——测试目标只注入到本次装配的 `env` 快照里，`resources` 从
+    // `ctx.env.DATABASE_URL` 读取，同进程并行多个实例互不污染。
+    const env = resolveAppEnv(prepareTestDatabase());
     // 以下步序与 `startServer` 逐行对应，只去掉 listen 与信号处理器
     const ctx = createBootContext(server, env);
-    const { resources, classifyResourceError } = await buildResources(ctx);
+    const { resources, units: resourceUnits, classifyResourceError } = await buildResources(ctx);
+    await setupResources(ctx, resourceUnits);
     await registerCoreStep(ctx, classifyResourceError);
     await buildConfig(ctx, resources);
     const clients = await buildClients(ctx, resources);
@@ -39,7 +49,7 @@ export async function createTestServer(server) {
     await registerMiddlewares(ctx, services, clients);
     registerSystemRoutesStep(ctx, services);
     await registerRouters(ctx, services, clients);
-    installShutdownHook(ctx, services);
+    installShutdownHook(ctx, services, resourceUnits);
     await ctx.app.ready();
     ctx.log.info({ service: ctx.service, database: maskDatabaseUrl(env.DATABASE_URL), env: env.ENV }, '[test-server] ready（测试实例不会监听端口）');
     // `buildConfig` 一定跑过（本路径不跳过 config），缺了就按「没有 config」的语义
@@ -47,6 +57,10 @@ export async function createTestServer(server) {
     if (!ctx.configAccess.available) {
         throw new Error('[test-server] config 槽位没有产出：装配顺序被改坏了（应当紧跟 resources 之后）');
     }
+    // 装载`testdata/` 脚本并整体 `load()`：闸门（ENV 必须可清理）在 `loadTestData` 内部，
+    // 这里不重复判断，也不降级成「非测试就不算」——失败直接冒泡。
+    const testData = await discoverTestDataModules();
+    await loadTestData({ env: env.ENV, units: testData, service: ctx.service, log: ctx.log });
     const app = ctx.app;
     return {
         app,
@@ -55,6 +69,8 @@ export async function createTestServer(server) {
         config: ctx.configAccess.read(),
         clients,
         services,
-        log: ctx.log
+        log: ctx.log,
+        testData,
+        resetTestData: () => resetTestData({ env: env.ENV, units: testData, service: ctx.service, log: ctx.log }),
     };
 }

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

@@ -26,7 +26,7 @@ function buildServer(seen = {}) {
         config: () => ({ server: { cookieNames: ['token'] } }),
         clients: () => ({}),
         services: () => ({}),
-        middlewares: () => ({}),
+        middlewares: () => [],
         routers: ({ app }) => {
             app.get('/probe', { schema: ROUTE_SCHEMA }, async () => ({ ok: true }));
         },
@@ -60,14 +60,16 @@ describe('createTestServer', () => {
         expect((await testServer.app.inject({ method: 'GET', url: '/health' })).statusCode).toBe(200);
         await testServer.app.close();
     });
-    it('数据层被强制指向 *_test（resources 拿到的 DATABASE_URL 已改写）', async () => {
+    it('数据层被结算到 *_test（resources 从 ctx.env 拿到的就是测试目标），且不改写全局 process.env', async () => {
         useEnv({ DATABASE_URL: APP_URL });
         const seen = {};
         const testServer = await createTestServer(buildServer(seen));
+        // resources 从 `ctx.env.DATABASE_URL` 读到的是结算后的测试目标
         expect(seen.databaseUrl).toContain('schema=probe_test');
-        expect(process.env.DATABASE_URL).toContain('schema=probe_test');
         // 交出来的连接串就是「测试实际连的那个」，不是从 process.env 再推一遍
         expect(testServer.env.DATABASE_URL).toBe(seen.databaseUrl);
+        // **不改写全局 process.env.DATABASE_URL**：测试目标只属于本次装配，避免同进程并行串扰
+        expect(process.env.DATABASE_URL).toBe(APP_URL);
         await testServer.app.close();
     });
     it('显式 TEST_DATABASE_URL 优先于派生', async () => {
@@ -107,7 +109,7 @@ describe('createTestServer', () => {
         await expect(createTestServer(server)).rejects.toThrow(/必须以 _test 结尾/);
         expect(onResources).not.toHaveBeenCalled();
     });
-    it('关闭时走同一套七步流程（services 的 dispose 被调用）', async () => {
+    it('关闭时走同一套八步流程（services 的 dispose 被调用）', async () => {
         useEnv({ DATABASE_URL: APP_URL });
         const onDispose = vi.fn();
         const server = defineServer({
@@ -140,7 +142,7 @@ describe('createTestServer', () => {
             config: () => config,
             clients: () => clients,
             services: () => services,
-            middlewares: () => ({}),
+            middlewares: () => [],
             routers: () => { },
         }));
         // 装配产物直接交出来：测试能断言/操作它们本身，而不是再构造一份副本。