@taicode/common-server 3.7.13 → 3.8.0

package/output/app/define-server.test.d.ts.map

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

package/output/app/define-server.test.js

@@ -0,0 +1,299 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import { createPrismaDatabaseModule } from './database.js';
+import { defineServer } from './define-server.js';
+import { STEP_ORDER } from './steps.js';
+const P1_OPT_OUT = {
+    context: false,
+    response: false,
+    cors: false,
+    schema: false,
+    'rate-limit': false,
+    auth: false,
+    openapi: false,
+    database: false,
+};
+const DUMMY_ERRORS = {
+    UserError: class extends Error {
+    },
+    SystemError: class extends Error {
+    },
+};
+const TEST_CONFIG = { loadConfig: () => ({ debug: false, port: 0 }) };
+const FAKE_PRISMA_NAMESPACE = {
+    PrismaClientKnownRequestError: class extends Error {
+    },
+    PrismaClientUnknownRequestError: class extends Error {
+    },
+    PrismaClientValidationError: class extends Error {
+    },
+    PrismaClientRustPanicError: class extends Error {
+    },
+    PrismaClientInitializationError: class extends Error {
+    },
+};
+class FakeClient {
+    args;
+    disconnected = false;
+    constructor(args = []) {
+        this.args = args;
+    }
+    async $disconnect() {
+        this.disconnected = true;
+    }
+}
+function createTestLog() {
+    const steps = [];
+    const errors = [];
+    const log = {
+        debug: (obj) => {
+            const step = obj.step;
+            if (typeof step === 'string') {
+                steps.push(step);
+            }
+        },
+        info: () => undefined,
+        warn: () => undefined,
+        error: (obj) => {
+            errors.push(obj);
+        },
+    };
+    return { log, steps, errors };
+}
+function without(list, drop) {
+    return list.filter((step) => !drop.includes(step));
+}
+function createBaseOptions(overrides = {}) {
+    return {
+        serviceName: 'test',
+        title: 'Test',
+        description: 'Test service',
+        errors: DUMMY_ERRORS,
+        config: TEST_CONFIG,
+        modules: { ...P1_OPT_OUT },
+        serverOptions: { port: 0, host: '127.0.0.1' },
+        signal: false,
+        createServices: () => ({ dispose: () => undefined }),
+        registerRouters: () => undefined,
+        ...overrides,
+    };
+}
+describe('defineServer 装配期校验', () => {
+    it('未知模块名报错（文案逐字对齐 design §3.2）', async () => {
+        const modules = { ...P1_OPT_OUT, foo: false };
+        await expect(defineServer(createBaseOptions({ modules }))).rejects.toThrow('Unknown module "foo". Allowed: env, database, redis, context, response, cors, schema, rate-limit, auth, openapi');
+    });
+    it('重复注册报错', async () => {
+        const modules = { ...P1_OPT_OUT, cors: { name: 'cors' }, redis: { name: 'cors' } };
+        await expect(defineServer(createBaseOptions({ modules }))).rejects.toThrow('Module "cors" registered twice');
+    });
+    it('键名不符报错', async () => {
+        const modules = { ...P1_OPT_OUT, redis: { name: 'mysql' } };
+        await expect(defineServer(createBaseOptions({ modules }))).rejects.toThrow('Module key "redis" != module.name "mysql"');
+    });
+    it('dependsOn 指向被跳过的模块报错', async () => {
+        const modules = {
+            ...P1_OPT_OUT,
+            database: false,
+            redis: { name: 'redis', dependsOn: ['database'] },
+        };
+        await expect(defineServer(createBaseOptions({ modules }))).rejects.toThrow('Module "redis" depends on "database" which is disabled');
+    });
+    it('P1 未实现模块未显式 false 报错', async () => {
+        const modules = {
+            context: false,
+            cors: false,
+            schema: false,
+            'rate-limit': false,
+            auth: false,
+            openapi: false,
+            database: false,
+        };
+        await expect(defineServer(createBaseOptions({ modules }))).rejects.toThrow('Module "response" is not implemented until P3; pass false to opt out');
+    });
+    it('过渡期报错按真实阶段号：openapi = P2、auth = P4', async () => {
+        const modulesWithoutOpenapi = {
+            context: false,
+            response: false,
+            cors: false,
+            schema: false,
+            'rate-limit': false,
+            auth: false,
+            database: false,
+        };
+        await expect(defineServer(createBaseOptions({ modules: modulesWithoutOpenapi }))).rejects.toThrow('Module "openapi" is not implemented until P2; pass false to opt out');
+        const modulesWithoutAuth = {
+            context: false,
+            response: false,
+            cors: false,
+            schema: false,
+            'rate-limit': false,
+            openapi: false,
+            database: false,
+        };
+        await expect(defineServer(createBaseOptions({ modules: modulesWithoutAuth }))).rejects.toThrow('Module "auth" is not implemented until P4; pass false to opt out');
+    });
+    it('未显式提供 database 报错（提示需 createPrismaDatabaseModule({...}) 或 false）', async () => {
+        const modules = {
+            context: false,
+            response: false,
+            cors: false,
+            schema: false,
+            'rate-limit': false,
+            auth: false,
+            openapi: false,
+        };
+        await expect(defineServer(createBaseOptions({ modules }))).rejects.toThrow('Module "database" requires createPrismaDatabaseModule({...}) or false');
+    });
+    it('装配期报错发生在 promise resolve 之前（不拖到 listen）', async () => {
+        const promise = defineServer(createBaseOptions({ modules: { ...P1_OPT_OUT, database: false, redis: { name: 'redis', dependsOn: ['database'] } } }));
+        await expect(promise).rejects.toThrow();
+    });
+});
+describe('defineServer 15 步骨架', () => {
+    it('production 模式执行完整 15 步且顺序固定', async () => {
+        const { log, steps } = createTestLog();
+        const app = await defineServer(createBaseOptions({ log, mode: 'production' }));
+        try {
+            expect(steps).toEqual([...STEP_ORDER]);
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('test 模式跳过第 10 / 14 步', async () => {
+        const { log, steps } = createTestLog();
+        const app = await defineServer(createBaseOptions({ log, mode: 'test' }));
+        try {
+            expect(steps).toEqual(without(STEP_ORDER, ['backgroundWorkers', 'afterReady']));
+        }
+        finally {
+            await app.close();
+        }
+    });
+    it('openapi-build 模式跳过 [5,6,9,10,14,15]，但保留第 3 / 4 步（决策 10-3）', async () => {
+        const { log, steps } = createTestLog();
+        const app = await defineServer(createBaseOptions({ log, mode: 'openapi-build' }));
+        expect(steps).toEqual(without(STEP_ORDER, ['initGlobalConfig', 'initClients', 'initServices', 'backgroundWorkers', 'afterReady', 'listen']));
+        expect(steps).toContain('database.createClient');
+        expect(steps).toContain('createRedis');
+        await app.close();
+    });
+});
+describe('defineServer 跳过语义', () => {
+    it('test 模式下 backgroundWorkers / afterReady 确实未执行', async () => {
+        let workers = 0;
+        let ready = 0;
+        const app = await defineServer(createBaseOptions({
+            mode: 'test',
+            backgroundWorkers: async () => {
+                workers += 1;
+            },
+            afterReady: async () => {
+                ready += 1;
+            },
+        }));
+        await app.close();
+        expect(workers).toBe(0);
+        expect(ready).toBe(0);
+    });
+    it('openapi-build 模式下连库/连 Redis 与集合类初始化确实未执行', async () => {
+        const calls = { initGlobalConfig: 0, initClients: 0, initServices: 0, workers: 0, ready: 0, routers: 0 };
+        const app = await defineServer(createBaseOptions({
+            mode: 'openapi-build',
+            initGlobalConfig: () => {
+                calls.initGlobalConfig += 1;
+            },
+            initClients: async () => {
+                calls.initClients += 1;
+            },
+            initServices: async () => {
+                calls.initServices += 1;
+            },
+            backgroundWorkers: async () => {
+                calls.workers += 1;
+            },
+            afterReady: async () => {
+                calls.ready += 1;
+            },
+            registerRouters: () => {
+                calls.routers += 1;
+            },
+        }));
+        await app.close();
+        expect(calls).toEqual({ initGlobalConfig: 0, initClients: 0, initServices: 0, workers: 0, ready: 0, routers: 1 });
+    });
+    it('production 模式下后台 worker / afterReady 都会执行', async () => {
+        let workers = 0;
+        let ready = 0;
+        const app = await defineServer(createBaseOptions({
+            mode: 'production',
+            backgroundWorkers: async () => {
+                workers += 1;
+            },
+            afterReady: async () => {
+                ready += 1;
+            },
+        }));
+        await app.close();
+        expect(workers).toBe(1);
+        expect(ready).toBe(1);
+    });
+    it('database: false 时第 3 步空转，createServices 收到 undefined db', async () => {
+        let received = 'sentinel';
+        const app = await defineServer(createBaseOptions({
+            modules: { ...P1_OPT_OUT, database: false },
+            createServices: (ctx) => {
+                received = ctx.db;
+                return {};
+            },
+        }));
+        await app.close();
+        expect(received).toBeUndefined();
+    });
+});
+describe('defineServer 模块覆盖与 Db 推断', () => {
+    it('Db 泛型从 database 模块推断（决策 10-2，无需强转）', async () => {
+        const database = createPrismaDatabaseModule({
+            PrismaClient: FakeClient,
+            PrismaNamespace: FAKE_PRISMA_NAMESPACE,
+        });
+        const app = await defineServer({
+            serviceName: 'test',
+            title: 'Test',
+            description: 'Test service',
+            errors: DUMMY_ERRORS,
+            config: TEST_CONFIG,
+            modules: { ...P1_OPT_OUT, database },
+            serverOptions: { port: 0, host: '127.0.0.1' },
+            signal: false,
+            createServices: (ctx) => {
+                expectTypeOf(ctx.db).toEqualTypeOf();
+                return {};
+            },
+            registerRouters: () => undefined,
+        });
+        await app.close();
+    });
+    it('整体覆盖 database 模块时使用覆盖实现的 createClient', async () => {
+        let created = 0;
+        const database = {
+            name: 'database',
+            createClient: () => {
+                created += 1;
+                return { tag: 'custom' };
+            },
+            classifyError: () => null,
+        };
+        let received;
+        const app = await defineServer(createBaseOptions({
+            modules: { ...P1_OPT_OUT, database: database },
+            createServices: (ctx) => {
+                received = ctx.db;
+                return {};
+            },
+        }));
+        await app.close();
+        expect(created).toBe(1);
+        expect(received).toEqual({ tag: 'custom' });
+    });
+});

package/output/app/env.d.ts

@@ -0,0 +1,24 @@
+/**
+ * 默认 env 文件分层（低 → 高优先级，后者覆盖前者）：
+ *
+ *   .env.dev   已提交进仓库的 dev 默认值（克隆后 `pnpm run dev` 开箱即用）
+ *   .env       本机私有覆盖（已被 gitignore）
+ *   .env.local 本机更高优先级覆盖（已被 gitignore）
+ *
+ * 真实环境变量（进程/容器注入）优先级最高，任何 .env 文件都不会覆盖它们 —— 这条保证让 CI、
+ * helm、`docker run -e` 等显式注入始终生效，也避免测试探针
+ * （`check-test-database-isolation`）注入的连接串被仓库里的默认值顶掉。
+ *
+ * 解析器与 account / expense / notice / release 四家现状保持一致，统一使用 `dotenv`，
+ * 以保证多行值、引号/转义、`export` 前缀等细节语义完全等价（design §6：与现状逐字一致）。
+ */
+export declare const ENV_FILE_LAYERS: readonly [".env.dev", ".env", ".env.local"];
+/**
+ * 按分层顺序加载 env 文件（design 决策 #5：独立导出，不塞进 `defineServer`）。
+ *
+ * 必须在任何 `config` 读取之前调用；测试 / 脚本同样复用本函数。
+ *
+ * @param extraLayers 追加在最高优先级的额外层，例如测试配置传 `['.env.test.local']`
+ */
+export declare function loadEnvFiles(extraLayers?: readonly string[]): void;
+//# sourceMappingURL=env.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../source/app/env.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,6CAA8C,CAAA;AAU1E;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,WAAW,GAAE,SAAS,MAAM,EAAO,GAAG,IAAI,CAUtE"}

package/output/app/env.js

@@ -0,0 +1,38 @@
+import { config } from 'dotenv';
+/**
+ * 默认 env 文件分层（低 → 高优先级，后者覆盖前者）：
+ *
+ *   .env.dev   已提交进仓库的 dev 默认值（克隆后 `pnpm run dev` 开箱即用）
+ *   .env       本机私有覆盖（已被 gitignore）
+ *   .env.local 本机更高优先级覆盖（已被 gitignore）
+ *
+ * 真实环境变量（进程/容器注入）优先级最高，任何 .env 文件都不会覆盖它们 —— 这条保证让 CI、
+ * helm、`docker run -e` 等显式注入始终生效，也避免测试探针
+ * （`check-test-database-isolation`）注入的连接串被仓库里的默认值顶掉。
+ *
+ * 解析器与 account / expense / notice / release 四家现状保持一致，统一使用 `dotenv`，
+ * 以保证多行值、引号/转义、`export` 前缀等细节语义完全等价（design §6：与现状逐字一致）。
+ */
+export const ENV_FILE_LAYERS = ['.env.dev', '.env', '.env.local'];
+/**
+ * 首次 import 时的真实环境变量快照（此时还没有任何 .env 文件被加载）。
+ * 加载结束后原样恢复，实现「外部注入 > .env.local > .env > .env.dev」。
+ */
+const EXTERNAL_ENV = new Map(Object.entries(process.env).filter((entry) => entry[1] !== undefined));
+/**
+ * 按分层顺序加载 env 文件（design 决策 #5：独立导出，不塞进 `defineServer`）。
+ *
+ * 必须在任何 `config` 读取之前调用；测试 / 脚本同样复用本函数。
+ *
+ * @param extraLayers 追加在最高优先级的额外层，例如测试配置传 `['.env.test.local']`
+ */
+export function loadEnvFiles(extraLayers = []) {
+    const layers = [...ENV_FILE_LAYERS, ...extraLayers];
+    layers.forEach((path, index) => {
+        // 第一层不覆盖已有值，后续层逐层覆盖前一层
+        config({ path, override: index > 0 });
+    });
+    for (const [key, value] of EXTERNAL_ENV) {
+        process.env[key] = value;
+    }
+}

package/output/app/env.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=env.test.d.ts.map

package/output/app/env.test.d.ts.map

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

package/output/app/env.test.js

@@ -0,0 +1,78 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+const ENV_KEYS = [
+    'LAYER',
+    'OVERRIDE',
+    'ONLY_DEV',
+    'ONLY_ENV',
+    'ONLY_LOCAL',
+    'EXTERNAL_ONLY',
+    'EXPORTED',
+    'QUOTED',
+    'MULTI',
+    'HASHED',
+];
+describe('loadEnvFiles', () => {
+    let previousCwd;
+    let directory;
+    beforeEach(() => {
+        previousCwd = process.cwd();
+        directory = mkdtempSync(join(tmpdir(), 'common-app-env-'));
+        writeFileSync(join(directory, '.env.dev'), 'LAYER=dev\nONLY_DEV=dev\nOVERRIDE=dev\n');
+        writeFileSync(join(directory, '.env'), 'LAYER=env\nONLY_ENV=env\nOVERRIDE=env\n');
+        writeFileSync(join(directory, '.env.local'), 'LAYER=local\nONLY_LOCAL=local\nOVERRIDE=local\n');
+        process.chdir(directory);
+    });
+    afterEach(() => {
+        process.chdir(previousCwd);
+        rmSync(directory, { recursive: true, force: true });
+        for (const key of ENV_KEYS) {
+            delete process.env[key];
+        }
+        vi.resetModules();
+    });
+    it('优先级：外部注入 > .env.local > .env > .env.dev', async () => {
+        process.env.LAYER = 'external';
+        process.env.EXTERNAL_ONLY = 'external';
+        vi.resetModules();
+        const { loadEnvFiles } = await import('./env.js');
+        loadEnvFiles();
+        expect(process.env.LAYER).toBe('external');
+        expect(process.env.EXTERNAL_ONLY).toBe('external');
+        expect(process.env.OVERRIDE).toBe('local');
+        expect(process.env.ONLY_DEV).toBe('dev');
+        expect(process.env.ONLY_ENV).toBe('env');
+        expect(process.env.ONLY_LOCAL).toBe('local');
+    });
+    it('追加层（如 .env.test.local）优先级最高', async () => {
+        writeFileSync(join(directory, '.env.test.local'), 'OVERRIDE=test-local\n');
+        vi.resetModules();
+        const { loadEnvFiles } = await import('./env.js');
+        loadEnvFiles(['.env.test.local']);
+        expect(process.env.OVERRIDE).toBe('test-local');
+    });
+    it('缺失文件不报错', async () => {
+        rmSync(join(directory, '.env.local'));
+        vi.resetModules();
+        const { loadEnvFiles } = await import('./env.js');
+        expect(() => loadEnvFiles()).not.toThrow();
+        expect(process.env.ONLY_DEV).toBe('dev');
+    });
+    it('dotenv 语义：export 前缀 / 引号 / 转义 / 多行 / 行尾注释（与四家现状逐字一致）', async () => {
+        writeFileSync(join(directory, '.env.local'), [
+            'export EXPORTED=1',
+            'QUOTED="a b"',
+            'MULTI="line1\\nline2"',
+            'HASHED=value # 行尾注释',
+        ].join('\n'));
+        vi.resetModules();
+        const { loadEnvFiles } = await import('./env.js');
+        loadEnvFiles();
+        expect(process.env.EXPORTED).toBe('1');
+        expect(process.env.QUOTED).toBe('a b');
+        expect(process.env.MULTI).toBe('line1\nline2');
+        expect(process.env.HASHED).toBe('value');
+    });
+});

package/output/app/index.d.ts

@@ -0,0 +1,16 @@
+export { defineServer } from './define-server.js';
+export { loadEnvFiles, ENV_FILE_LAYERS } from './env.js';
+export { createPrismaDatabaseModule } from './database.js';
+export { createEnvModule, createRedisModule, createDefaultModules } from './default-modules.js';
+export { MODULE_NAMES, PENDING_MODULES } from './module.js';
+export { STEP_ORDER, SKIP_BY_MODE } from './steps.js';
+export { SHUTDOWN_ORDER } from './shutdown.js';
+export { assembleModules } from './assemble.js';
+export { attachSignalHandlers } from './signal.js';
+export type { DefineServerOptions, ServerInstance, ServerMode, ErrorFactory, ErrorFactories, RuntimeConfig, ConfigModule, LoggerLike, RedisLike, RedisHandle, DisposeFunction, UnsubscribeFunction, GlobalConfigOptions, DbContext, ServicesContext, InitContext, WorkersContext, ReadyContext, ServerOptions, ResolveMessage, MapStatus, RuntimeState, StepContext, StepRunner, StepImplementations, ShutdownRunner, ShutdownImplementations, ServerHooks, } from './types.js';
+export type { ModuleName, ModuleAssembly, ServerModule, DatabaseModule, DatabaseClientParams, PrismaErrorConstructors, PrismaOperationKey, PrismaOperationLabels, PendingModuleName, PendingModuleStage, } from './module.js';
+export type { ResolvedModules } from './assemble.js';
+export type { StepName } from './steps.js';
+export type { ShutdownStepName } from './shutdown.js';
+export type { PrismaDatabaseModuleParams } from './database.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../source/app/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AACjD,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,UAAU,CAAA;AACxD,OAAO,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAA;AAC1D,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAA;AAC/F,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC3D,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACrD,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAC9C,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAC/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAA;AAElD,YAAY,EACV,mBAAmB,EACnB,cAAc,EACd,UAAU,EACV,YAAY,EACZ,cAAc,EACd,aAAa,EACb,YAAY,EACZ,UAAU,EACV,SAAS,EACT,WAAW,EACX,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,SAAS,EACT,eAAe,EACf,WAAW,EACX,cAAc,EACd,YAAY,EACZ,aAAa,EACb,cAAc,EACd,SAAS,EACT,YAAY,EACZ,WAAW,EACX,UAAU,EACV,mBAAmB,EACnB,cAAc,EACd,uBAAuB,EACvB,WAAW,GACZ,MAAM,YAAY,CAAA;AACnB,YAAY,EACV,UAAU,EACV,cAAc,EACd,YAAY,EACZ,cAAc,EACd,oBAAoB,EACpB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,aAAa,CAAA;AACpB,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,YAAY,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAA;AAC1C,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AACrD,YAAY,EAAE,0BAA0B,EAAE,MAAM,eAAe,CAAA"}

package/output/app/index.js

@@ -0,0 +1,9 @@
+export { defineServer } from './define-server.js';
+export { loadEnvFiles, ENV_FILE_LAYERS } from './env.js';
+export { createPrismaDatabaseModule } from './database.js';
+export { createEnvModule, createRedisModule, createDefaultModules } from './default-modules.js';
+export { MODULE_NAMES, PENDING_MODULES } from './module.js';
+export { STEP_ORDER, SKIP_BY_MODE } from './steps.js';
+export { SHUTDOWN_ORDER } from './shutdown.js';
+export { assembleModules } from './assemble.js';
+export { attachSignalHandlers } from './signal.js';

package/output/app/module.d.ts

@@ -0,0 +1,88 @@
+import type { SystemError } from '@taicode/common-base';
+import type { FastifyPluginAsync } from 'fastify';
+import type { ConfigModule, ServerHooks, ShutdownImplementations, StepImplementations } from './types.js';
+/**
+ * 封闭模块名集合（design §3.1 十项）。
+ *
+ * 数组顺序即「注册顺序」，也是装配期报错文案里 `Allowed: ...` 的顺序，**不得重排**。
+ */
+export declare const MODULE_NAMES: readonly ["env", "database", "redis", "context", "response", "cors", "schema", "rate-limit", "auth", "openapi"];
+export type ModuleName = (typeof MODULE_NAMES)[number];
+/**
+ * P1 尚未提供默认实现的模块 → 各自的落地阶段（design §3.1 十项里除 `env` / `database` / `redis`
+ * 之外的七个）。阶段号取自 `proposals/P1-boot-shutdown.md`：`openapi` 在 P2、`auth` 在 P4、其余在 P3。
+ *
+ * P1 过渡规则（design §3.2 + 提案 §3.3）：这些名字**必须由调用方显式写 `false`**（或直接提供
+ * 一个同名的整体覆盖实现），否则装配期按**真实阶段号**报错 —— 静默 no-op 会让调用方少注册插件
+ * 却启动成功。
+ */
+export declare const PENDING_MODULES: {
+    readonly context: "P3";
+    readonly response: "P3";
+    readonly cors: "P3";
+    readonly schema: "P3";
+    readonly 'rate-limit': "P3";
+    readonly auth: "P4";
+    readonly openapi: "P2";
+};
+export type PendingModuleName = keyof typeof PENDING_MODULES;
+export type PendingModuleStage = (typeof PENDING_MODULES)[PendingModuleName];
+/** 模块契约：可贡献「初始化步骤实现 / Fastify 插件 / 生命周期 hook / 关闭逻辑」四类东西（design §3.1） */
+export interface ServerModule {
+    /** 具名单元；装配期校验「键 == name」「不重复」「在封闭集合内」 */
+    name: ModuleName;
+    /** ① 初始化步骤实现：key 只能是 §4.1 的既定槽位，不得新增 / 重排步骤 */
+    steps?: Partial<StepImplementations>;
+    /** ② Fastify 插件：注册进第 7 步 `registerCorePlugins` */
+    plugins?: FastifyPluginAsync[];
+    /** ③ 生命周期 hook（见 design §4.2）；模块提供的 hook 不再是顶层选项 */
+    hooks?: ServerHooks;
+    /** ④ 关闭逻辑：只能命中 §5 的 7 个既定槽位 */
+    shutdown?: Partial<ShutdownImplementations>;
+    /** 依赖的其它模块名；装配期做拓扑校验（指向被跳过的模块即报错） */
+    dependsOn?: ModuleName[];
+}
+/** 模块装配入参（design §3.2）：未出现 = 默认实现；`false` = 跳过；对象 = 整体覆盖 */
+export interface ModuleAssembly<Db = unknown> {
+    env?: false | ServerModule;
+    database?: false | DatabaseModule<Db>;
+    redis?: false | ServerModule;
+    context?: false | ServerModule;
+    response?: false | ServerModule;
+    cors?: false | ServerModule;
+    schema?: false | ServerModule;
+    'rate-limit'?: false | ServerModule;
+    auth?: false | ServerModule;
+    openapi?: false | ServerModule;
+}
+/** `database` 模块步骤 3 的入参（design §3.3） */
+export interface DatabaseClientParams {
+    config: ConfigModule;
+    postgresConfig: unknown;
+}
+/** 各仓生成的 Prisma 命名空间里、错误分类用到的 5 个错误类构造器（跨包 instanceof 不可靠，决策 #9） */
+export interface PrismaErrorConstructors {
+    PrismaClientKnownRequestError: new (...args: never[]) => unknown;
+    PrismaClientUnknownRequestError: new (...args: never[]) => unknown;
+    PrismaClientValidationError: new (...args: never[]) => unknown;
+    PrismaClientInitializationError: new (...args: never[]) => unknown;
+    PrismaClientRustPanicError: new (...args: never[]) => unknown;
+}
+export type PrismaOperationKey = 'known' | 'unknown' | 'validation' | 'initialization' | 'rustPanic';
+/** 可选覆盖的 operation 标签（默认对齐 design §2.3 的统一口径） */
+export type PrismaOperationLabels = Partial<Record<PrismaOperationKey, string>>;
+/**
+ * 数据层端口（design §3.3）：任何实现只要满足它即可整体替换。
+ *
+ * 契约相同（同名、同贡献面）即可换实现——「支持非 Prisma 数据库」靠模块替换达成。
+ */
+export interface DatabaseModule<Db = unknown> extends ServerModule {
+    name: 'database';
+    /** 步骤 3：建立连接。默认 Prisma 实现 = `new PrismaClient(...)` */
+    createClient(params: DatabaseClientParams): Db | Promise<Db>;
+    /** 错误分类：命中 → `SystemError('DATABASE_ERROR', …)`；未命中 → `null`（落回 UNKNOWN_ERROR 兜底） */
+    classifyError(error: unknown): SystemError | null;
+    /** §5-7：释放连接。默认 = `db.$disconnect()` */
+    dispose?(db: Db): Promise<void>;
+}
+//# sourceMappingURL=module.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"module.d.ts","sourceRoot":"","sources":["../../source/app/module.ts"],"names":[],"mappings":"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"}

package/output/app/module.js

@@ -0,0 +1,34 @@
+/**
+ * 封闭模块名集合（design §3.1 十项）。
+ *
+ * 数组顺序即「注册顺序」，也是装配期报错文案里 `Allowed: ...` 的顺序，**不得重排**。
+ */
+export const MODULE_NAMES = [
+    'env',
+    'database',
+    'redis',
+    'context',
+    'response',
+    'cors',
+    'schema',
+    'rate-limit',
+    'auth',
+    'openapi',
+];
+/**
+ * P1 尚未提供默认实现的模块 → 各自的落地阶段（design §3.1 十项里除 `env` / `database` / `redis`
+ * 之外的七个）。阶段号取自 `proposals/P1-boot-shutdown.md`：`openapi` 在 P2、`auth` 在 P4、其余在 P3。
+ *
+ * P1 过渡规则（design §3.2 + 提案 §3.3）：这些名字**必须由调用方显式写 `false`**（或直接提供
+ * 一个同名的整体覆盖实现），否则装配期按**真实阶段号**报错 —— 静默 no-op 会让调用方少注册插件
+ * 却启动成功。
+ */
+export const PENDING_MODULES = {
+    context: 'P3',
+    response: 'P3',
+    cors: 'P3',
+    schema: 'P3',
+    'rate-limit': 'P3',
+    auth: 'P4',
+    openapi: 'P2',
+};

package/output/app/shutdown.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 固定关闭 7 步（design §5）——**顺序写死在数组里**。
+ *
+ * 关键修正（相对现状）：Redis 晚于 queue/cache 消费者释放；afterInit（如 LDAP）资源进第 1 步。
+ * 单步抛错记录后**继续**后续步骤，最后聚合上报（避免「config 报错导致 DB 没关」）。
+ */
+export declare const SHUTDOWN_ORDER: readonly ["stopProducers", "unsubscribeConfig", "disposeConfig", "disposeServices", "disposeClients", "disposeRedis", "disposeDb"];
+export type ShutdownStepName = (typeof SHUTDOWN_ORDER)[number];
+//# sourceMappingURL=shutdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"shutdown.d.ts","sourceRoot":"","sources":["../../source/app/shutdown.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,eAAO,MAAM,cAAc,oIAQjB,CAAA;AAEV,MAAM,MAAM,gBAAgB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAA"}

package/output/app/shutdown.js

@@ -0,0 +1,15 @@
+/**
+ * 固定关闭 7 步（design §5）——**顺序写死在数组里**。
+ *
+ * 关键修正（相对现状）：Redis 晚于 queue/cache 消费者释放；afterInit（如 LDAP）资源进第 1 步。
+ * 单步抛错记录后**继续**后续步骤，最后聚合上报（避免「config 报错导致 DB 没关」）。
+ */
+export const SHUTDOWN_ORDER = [
+    'stopProducers',
+    'unsubscribeConfig',
+    'disposeConfig',
+    'disposeServices',
+    'disposeClients',
+    'disposeRedis',
+    'disposeDb',
+];

package/output/app/shutdown.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shutdown.test.d.ts.map

package/output/app/shutdown.test.d.ts.map

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