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

package/output/app/index.d.ts

@@ -7,6 +7,7 @@ export { createAuthMiddleware } from '../auth/index.js';
 export { createRateLimitMiddleware } from '../rate-limit/index.js';
 export { createRedis, createCache } from '../redis/index.js';
 export { defineResource } from '../core/resource.js';
+export type { TestDataContext, TestDataRunParams, TestDataScript, TestDataUnit } from '../core/test-support/testdata.js';
 export type { AppEnv, AppInstance, ClientsContext, ClientsFactory, ClientsView, ConfigContext, LoggerLike, Middleware, MiddlewareContext, MiddlewareEntry, MiddlewareUnit, ResourceUnit, ResourcesContext, ResourcesView, RouterContext, ServiceContext, } from '../core/types.js';
 export type { AuthVerifyInput, AuthVerifyMetadata, AuthVerifyResult } from '../auth/index.js';
 export type { AuthMiddlewareOptions } from '../auth/index.js';

package/output/app/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AA8HA,OAAO,yBAAyB,CAAA;AAGhC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAiE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAyBtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAA;AAiC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAiBlE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAsB5D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAGpD,YAAY,EACV,MAAM,EACN,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC7F,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAC7D,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,mCAAmC,GACpC,MAAM,wCAAwC,CAAA;AAC/C,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AA8HA,OAAO,yBAAyB,CAAA;AAGhC,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAA;AAiE/E,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AAyBtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAA;AAiC5E,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAA;AACvD,OAAO,EAAE,yBAAyB,EAAE,MAAM,wBAAwB,CAAA;AAiBlE,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAsB5D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAiBpD,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAA;AAGxH,YAAY,EACV,MAAM,EACN,WAAW,EACX,cAAc,EACd,cAAc,EACd,WAAW,EACX,aAAa,EACb,UAAU,EACV,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,cAAc,GACf,MAAM,kBAAkB,CAAA;AAEzB,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AAC7F,YAAY,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAC7D,YAAY,EACV,UAAU,EACV,iBAAiB,EACjB,mCAAmC,GACpC,MAAM,wCAAwC,CAAA;AAC/C,YAAY,EAAE,0BAA0B,EAAE,MAAM,wBAAwB,CAAA"}

package/output/app/index.js

@@ -284,6 +284,6 @@ export { createRedis, createCache } from '../redis/index.js';
 //
 // 「用例之间重置数据」（清表、清缓存、重新插入样本数据）**不在资源上**：资源只知道有哪些表 /
 // 哪些 key，不知道谁往里写了什么。它由一套独立机制承担：`packages/server/testdata/*.ts|js`，
-// 每个脚本自带 `load()` / `cleanup()`，框架在 `development` / `test` 下自动装载并执行。
+// 每个脚本自带 `load(ctx)` / `cleanup(ctx)`，框架在 `development` / `test` 下自动装载并执行。
 // 详见 `createTestServer` 的 `resetTestData()`。
 export { defineResource } from '../core/resource.js';

package/output/core/entries.d.ts

@@ -63,7 +63,7 @@ export declare function defineServer<Env = object, Resources = object, Config =
  * 步序**就写在本函数里**，不抽到共享的「按模式分支」的装配器：
  * ```
  * env → resources → core → config → clients → services → services.init() → middlewares
- *     → systemRoutes → routers → onClose → ready → listen/signal
+ *     → systemRoutes → routers → onClose → ready → testdata → listen/signal
  * ```
  *
  * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
@@ -75,10 +75,11 @@ export declare function defineServer<Env = object, Resources = object, Config =
  *
  * ## `development` / `test` 下会自动装载 `testdata/`
  *
- * 真启动（本地 `pnpm dev`）在 listen 成功之后、装信号处理器之前，装载 `<cwd>/testdata` 下的
- * 脚本并整体 `load()`（见 `test-support/testdata.ts`）。`ENV` 不在 `CLEANABLE_ENVS` 里
- * （即生产）时**整段跳过**——这是 `startServer` 的唯一一处环境分支，且是安静的：生产不需要
- * 测试数据，也没有什么东西需要失败。
+ * 真启动（本地 `pnpm dev`）在 `ready()` 之后、**listen 之前**装载 `<cwd>/testdata` 下的脚本并整体
+ * `load()`（见 `test-support/testdata.ts`）：端口一旦对外，数据必须已经在位。脚本拿到的是装配好的
+ * ctx（`env` + `resources` + `log`），所以它们写数据用的就是被测服务读数据的那份连接。
+ * `ENV` 不在 `CLEANABLE_ENVS` 里（即生产）时**整段跳过**——这是 `startServer` 的唯一一处环境
+ * 分支，且是安静的：生产不需要测试数据，也没有什么东西需要失败。
  *
  * `cleanup()` 在 `startServer` 路径上不会被调用：真启动要的就是「数据在」，不是「数据不在」。
  *

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

@@ -1 +1 @@
-{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../source/core/entries.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAU,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAc9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,YAAY,CAAC,GAAG,GAAG,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,GAAG,MAAM,EACjH,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,GAC9D,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAMnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,WAAW,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,eAAe,CAAC,CAgDhK;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,eAAe,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,eAAe,CAAC,CAsBpK"}
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../source/core/entries.ts"],"names":[],"mappings":"AAyBA,OAAO,KAAK,EAAU,eAAe,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC/E,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAc9C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,YAAY,CAAC,GAAG,GAAG,MAAM,EAAE,SAAS,GAAG,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,OAAO,GAAG,MAAM,EAAE,QAAQ,GAAG,MAAM,EACjH,MAAM,EAAE,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,GAC9D,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,GAAG,CAAC,CAMnD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,WAAW,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,eAAe,CAAC,CAoDhK;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAsB,eAAe,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,eAAe,CAAC,CAsBpK"}

package/output/core/entries.js

@@ -3,7 +3,7 @@ import { attachSignalHandlers } from './boot/signal.js';
 import { buildClients, buildConfig, buildResources, buildServices, createBootContext, createDocumentContext, installShutdownHook, registerCoreStep, registerDocumentCoreStep, registerDocumentRoutersStep, registerDocumentSystemRoutesStep, registerMiddlewares, registerRouters, registerSystemRoutesStep, resolveAppEnv, setupResources, } from './boot/steps.js';
 import { loadEnvironment, resolveConfigEnv, CLEANABLE_ENVS } from './env.js';
 import { SERVER_BRAND } from './types.js';
-import { discoverTestDataModules, loadTestData, resolveTestDataDirectory } from './test-support/testdata.js';
+import { discoverTestDataModules, loadTestData } from './test-support/testdata.js';
 /** 默认监听地址 */
 const DEFAULT_HOST = '0.0.0.0';
 function resolvePort(env) {
@@ -83,7 +83,7 @@ export function defineServer(config) {
  * 步序**就写在本函数里**，不抽到共享的「按模式分支」的装配器：
  * ```
  * env → resources → core → config → clients → services → services.init() → middlewares
- *     → systemRoutes → routers → onClose → ready → listen/signal
+ *     → systemRoutes → routers → onClose → ready → testdata → listen/signal
  * ```
  *
  * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
@@ -95,10 +95,11 @@ export function defineServer(config) {
  *
  * ## `development` / `test` 下会自动装载 `testdata/`
  *
- * 真启动（本地 `pnpm dev`）在 listen 成功之后、装信号处理器之前，装载 `<cwd>/testdata` 下的
- * 脚本并整体 `load()`（见 `test-support/testdata.ts`）。`ENV` 不在 `CLEANABLE_ENVS` 里
- * （即生产）时**整段跳过**——这是 `startServer` 的唯一一处环境分支，且是安静的：生产不需要
- * 测试数据，也没有什么东西需要失败。
+ * 真启动（本地 `pnpm dev`）在 `ready()` 之后、**listen 之前**装载 `<cwd>/testdata` 下的脚本并整体
+ * `load()`（见 `test-support/testdata.ts`）：端口一旦对外，数据必须已经在位。脚本拿到的是装配好的
+ * ctx（`env` + `resources` + `log`），所以它们写数据用的就是被测服务读数据的那份连接。
+ * `ENV` 不在 `CLEANABLE_ENVS` 里（即生产）时**整段跳过**——这是 `startServer` 的唯一一处环境
+ * 分支，且是安静的：生产不需要测试数据，也没有什么东西需要失败。
  *
  * `cleanup()` 在 `startServer` 路径上不会被调用：真启动要的就是「数据在」，不是「数据不在」。
  *
@@ -142,6 +143,19 @@ export async function startServer(server) {
         detachSignalHandlers();
     });
     await ctx.app.ready();
+    // 服务已经完全就绪（路由 / 中间件 / 关闭钩子都装好），现在把开发用样本数据写进去，然后才开门。
+    // 顺序是**装配 → 数据 → listen**：端口一旦对外，第一条请求就必须能看到完整数据；反过来
+    // （先 listen 再 load）会留下一段「端口在响应、数据还没就位」的窗口——本地前端 / 集成脚本
+    // 恰好在这时请求，就是偶发的 404 / 空列表。
+    //
+    // 失败直接冒泡给调用方：`testdata/` 的脚本是服务能正常提供数据的前提，它失败时**不该**把端口
+    // 占着等人发现。非可清理环境（生产）整段跳过——这是本入口唯一的环境分支。
+    if (CLEANABLE_ENVS.includes(env.ENV)) {
+        const units = await discoverTestDataModules();
+        if (units.length > 0) {
+            await loadTestData({ ctx: { env, resources, log: ctx.log }, units, service: ctx.service });
+        }
+    }
     try {
         await ctx.app.listen({ port: resolvePort(env), host: DEFAULT_HOST });
     }
@@ -151,15 +165,6 @@ export async function startServer(server) {
         throw error;
     }
     detachSignalHandlers = attachSignalHandlers(ctx.app, ctx.log);
-    // 本地开发（非测试入口）也拿同一批测试数据：`load()` 排在 listen 之后、信号处理器之后，
-    // 失败也不会把已就绪的服务卡在「端口占着、数据没就绪」的状态。
-    // 非可清理环境（生产）整段跳过——这是本入口唯一的环境分支。
-    if (CLEANABLE_ENVS.includes(env.ENV)) {
-        const units = await discoverTestDataModules(resolveTestDataDirectory());
-        if (units.length > 0) {
-            await loadTestData({ env: env.ENV, units, service: ctx.service, log: ctx.log });
-        }
-    }
     return ctx.app;
 }
 /**

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

@@ -78,9 +78,9 @@ export interface TestServer<Resources, Config, Clients, Services, Env> {
      * 目录不存在则为空数组）。
      *
      * 装配时已经自动 `load()` 过一次。需要单独的细粒度控制时用这里列的脚本自跑
-     * `loadTestData({ env: testServer.env.ENV, units })`；绝大多数用例只需 `resetTestData()`。
+     * `loadTestData({ ctx, units })`（`ctx` 见 `TestDataContext`）；绝大多数用例只需 `resetTestData()`。
      */
-    readonly testData: readonly TestDataUnit[];
+    readonly testData: readonly TestDataUnit<Resources, Env>[];
     /**
      * 重置测试数据：先整体 `cleanup`（文件名**逆序**），再整体 `load`（**正序**）。
      *
@@ -108,12 +108,12 @@ export interface TestServer<Resources, Config, Clients, Services, Env> {
  *     → 回写 process.env.DATABASE_URL
  * → resources → core → config → clients → services → init() → middlewares
  *   → 系统路由 → routers → 关闭钩子 → ready()
- *   → 装载 testdata/ 脚本并整体 load()
+ *   → 装载 testdata/ 脚本并整体 load(ctx)
  * ```
  *
- * `testdata/` 的 `load()` 排在 `ready()` 之后有一个硬性理由：脚本用的是被装配出来的真实资源
- * （资源模块自己建连接、自己连库），而仓库里不提供「从这里拿资源」的通道——数据脚本应当
- * 自己建自己那份客户端，所以它只依赖 env。排在最后也让失败语义最干净：装载失败时
+ * `testdata/` 的 `load()` 排在 `ready()` 之后：脚本拿到的是装配好的 `ctx`（`env` + `resources` +
+ * `log`），所以它写数据用的就是被测服务读数据的那份连接——两套连接写/读同一张表而看不到对方
+ * 写入（缓存 / 连接级状态）这类问题从结构上不会发生。排在最后也让失败语义最干净：装载失败时
  * 装配已完成、可正常 `app.close()` 释放。
  *
  * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于

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":"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"}
+{"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,EAAmB,YAAY,EAAE,MAAM,eAAe,CAAA;AAClE,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,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAA;IAC1D;;;;;;;;;;;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,CA2D3M"}

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

@@ -16,12 +16,12 @@ import { discoverTestDataModules, loadTestData, resetTestData } from './testdata
  *     → 回写 process.env.DATABASE_URL
  * → resources → core → config → clients → services → init() → middlewares
  *   → 系统路由 → routers → 关闭钩子 → ready()
- *   → 装载 testdata/ 脚本并整体 load()
+ *   → 装载 testdata/ 脚本并整体 load(ctx)
  * ```
  *
- * `testdata/` 的 `load()` 排在 `ready()` 之后有一个硬性理由：脚本用的是被装配出来的真实资源
- * （资源模块自己建连接、自己连库），而仓库里不提供「从这里拿资源」的通道——数据脚本应当
- * 自己建自己那份客户端，所以它只依赖 env。排在最后也让失败语义最干净：装载失败时
+ * `testdata/` 的 `load()` 排在 `ready()` 之后：脚本拿到的是装配好的 `ctx`（`env` + `resources` +
+ * `log`），所以它写数据用的就是被测服务读数据的那份连接——两套连接写/读同一张表而看不到对方
+ * 写入（缓存 / 连接级状态）这类问题从结构上不会发生。排在最后也让失败语义最干净：装载失败时
  * 装配已完成、可正常 `app.close()` 释放。
  *
  * 不会再拿应用目标跟测试目标比对：本进程读到的 `DATABASE_URL` 此时已经是测试目标，比对恒等于
@@ -57,10 +57,13 @@ export async function createTestServer(server) {
     if (!ctx.configAccess.available) {
         throw new Error('[test-server] config 槽位没有产出：装配顺序被改坏了（应当紧跟 resources 之后）');
     }
-    // 装载`testdata/` 脚本并整体 `load()`：闸门（ENV 必须可清理）在 `loadTestData` 内部，
+    // 装载`testdata/` 脚本并整体 `load(ctx)`：闸门（ENV 必须可清理）在 `loadTestData` 内部，
     // 这里不重复判断，也不降级成「非测试就不算」——失败直接冒泡。
+    //
+    // `ctx` 与 `resources` 槽位同一个口径：脚本写数据 / 清缓存用的就是被测服务的那份实例。
+    const testDataCtx = { env, resources, log: ctx.log };
     const testData = await discoverTestDataModules();
-    await loadTestData({ env: env.ENV, units: testData, service: ctx.service, log: ctx.log });
+    await loadTestData({ ctx: testDataCtx, units: testData, service: ctx.service });
     const app = ctx.app;
     return {
         app,
@@ -71,6 +74,6 @@ export async function createTestServer(server) {
         services,
         log: ctx.log,
         testData,
-        resetTestData: () => resetTestData({ env: env.ENV, units: testData, service: ctx.service, log: ctx.log }),
+        resetTestData: () => resetTestData({ ctx: testDataCtx, units: testData, service: ctx.service }),
     };
 }

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

@@ -1,4 +1,4 @@
-import type { LoggerLike } from '../types.js';
+import type { AppEnv, LoggerLike, ResourcesView } from '../types.js';
 /**
  * **测试数据（testdata）机制**：`packages/server/testdata/*.ts|js` 下的脚本，在 `development` /
  * `test` 启动时自动加载、在测试用例之间自动清理。
@@ -13,10 +13,11 @@ import type { LoggerLike } from '../types.js';
  *
  * ```ts
  * // packages/server/testdata/01-base.ts
- * import { PrismaClient } from '@prisma/generated/client'
+ * import type { TestDataContext } from '@taicode/common-server/app'
+ * import type { AppResources } from '../source/resources'
  *
- * export async function load() { …插入样本数据… }
- * export async function cleanup() { …删掉自己插入的数据… }
+ * export async function load(ctx: TestDataContext<AppResources>) { …插入样本数据… }
+ * export async function cleanup(ctx: TestDataContext<AppResources>) { …删掉自己插入的数据… }
  * ```
  *
  * ## 契约（只有三条）
@@ -36,8 +37,8 @@ import type { LoggerLike } from '../types.js';
  * ```
  *
  * - **引用名 = 去扩展名的文件名**（`01-base.ts` → `'01-base'`），与 `TestDataUnit.name` 一致。
- * - **只影响顺序，不注入任何东西**：声明依赖**不会**把前一个脚本的客户端/数据递给你。脚本仍然
- *   自己建自己的连接（只依赖 env），否则 `testdata/` 就不再是可独立运行的样本数据。
+ * - **只影响顺序，不注入任何东西**：声明依赖**不会**把前一个脚本的客户端/数据递给你——需要共享
+ *   资源时用 `ctx.resources`（框架注入的装配产物），而不是依赖另一个脚本。
  * - **`cleanup` 不用声明**：它是装配序的逆序，依赖自动反向成立（后建的先拆）。
  * - **同层按文件名升序**：没有依赖关系的脚本之间的相对顺序由文件名决定，结果确定可复现。
  * - **缺依赖 / 自依赖 / 环一律报错**（不是跳过、不是猜测顺序）：顺序是安全属性，猜错只会
@@ -54,8 +55,8 @@ import type { LoggerLike } from '../types.js';
  * - **`_` 开头的文件不是脚本**：它们是脚本之间共享的 helper（`_client.ts`），不会被 `load` /
  *   `cleanup`。否则扫描目录就会把工具文件也当成脚本执行。
  * - **只在可清理环境执行**：`load` / `cleanup` / `reset` 三个执行入口的**第 0 步**都是
- *   `assertCleanableEnvironment(env)`。`env` 是**必填参数**而不是从 `process.env` 现读——
- *    漏传即编译错误，且判据是装配期的快照（事后改写 `process.env` 不影响结论）。
+ *   `assertCleanableEnvironment(ctx.env.ENV)`。判据是装配期的 `ctx.env` 快照（事后改写
+ *   `process.env` 不影响结论）。
  *
  * ## 执行顺序与失败语义
  *
@@ -70,12 +71,35 @@ import type { LoggerLike } from '../types.js';
  *
  * 失败**一律冒泡**，不降级成「跳过这条脚本」：数据没准备好时静默继续只会让后续用例读到脏状态，
  * 制造伪绿。
+ *
+ * ## 脚本拿到什么：`ctx`（与 `resources` 槽位同一个口径）
+ *
+ * 脚本不再自己读 env、不再自己建连接——框架把装配好的东西注入进来：
+ *
+ * | 字段 | 是什么 | 为什么给 |
+ * | --- | --- | --- |
+ * | `env` | 装配快照 `AppEnv<Env>` | 脚本不碰 `process.env`；看到的就是应用看到的那份 |
+ * | `resources` | `ResourcesView<Resources>`（单元已解包） | 脚本写数据的地方就是被测服务读数据的地方 |
+ * | `log` | `ctx.log` | 日志与装配期同一路输出 |
+ *
+ * 「脚本自己建一份客户端」是**错的**：同一份数据经两条连接写/读，缓存与连接级状态对不上
+ * （account 曾经的 `globalThis` 重置注册表就是这个坑的产物）。所以注入 `resources` 是结构性的，
+ * 不是便利。
  */
-export interface TestDataScript {
+export interface TestDataContext<Resources = object, Env = object> {
+    /** 本次装配的 env 快照（框架固定约定 + 应用扩展字段）；脚本**不必也不该**再读 `process.env` */
+    readonly env: AppEnv<Env>;
+    /** 装配好的资源（单元已解包）：写数据 / 清缓存都用它，而不是另建一份客户端 */
+    readonly resources: ResourcesView<Resources>;
+    /** 记录型 logger（与装配期同一个） */
+    readonly log: LoggerLike;
+}
+/** 一个测试数据脚本（`testdata/*.ts` 的两个约定导出） */
+export interface TestDataScript<Resources = object, Env = object> {
     /** 加载本脚本负责的测试数据（可重复执行：`reset` 会反复调它） */
-    load(): void | Promise<void>;
+    load(ctx: TestDataContext<Resources, Env>): void | Promise<void>;
     /** 清理本脚本负责的测试数据（必须能把 `load()` 的效果完全撤销） */
-    cleanup(): void | Promise<void>;
+    cleanup(ctx: TestDataContext<Resources, Env>): void | Promise<void>;
     /**
      * 必须在哪些脚本**之后**执行（去扩展名的文件名；缺省 = 无要求）。
      *
@@ -85,24 +109,23 @@ export interface TestDataScript {
     readonly dependsOn?: readonly string[];
 }
 /** 一个已从磁盘装载好的脚本单元（含名字，用于日志与报错定位） */
-export interface TestDataUnit extends TestDataScript {
+export interface TestDataUnit<Resources = object, Env = object> extends TestDataScript<Resources, Env> {
     /** 脚本文件名去掉扩展名（`01-base.ts` → `01-base`） */
     readonly name: string;
 }
 /** 三个执行入口的共同入参 */
-export interface TestDataRunParams {
+export interface TestDataRunParams<Resources = object, Env = object> {
     /**
-     * 本次装配的 `env.ENV`（`ctx.env.ENV`）。**必填**：破坏性动作没有环境就没法判断该不该跑。
+     * 本次装配的 ctx（`env` + `resources` + `log`）。**必填**：
      *
-     * 非 `CLEANABLE_ENVS`（`development` / `test`）一律抛错，一个脚本都不跑。
+     * - 闸门读 `ctx.env.ENV`：非 `CLEANABLE_ENVS`（`development` / `test`）一律抛错，一个脚本都不跑；
+     * - 脚本拿到的就是这份 ctx，所以它看到的环境 / 资源与本次装配完全一致。
      */
-    env: string;
+    ctx: TestDataContext<Resources, Env>;
     /** 已装载的脚本（`discoverTestDataModules()` 的产物）；缺省 = 没有脚本 */
-    units?: readonly TestDataUnit[];
+    units?: readonly TestDataUnit<Resources, Env>[];
     /** 日志标签（`defineServer({ app: { service } })`） */
     service?: string;
-    /** 记录型 logger（`ctx.log`）；缺省 = 不打日志 */
-    log?: LoggerLike;
 }
 /** 默认脚本目录（相对 `process.cwd()`） */
 export declare function resolveTestDataDirectory(): string;
@@ -115,13 +138,13 @@ export declare function resolveTestDataDirectory(): string;
  * 返回的顺序就是**执行序**：`dependsOn` 拓扑序 + 同层文件名升序（`load` 直接正序跑，
  * `cleanup` 直接逆序跑）。
  */
-export declare function discoverTestDataModules(directory?: string): Promise<TestDataUnit[]>;
+export declare function discoverTestDataModules<Resources = object, Env = object>(directory?: string): Promise<TestDataUnit<Resources, Env>[]>;
 /**
- * 加载测试数据：按**执行序**逐项 `await load()`（依赖在前，同层按文件名升序）。
+ * 加载测试数据：按**执行序**逐项 `await load(ctx)`（依赖在前，同层按文件名升序）。
  *
- * 在 `createTestServer()` 装配完成（`ready()` 之后）自动执行一次；也可以由测试自己再调。
+ * 在 `createTestServer()` / `startServer()` 装配完成后自动执行一次；也可以由测试自己再调。
  */
-export declare function loadTestData(params: TestDataRunParams): Promise<void>;
+export declare function loadTestData<Resources, Env>(params: TestDataRunParams<Resources, Env>): Promise<void>;
 /**
  * 清理测试数据：按执行序**逆序**逐项 `await cleanup()`（后建的先拆）。
  *
@@ -130,7 +153,7 @@ export declare function loadTestData(params: TestDataRunParams): Promise<void>;
  * 单独调用它的场景很少（多半是要 `resetTestData`）：它与 `loadTestData` 成对，
  * 语义是「把脚本插入的数据撤掉」，而不是「把整个库清空」。
  */
-export declare function cleanupTestData(params: TestDataRunParams): Promise<void>;
+export declare function cleanupTestData<Resources, Env>(params: TestDataRunParams<Resources, Env>): Promise<void>;
 /**
  * 重置测试数据：先**整体** `cleanup`（逆序），再**整体** `load`（正序）。
  *
@@ -144,5 +167,5 @@ export declare function cleanupTestData(params: TestDataRunParams): Promise<void
  * - **闸门只判一次**（三个入口各自开头），不做逐脚本判定：同一批脚本在同一环境里跑，
  *   逐个判只是把一次判定复制 N 次。
  */
-export declare function resetTestData(params: TestDataRunParams): Promise<void>;
+export declare function resetTestData<Resources, Env>(params: TestDataRunParams<Resources, Env>): Promise<void>;
 //# sourceMappingURL=testdata.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"testdata.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/testdata.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuEG;AACH,MAAM,WAAW,cAAc;IAC7B,wCAAwC;IACxC,IAAI,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC5B,0CAA0C;IAC1C,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,kBAAkB;AAClB,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,GAAG,EAAE,MAAM,CAAA;IACX,wDAAwD;IACxD,KAAK,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;IAC/B,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,sCAAsC;IACtC,GAAG,CAAC,EAAE,UAAU,CAAA;CACjB;AAED,iCAAiC;AACjC,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AA8FD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,SAAS,GAAE,MAAmC,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC,CAgDrH;AAeD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAO3E;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9E;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,MAAM,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAW5E"}
+{"version":3,"file":"testdata.d.ts","sourceRoot":"","sources":["../../../source/core/test-support/testdata.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsFG;AACH,MAAM,WAAW,eAAe,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM;IAC/D,gEAAgE;IAChE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,GAAG,CAAC,CAAA;IACzB,4CAA4C;IAC5C,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC,SAAS,CAAC,CAAA;IAC5C,0BAA0B;IAC1B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;CACzB;AAED,wCAAwC;AACxC,MAAM,WAAW,cAAc,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM;IAC9D,wCAAwC;IACxC,IAAI,CAAC,GAAG,EAAE,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChE,0CAA0C;IAC1C,OAAO,CAAC,GAAG,EAAE,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IACnE;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CACvC;AAED,oCAAoC;AACpC,MAAM,WAAW,YAAY,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,CAAE,SAAQ,cAAc,CAAC,SAAS,EAAE,GAAG,CAAC;IACpG,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,kBAAkB;AAClB,MAAM,WAAW,iBAAiB,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM;IACjE;;;;;OAKG;IACH,GAAG,EAAE,eAAe,CAAC,SAAS,EAAE,GAAG,CAAC,CAAA;IACpC,wDAAwD;IACxD,KAAK,CAAC,EAAE,SAAS,YAAY,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAA;IAC/C,iDAAiD;IACjD,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,iCAAiC;AACjC,wBAAgB,wBAAwB,IAAI,MAAM,CAEjD;AA8FD;;;;;;;;GAQG;AACH,wBAAsB,uBAAuB,CAAC,SAAS,GAAG,MAAM,EAAE,GAAG,GAAG,MAAM,EAAE,SAAS,GAAE,MAAmC,GAAG,OAAO,CAAC,YAAY,CAAC,SAAS,EAAE,GAAG,CAAC,EAAE,CAAC,CAgDvK;AAeD;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,iBAAiB,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAO3G;AAED;;;;;;;GAOG;AACH,wBAAsB,eAAe,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,iBAAiB,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAM9G;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,aAAa,CAAC,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,iBAAiB,CAAC,SAAS,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAW5G"}

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

@@ -141,24 +141,24 @@ export async function discoverTestDataModules(directory = resolveTestDataDirecto
 /** 跑一个脚本步骤（统一日志，失败冒泡给调用方决定） */
 async function runTestDataUnit(params, unit, phase) {
     const fields = { service: params.service ?? '', unit: unit.name, stage: 'testdata', phase };
-    params.log?.debug(fields, `[testdata] ${phase} "${unit.name}" start`);
+    params.ctx.log.debug(fields, `[testdata] ${phase} "${unit.name}" start`);
     try {
-        await unit[phase]();
-        params.log?.debug(fields, `[testdata] ${phase} "${unit.name}" done`);
+        await unit[phase](params.ctx);
+        params.ctx.log.debug(fields, `[testdata] ${phase} "${unit.name}" done`);
     }
     catch (error) {
-        params.log?.error({ ...fields, error }, `[testdata] ${phase} "${unit.name}" failed`);
+        params.ctx.log.error({ ...fields, error }, `[testdata] ${phase} "${unit.name}" failed`);
         throw error;
     }
 }
 /**
- * 加载测试数据：按**执行序**逐项 `await load()`（依赖在前，同层按文件名升序）。
+ * 加载测试数据：按**执行序**逐项 `await load(ctx)`（依赖在前，同层按文件名升序）。
  *
- * 在 `createTestServer()` 装配完成（`ready()` 之后）自动执行一次；也可以由测试自己再调。
+ * 在 `createTestServer()` / `startServer()` 装配完成后自动执行一次；也可以由测试自己再调。
  */
 export async function loadTestData(params) {
     // 闸门先于一切：非可清理环境下一个脚本都不许跑
-    assertCleanableEnvironment(params.env);
+    assertCleanableEnvironment(params.ctx.env.ENV);
     for (const unit of sortByDependencies(params.units ?? [])) {
         await runTestDataUnit(params, unit, 'load');
     }
@@ -172,7 +172,7 @@ export async function loadTestData(params) {
  * 语义是「把脚本插入的数据撤掉」，而不是「把整个库清空」。
  */
 export async function cleanupTestData(params) {
-    assertCleanableEnvironment(params.env);
+    assertCleanableEnvironment(params.ctx.env.ENV);
     for (const unit of sortByDependencies(params.units ?? []).reverse()) {
         await runTestDataUnit(params, unit, 'cleanup');
     }
@@ -191,7 +191,7 @@ export async function cleanupTestData(params) {
  *   逐个判只是把一次判定复制 N 次。
  */
 export async function resetTestData(params) {
-    assertCleanableEnvironment(params.env);
+    assertCleanableEnvironment(params.ctx.env.ENV);
     const units = sortByDependencies(params.units ?? []);
     for (const unit of [...units].reverse()) {
         await runTestDataUnit(params, unit, 'cleanup');

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

@@ -124,6 +124,14 @@ describe('discoverTestDataModules', () => {
         await expect(discoverTestDataModules(dir)).rejects.toThrow(/dependsOn 必须是字符串数组/);
     });
 });
+/** 造一个最小 ctx（`resources` 用不着时给空对象；`log` 静默） */
+function makeCtx(env, resources = {}) {
+    return {
+        env: { ENV: env },
+        resources: resources,
+        log: { debug: () => { }, info: () => { }, warn: () => { }, error: () => { } },
+    };
+}
 /** 造一批内存脚本单元（不经磁盘，专测执行语义） */
 function unitsOf(order, names) {
     return names.map((name) => ({
@@ -140,36 +148,48 @@ describe('testdata 执行语义', () => {
     it('load 正序、cleanup 逆序', async () => {
         const order = [];
         const units = unitsOf(order, ['a', 'b', 'c']);
-        await loadTestData({ env: 'test', units });
+        await loadTestData({ ctx: makeCtx('test'), units });
         expect(order).toEqual(['load:a', 'load:b', 'load:c']);
         order.length = 0;
-        await cleanupTestData({ env: 'test', units });
+        await cleanupTestData({ ctx: makeCtx('test'), units });
         expect(order).toEqual(['cleanup:c', 'cleanup:b', 'cleanup:a']);
     });
     it('reset 先整体 cleanup（逆序）再整体 load（正序）', async () => {
         const order = [];
         const units = unitsOf(order, ['a', 'b']);
-        await resetTestData({ env: 'test', units });
+        await resetTestData({ ctx: makeCtx('test'), units });
         // 分两趟而不是「逐脚本 cleanup + load」：后者会让前一个脚本刚插入的数据
         // 被后一个脚本的 cleanup 顺手删掉（顺序依赖）。
         expect(order).toEqual(['cleanup:b', 'cleanup:a', 'load:a', 'load:b']);
     });
+    it('每个脚本收到的就是同一个 ctx（env / resources / log 都是装配产物）', async () => {
+        const seen = [];
+        const resources = { database: { marker: 'live-db' } };
+        const ctx = makeCtx('test', resources);
+        const units = [
+            { name: 'a', load: (received) => { seen.push(received); }, cleanup: () => { } },
+        ];
+        await loadTestData({ ctx, units });
+        // 同一个对象：脚本里 `ctx.resources.database` 就是被测服务用的那个实例，不是副本
+        expect(seen[0]).toBe(ctx);
+        expect(seen[0].resources.database).toBe(resources.database);
+    });
     it('执行器自己按 dependsOn 定序，不信任调用方传入的顺序', async () => {
         const order = [];
         const units = [
             { name: '01-late', dependsOn: ['99-early'], load: () => { order.push('load:late'); }, cleanup: () => { order.push('cleanup:late'); } },
             { name: '99-early', load: () => { order.push('load:early'); }, cleanup: () => { order.push('cleanup:early'); } },
         ];
-        await loadTestData({ env: 'test', units });
+        await loadTestData({ ctx: makeCtx('test'), units });
         expect(order).toEqual(['load:early', 'load:late']);
         order.length = 0;
-        await cleanupTestData({ env: 'test', units });
+        await cleanupTestData({ ctx: makeCtx('test'), units });
         expect(order).toEqual(['cleanup:late', 'cleanup:early']);
     });
     it('没有脚本时三个入口都是空操作（但闸门照样生效）', async () => {
-        await expect(loadTestData({ env: 'test' })).resolves.toBeUndefined();
-        await expect(cleanupTestData({ env: 'development' })).resolves.toBeUndefined();
-        await expect(resetTestData({ env: 'test' })).resolves.toBeUndefined();
+        await expect(loadTestData({ ctx: makeCtx('test') })).resolves.toBeUndefined();
+        await expect(cleanupTestData({ ctx: makeCtx('development') })).resolves.toBeUndefined();
+        await expect(resetTestData({ ctx: makeCtx('test') })).resolves.toBeUndefined();
     });
     it.each([
         ['loadTestData', loadTestData],
@@ -181,7 +201,7 @@ describe('testdata 执行语义', () => {
             { name: 'ok', load: () => { order.push('load:ok'); }, cleanup: () => { order.push('cleanup:ok'); } },
             { name: 'broken', load: () => { throw new Error('insert failed'); }, cleanup: () => { throw new Error('delete failed'); } },
         ];
-        await expect(run({ env: 'test', units })).rejects.toThrow(/failed/);
+        await expect(run({ ctx: makeCtx('test'), units })).rejects.toThrow(/failed/);
     });
 });
 describe('testdata 的环境闸门', () => {
@@ -192,24 +212,24 @@ describe('testdata 的环境闸门', () => {
         ['resetTestData', resetTestData],
     ])('%s：非可清理环境一个脚本都不跑', async (_name, run) => {
         const order = [];
-        await expect(run({ env: 'production', units: units(order) })).rejects.toThrow(/拒绝在 ENV=/);
+        await expect(run({ ctx: makeCtx('production'), units: units(order) })).rejects.toThrow(/拒绝在 ENV=/);
         expect(order).toEqual([]);
     });
     it.each(['production', 'staging', ''])('ENV=%s 时拒绝，报错带上当前值', async (env) => {
-        await expect(loadTestData({ env })).rejects.toThrow(/ENV="/);
+        await expect(loadTestData({ ctx: makeCtx(env) })).rejects.toThrow(/ENV="/);
     });
     it.each(['development', 'test'])('ENV=%s 时放行', async (env) => {
         const order = [];
-        await loadTestData({ env, units: units(order) });
+        await loadTestData({ ctx: makeCtx(env), units: units(order) });
         expect(order).toEqual(['load:a']);
     });
     it('闸门先于一切：没有脚本也要在非可清理环境下失败', async () => {
-        await expect(resetTestData({ env: 'production' })).rejects.toThrow(/ENV="production"/);
+        await expect(resetTestData({ ctx: makeCtx('production') })).rejects.toThrow(/ENV="production"/);
     });
-    it('判据是传入的 env 参数，不是 process.env（事后改写不影响结论）', async () => {
+    it('判据是 ctx.env 快照，不是 process.env（事后改写不影响结论）', async () => {
         const order = [];
         process.env.ENV = 'production';
-        await loadTestData({ env: 'test', units: units(order) });
+        await loadTestData({ ctx: makeCtx('test'), units: units(order) });
         expect(order).toEqual(['load:a']);
     });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taicode/common-server",
-  "version": "4.0.0-beta.6",
+  "version": "4.0.0-beta.7",
   "author": "Alain",
   "license": "ISC",
   "description": "",
@@ -35,7 +35,7 @@
   "peerDependencies": {
     "fastify": "^5.5.0",
     "redis": "^5.11.0",
-    "@taicode/common-base": "^4.0.0-beta.6"
+    "@taicode/common-base": "^4.0.0-beta.7"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.3",
@@ -49,7 +49,7 @@
     "redis": "^5.11.0",
     "typescript-eslint": "^8.56.1",
     "vitest": "^3.2.4",
-    "@taicode/common-base": "^4.0.0-beta.6"
+    "@taicode/common-base": "^4.0.0-beta.7"
   },
   "scripts": {
     "test": "vitest run",