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

package/output/app/entries.js

@@ -0,0 +1,64 @@
+import { bootServer, BOOT_PHASE_OPENAPI, BOOT_PHASE_START } from './boot.js';
+import { loadRuntimeEnvFiles, resolveConfigEnv } from './env.js';
+import { SERVER_BRAND } from './types.js';
+export { SERVER_BRAND } from './types.js';
+/**
+ * `defineServer()`（N1 §1）——**纯定义**：产出一个 `Server` 对象，不建连、不起服务。
+ *
+ * 启动是另一个函数（`startServer`）的事——同一份定义可同时喂给「启动」与「出 spec」
+ * （`generateOpenApi`）。调用方**不写泛型**：`R` / `C` / `S` 全部从工厂返回类型推导。
+ */
+export function defineServer(config) {
+    const server = {
+        ...config,
+        __brand: SERVER_BRAND,
+    };
+    return server;
+}
+/** 供内部/调试使用：判断是否为 `defineServer()` 产物 */
+export function isServer(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.__brand === SERVER_BRAND);
+}
+/**
+ * `startServer()`——真正跑起来：构造资源、加载配置、建服务、装中间件、注册路由、listen、装信号。
+ *
+ * - 最早阶段**固定加载 env**（`.env.dev < .env < .env.local`；`ENV=test` 追加 `.env.test.local`）。
+ * - 返回**原生 `FastifyInstance`**：不包 `fastify-plugin`、不返回包装对象。
+ * - `listen` 默认 `NODE_ENV !== 'test'`（测试不监听）。
+ * - 硬性要求 `Server`（品牌）产物：传裸 `ServerConfig` 是编译错误。
+ */
+export async function startServer(server, options = {}) {
+    const env = loadRuntimeEnvFiles();
+    const isTest = process.env.NODE_ENV === 'test';
+    const booted = await bootServer({
+        server,
+        env,
+        phase: BOOT_PHASE_START,
+        listen: options.listen ?? !isTest,
+        shutdown: options.shutdown,
+    });
+    return booted.app;
+}
+/**
+ * `generateOpenApi()`——只出 spec，跑到能拿到 schema 就停。
+ *
+ * **红线**：全程**不得要求配置有效** —— 不跑 `config` 槽位、不要求 `DATABASE_URL` / `REDIS_URL`
+ * 有效；`resources`（只构造不建连）/ `services` / 中间件注册 / 路由注册照常执行。
+ */
+export async function generateOpenApi(server) {
+    // 不加载 .env 文件、不读配置
+    const env = resolveConfigEnv();
+    const booted = await bootServer({
+        server,
+        env,
+        phase: BOOT_PHASE_OPENAPI,
+        listen: false,
+    });
+    const app = booted.app;
+    if (typeof app.swagger !== 'function') {
+        throw new Error('[generateOpenApi] @fastify/swagger is not registered');
+    }
+    return app.swagger();
+}

package/output/app/env.d.ts

@@ -9,16 +9,51 @@
  * helm、`docker run -e` 等显式注入始终生效，也避免测试探针
  * （`check-test-database-isolation`）注入的连接串被仓库里的默认值顶掉。
  *
- * 解析器与 account / expense / notice / release 四家现状保持一致，统一使用 `dotenv`，
- * 以保证多行值、引号/转义、`export` 前缀等细节语义完全等价（design §6：与现状逐字一致）。
+ * 解析器与四家现状保持一致，统一使用 `dotenv`，以保证多行值、引号/转义、`export` 前缀等
+ * 细节语义完全等价（设计 §3.1 ①：与现状逐字一致）。
  */
 export declare const ENV_FILE_LAYERS: readonly [".env.dev", ".env", ".env.local"];
+/** `ENV=test` 时追加的最高层（设计 §3.1 ①） */
+export declare const TEST_ENV_FILE_LAYER = ".env.test.local";
+/** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
+export declare const DEFAULT_LOG_LEVEL = "info";
 /**
- * 按分层顺序加载 env 文件（design 决策 #5：独立导出，不塞进 `defineServer`）。
+ * 按分层顺序加载 env 文件（设计 §3.1 ①）。
  *
- * 必须在任何 `config` 读取之前调用；测试 / 脚本同样复用本函数。
+ * `startServer` 内部会**固定调用**本函数；工具进程（`vitest.config.ts` / `scripts/*.ts`）不在
+ * `startServer` 覆盖范围内，须自行显式调用本函数。
  *
  * @param extraLayers 追加在最高优先级的额外层，例如测试配置传 `['.env.test.local']`
  */
 export declare function loadEnvFiles(extraLayers?: readonly string[]): void;
+/**
+ * 框架在配置前固定加载的 env（N2 §2.2）。
+ *
+ * 只读固定约定值：`ENV` / `API_PORT` / `LOG_LEVEL` / `DATABASE_URL` / `REDIS_URL`；
+ * `debug` 由 `ENV === 'development'` 派生；**绝不回退 `PORT`**（`PORT` 属 nginx）。
+ *
+ * **不给索引签名**：访问 `env.XXX` 拼错即编译错误。各仓若有额外 env，不扩展这个类型 ——
+ * 走 `process.env.XXX`（在 `resources(ctx)` 里读），框架不背书。
+ */
+export interface ConfigEnv {
+    /** 运行环境标记；`debug` 由 `ENV === 'development'` 派生 */
+    ENV: string;
+    /** 监听端口；**只读 `API_PORT`，绝不回退 `PORT`** */
+    API_PORT: string;
+    /** 日志级别；默认 `info` */
+    LOG_LEVEL: string;
+    /** 数据层连接串（`resources` 只读它构造数据层客户端） */
+    DATABASE_URL: string;
+    /** Redis 连接串；缺省 → redis 资源为 `undefined` */
+    REDIS_URL?: string;
+}
+/** 读取固定 env（不加载文件）；`startServer` 会先 `loadRuntimeEnvFiles()` 再调用本函数 */
+export declare function resolveConfigEnv(): ConfigEnv;
+/**
+ * `startServer` 最早阶段的固定 env 加载（设计 §3.1 ①）：
+ * `.env.dev < .env < .env.local`（外部注入最高），`ENV=test` 时再追加 `.env.test.local`。
+ *
+ * 注意 `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
+ */
+export declare function loadRuntimeEnvFiles(): ConfigEnv;
 //# sourceMappingURL=env.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../source/app/env.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,eAAe,6CAA8C,CAAA;AAE1E,oCAAoC;AACpC,eAAO,MAAM,mBAAmB,oBAAoB,CAAA;AAEpD,wDAAwD;AACxD,eAAO,MAAM,iBAAiB,SAAS,CAAA;AAUvC;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,WAAW,GAAE,SAAS,MAAM,EAAO,GAAG,IAAI,CAUtE;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAA;IACX,yCAAyC;IACzC,QAAQ,EAAE,MAAM,CAAA;IAChB,qBAAqB;IACrB,SAAS,EAAE,MAAM,CAAA;IACjB,sCAAsC;IACtC,YAAY,EAAE,MAAM,CAAA;IACpB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,IAAI,SAAS,CAQ5C;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,IAAI,SAAS,CAM/C"}

package/output/app/env.js

@@ -10,19 +10,24 @@ import { config } from 'dotenv';
  * helm、`docker run -e` 等显式注入始终生效，也避免测试探针
  * （`check-test-database-isolation`）注入的连接串被仓库里的默认值顶掉。
  *
- * 解析器与 account / expense / notice / release 四家现状保持一致，统一使用 `dotenv`，
- * 以保证多行值、引号/转义、`export` 前缀等细节语义完全等价（design §6：与现状逐字一致）。
+ * 解析器与四家现状保持一致，统一使用 `dotenv`，以保证多行值、引号/转义、`export` 前缀等
+ * 细节语义完全等价（设计 §3.1 ①：与现状逐字一致）。
  */
 export const ENV_FILE_LAYERS = ['.env.dev', '.env', '.env.local'];
+/** `ENV=test` 时追加的最高层（设计 §3.1 ①） */
+export const TEST_ENV_FILE_LAYER = '.env.test.local';
+/** `LOG_LEVEL` 未设置时的默认级别（设计 §3.1 ① / §5.1 `logging`） */
+export const DEFAULT_LOG_LEVEL = 'info';
 /**
  * 首次 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`）。
+ * 按分层顺序加载 env 文件（设计 §3.1 ①）。
  *
- * 必须在任何 `config` 读取之前调用；测试 / 脚本同样复用本函数。
+ * `startServer` 内部会**固定调用**本函数；工具进程（`vitest.config.ts` / `scripts/*.ts`）不在
+ * `startServer` 覆盖范围内，须自行显式调用本函数。
  *
  * @param extraLayers 追加在最高优先级的额外层，例如测试配置传 `['.env.test.local']`
  */
@@ -36,3 +41,26 @@ export function loadEnvFiles(extraLayers = []) {
         process.env[key] = value;
     }
 }
+/** 读取固定 env（不加载文件）；`startServer` 会先 `loadRuntimeEnvFiles()` 再调用本函数 */
+export function resolveConfigEnv() {
+    return {
+        ENV: process.env.ENV ?? '',
+        API_PORT: process.env.API_PORT ?? '',
+        LOG_LEVEL: process.env.LOG_LEVEL ?? DEFAULT_LOG_LEVEL,
+        DATABASE_URL: process.env.DATABASE_URL ?? '',
+        REDIS_URL: process.env.REDIS_URL,
+    };
+}
+/**
+ * `startServer` 最早阶段的固定 env 加载（设计 §3.1 ①）：
+ * `.env.dev < .env < .env.local`（外部注入最高），`ENV=test` 时再追加 `.env.test.local`。
+ *
+ * 注意 `generateOpenApi` **不**调用本函数（它不要求配置有效，设计 §3.2 规则 A/B）。
+ */
+export function loadRuntimeEnvFiles() {
+    loadEnvFiles();
+    if ((process.env.ENV ?? '') === 'test') {
+        loadEnvFiles([TEST_ENV_FILE_LAYER]);
+    }
+    return resolveConfigEnv();
+}

package/output/app/env.test.js

@@ -2,6 +2,12 @@ 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';
+/**
+ * env 加载契约（设计 §3.1 ①）。
+ *
+ * 固定约定：`.env.dev` < `.env` < `.env.local`（外部注入最高），`ENV=test` 追加 `.env.test.local`；
+ * 固定读取 `ENV` / `API_PORT` / `LOG_LEVEL`，端口**只读 `API_PORT`，绝不回退 `PORT`**。
+ */
 const ENV_KEYS = [
     'LAYER',
     'OVERRIDE',
@@ -9,12 +15,27 @@ const ENV_KEYS = [
     'ONLY_ENV',
     'ONLY_LOCAL',
     'EXTERNAL_ONLY',
+    'ONLY_TEST',
     'EXPORTED',
     'QUOTED',
     'MULTI',
     'HASHED',
+    'ENV',
+    'API_PORT',
+    'PORT',
+    'LOG_LEVEL',
 ];
-describe('loadEnvFiles', () => {
+function clearEnvKeys() {
+    for (const key of ENV_KEYS) {
+        delete process.env[key];
+    }
+}
+/** 重新求值 `env.js`（`EXTERNAL_ENV` 快照在模块首次求值时抓取） */
+async function importEnvModule() {
+    vi.resetModules();
+    return import('./env.js');
+}
+describe('env 加载（设计 §3.1 ①）', () => {
     let previousCwd;
     let directory;
     beforeEach(() => {
@@ -24,20 +45,18 @@ describe('loadEnvFiles', () => {
         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);
+        clearEnvKeys();
     });
     afterEach(() => {
         process.chdir(previousCwd);
         rmSync(directory, { recursive: true, force: true });
-        for (const key of ENV_KEYS) {
-            delete process.env[key];
-        }
+        clearEnvKeys();
         vi.resetModules();
     });
-    it('优先级：外部注入 > .env.local > .env > .env.dev', async () => {
+    it('分层优先级：外部注入 > .env.local > .env > .env.dev', async () => {
         process.env.LAYER = 'external';
         process.env.EXTERNAL_ONLY = 'external';
-        vi.resetModules();
-        const { loadEnvFiles } = await import('./env.js');
+        const { loadEnvFiles } = await importEnvModule();
         loadEnvFiles();
         expect(process.env.LAYER).toBe('external');
         expect(process.env.EXTERNAL_ONLY).toBe('external');
@@ -47,32 +66,59 @@ describe('loadEnvFiles', () => {
         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');
+        writeFileSync(join(directory, '.env.test.local'), 'OVERRIDE=test-local\nONLY_TEST=1\n');
+        const { loadEnvFiles } = await importEnvModule();
         loadEnvFiles(['.env.test.local']);
         expect(process.env.OVERRIDE).toBe('test-local');
+        expect(process.env.ONLY_TEST).toBe('1');
     });
-    it('缺失文件不报错', async () => {
+    it('缺失的 env 文件不报错，已有层照常生效', async () => {
         rmSync(join(directory, '.env.local'));
-        vi.resetModules();
-        const { loadEnvFiles } = await import('./env.js');
+        const { loadEnvFiles } = await importEnvModule();
         expect(() => loadEnvFiles()).not.toThrow();
         expect(process.env.ONLY_DEV).toBe('dev');
+        expect(process.env.OVERRIDE).toBe('env');
     });
     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');
+        writeFileSync(join(directory, '.env.local'), ['export EXPORTED=1', 'QUOTED="a b"', 'MULTI="line1\\nline2"', 'HASHED=value # 行尾注释'].join('\n'));
+        const { loadEnvFiles } = await importEnvModule();
         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');
     });
+    it('loadRuntimeEnvFiles：ENV=test 时追加 .env.test.local', async () => {
+        writeFileSync(join(directory, '.env.dev'), 'LAYER=dev\nOVERRIDE=dev\nENV=test\nAPI_PORT=4321\n');
+        writeFileSync(join(directory, '.env.test.local'), 'LOG_LEVEL=debug\nONLY_TEST=1\n');
+        const { loadRuntimeEnvFiles } = await importEnvModule();
+        const env = loadRuntimeEnvFiles();
+        expect(env.ENV).toBe('test');
+        expect(env.API_PORT).toBe('4321');
+        expect(env.LOG_LEVEL).toBe('debug');
+        expect(process.env.ONLY_TEST).toBe('1');
+    });
+    it('loadRuntimeEnvFiles：ENV 非 test 时不加载 .env.test.local', async () => {
+        writeFileSync(join(directory, '.env.local'), 'ENV=development\n');
+        writeFileSync(join(directory, '.env.test.local'), 'LOG_LEVEL=debug\nONLY_TEST=1\n');
+        const { loadRuntimeEnvFiles } = await importEnvModule();
+        const env = loadRuntimeEnvFiles();
+        expect(env.ENV).toBe('development');
+        expect(env.LOG_LEVEL).toBe('info');
+        expect(process.env.ONLY_TEST).toBeUndefined();
+    });
+    it('固定读取：只认 API_PORT（绝不回退 PORT），LOG_LEVEL 默认 info，ENV 缺省空串', async () => {
+        process.env.PORT = '9999';
+        const { resolveConfigEnv } = await importEnvModule();
+        const env = resolveConfigEnv();
+        expect(env.API_PORT).toBe('');
+        expect(env.LOG_LEVEL).toBe('info');
+        expect(env.ENV).toBe('');
+    });
+    it('固有常量：分层顺序 / 测试层 / 默认日志级别', async () => {
+        const { ENV_FILE_LAYERS, TEST_ENV_FILE_LAYER, DEFAULT_LOG_LEVEL } = await importEnvModule();
+        expect(ENV_FILE_LAYERS).toEqual(['.env.dev', '.env', '.env.local']);
+        expect(TEST_ENV_FILE_LAYER).toBe('.env.test.local');
+        expect(DEFAULT_LOG_LEVEL).toBe('info');
+    });
 });

package/output/app/error-contract.test.d.ts

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

package/output/app/error-contract.test.d.ts.map

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

package/output/app/error-contract.test.js

@@ -0,0 +1,125 @@
+import { describe, expect, it } from 'vitest';
+import { z } from 'zod';
+import { defineServer, startServer } from './entries.js';
+import { SystemError, UserError } from './errors.js';
+/**
+ * 错误契约——**强制、不可配置**。
+ *
+ * 响应信封 `{ status, message, data }`（错误时 `data: null`，`status` 放错误码字符串）；
+ * 映射固定：`UserError`→400（`error.status` 字面量）/ `SystemError`→500 / zod→400 / 未知→500 /
+ * 未匹配路由→404。错误只给稳定**码**，文案不归框架。
+ */
+/** zod validator 由 core 的 `schema` 统一装配，运行时按 zod 校验（类型上仍是 FastifySchema） */
+const validatedQuerySchema = {
+    querystring: z.object({ count: z.coerce.number().int().min(1) }),
+};
+function createErrorContractServer() {
+    return defineServer({
+        app: { service: 'error-contract', title: 'Error Contract', version: '1.0.0' },
+        resources: () => ({}),
+        config: () => ({}),
+        services: () => ({}),
+        middlewares: () => [],
+        routers: (ctx) => {
+            ctx.app.get('/ok', () => ({ hello: 'world' }));
+            ctx.app.get('/envelope', () => ({ status: 'CUSTOM', message: 'm', data: 1 }));
+            ctx.app.get('/user-error', () => {
+                throw new UserError('INVALID_TOKEN', undefined, 'token 无效');
+            });
+            ctx.app.get('/system-error', () => {
+                throw new SystemError('DATABASE_UNAVAILABLE', undefined, '数据库不可用');
+            });
+            ctx.app.get('/unknown-error', () => {
+                throw new Error('boom');
+            });
+            ctx.app.get('/validated', { schema: validatedQuerySchema }, (request) => ({
+                count: request.query.count,
+            }));
+        },
+    });
+}
+describe('错误契约', () => {
+    it('成功信封：{ status: SUCCESS, message: ok, data }', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/ok' });
+        expect(response.statusCode).toBe(200);
+        expect(response.json()).toEqual({ status: 'SUCCESS', message: 'ok', data: { hello: 'world' } });
+        await app.close();
+    });
+    it('已是信封的载荷不被二次包裹', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/envelope' });
+        expect(response.statusCode).toBe(200);
+        expect(response.json()).toEqual({ status: 'CUSTOM', message: 'm', data: 1 });
+        await app.close();
+    });
+    it('UserError → 400（取 `error.status` 字面量），status 放错误码、data 为 null', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/user-error' });
+        expect(response.statusCode).toBe(400);
+        expect(response.json()).toEqual({ status: 'INVALID_TOKEN', message: 'token 无效', data: null });
+        await app.close();
+    });
+    it('SystemError → 500（取 `error.status` 字面量）', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/system-error' });
+        expect(response.statusCode).toBe(500);
+        expect(response.json()).toEqual({ status: 'DATABASE_UNAVAILABLE', message: '数据库不可用', data: null });
+        await app.close();
+    });
+    it('未知错误 → 500 + UNKNOWN_ERROR', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/unknown-error' });
+        expect(response.statusCode).toBe(500);
+        expect(response.json()).toEqual({ status: 'UNKNOWN_ERROR', message: 'boom', data: null });
+        await app.close();
+    });
+    it('zod 校验失败 → 400（INVALID_INPUT）；通过校验 → 200', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const invalid = await app.inject({ method: 'GET', url: '/validated?count=0' });
+        expect(invalid.statusCode).toBe(400);
+        const invalidBody = invalid.json();
+        expect(invalidBody.status).toBe('INVALID_INPUT');
+        expect(invalidBody.data).toBeNull();
+        expect(invalidBody.message).toContain('count');
+        const valid = await app.inject({ method: 'GET', url: '/validated?count=3' });
+        expect(valid.statusCode).toBe(200);
+        expect(valid.json()).toEqual({ status: 'SUCCESS', message: 'ok', data: { count: 3 } });
+        await app.close();
+    });
+    it('未匹配路由 → 404 + NOT_IMPLEMENTED', async () => {
+        const app = await startServer(createErrorContractServer(), { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/missing' });
+        expect(response.statusCode).toBe(404);
+        const body = response.json();
+        expect(body.status).toBe('NOT_IMPLEMENTED');
+        expect(body.data).toBeNull();
+        expect(body.message).toContain('GET /missing');
+        await app.close();
+    });
+    it('资源包里的 `classifyError` 被用作数据层错误分类（→500）', async () => {
+        const server = defineServer({
+            app: { service: 'error-contract-database', title: 'Error Contract Database', version: '1.0.0' },
+            resources: () => ({
+                database: {
+                    classifyError: (error) => error instanceof Error && error.message === 'pg down'
+                        ? new SystemError('DATABASE_ERROR', { operation: 'query' }, 'pg down')
+                        : null,
+                },
+            }),
+            config: () => ({}),
+            services: () => ({}),
+            middlewares: () => [],
+            routers: (ctx) => {
+                ctx.app.get('/database-down', () => {
+                    throw new Error('pg down');
+                });
+            },
+        });
+        const app = await startServer(server, { listen: false });
+        const response = await app.inject({ method: 'GET', url: '/database-down' });
+        expect(response.statusCode).toBe(500);
+        expect(response.json()).toEqual({ status: 'DATABASE_ERROR', message: 'pg down', data: null });
+        await app.close();
+    });
+});

package/output/app/errors.d.ts

@@ -0,0 +1,20 @@
+import type { ErrorContext } from '@taicode/common-base';
+export declare class UserError extends Error {
+    readonly type: string;
+    readonly context?: ErrorContext | undefined;
+    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
+    static is(value: unknown): value is UserError;
+    /** 固定 HTTP 状态（字面量类型） */
+    readonly status: 400;
+    constructor(type: string, context?: ErrorContext | undefined, message?: string);
+}
+export declare class SystemError extends Error {
+    readonly type: string;
+    readonly context?: ErrorContext | undefined;
+    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
+    static is(value: unknown): value is SystemError;
+    /** 固定 HTTP 状态（字面量类型） */
+    readonly status: 500;
+    constructor(type: string, context?: ErrorContext | undefined, message?: string);
+}
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../source/app/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAA;AAsBxD,qBAAa,SAAU,SAAQ,KAAK;aASC,IAAI,EAAE,MAAM;aAAkB,OAAO,CAAC,EAAE,YAAY;IARvF,4CAA4C;IAC5C,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,SAAS;IAI7C,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAG,GAAG,CAAS;gBAEK,IAAI,EAAE,MAAM,EAAkB,OAAO,CAAC,EAAE,YAAY,YAAA,EAAE,OAAO,SAAK;CAKtG;AAED,qBAAa,WAAY,SAAQ,KAAK;aASD,IAAI,EAAE,MAAM;aAAkB,OAAO,CAAC,EAAE,YAAY;IARvF,4CAA4C;IAC5C,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,WAAW;IAI/C,wBAAwB;IACxB,QAAQ,CAAC,MAAM,EAAG,GAAG,CAAS;gBAEK,IAAI,EAAE,MAAM,EAAkB,OAAO,CAAC,EAAE,YAAY,YAAA,EAAE,OAAO,SAAK;CAKtG"}

package/output/app/errors.js

@@ -0,0 +1,51 @@
+/**
+ * 错误契约（N2 §2.12）。
+ *
+ * 框架直接提供并导出 `UserError` / `SystemError`：
+ * - `status` 是**字面量**（`400` / `500`）—— 映射表写成
+ *   `Record<UserError['status'] | SystemError['status'], number>` 时若改错直接编译失败；
+ * - `is()` 是**类型守卫**，走 `Symbol.for` 品牌（**不用 `instanceof`**：跨包 / 编译后 / 原型链丢失
+ *   都仍然可靠）；品牌与 `@taicode/common-base` 同名，故基座抛出的同类错误同样被识别；
+ * - 业务只抛这两个错误，状态码映射由框架固定（`UserError`→400 / `SystemError`→500）。
+ *
+ * 构造签名保持 `(code, context?, message?)`。
+ */
+const USER_ERROR_BRAND = Symbol.for('@taicode/common/UserError');
+const SYSTEM_ERROR_BRAND = Symbol.for('@taicode/common/SystemError');
+function hasBrand(value, brand) {
+    return typeof value === 'object' && value !== null && value[brand] === true;
+}
+export class UserError extends Error {
+    type;
+    context;
+    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
+    static is(value) {
+        return hasBrand(value, USER_ERROR_BRAND);
+    }
+    /** 固定 HTTP 状态（字面量类型） */
+    status = 400;
+    constructor(type, context, message = '') {
+        super(message, context);
+        this.type = type;
+        this.context = context;
+        this.name = 'UserError';
+        Object.defineProperty(this, USER_ERROR_BRAND, { value: true });
+    }
+}
+export class SystemError extends Error {
+    type;
+    context;
+    /** 类型守卫（`Symbol.for` 品牌，不用 `instanceof`） */
+    static is(value) {
+        return hasBrand(value, SYSTEM_ERROR_BRAND);
+    }
+    /** 固定 HTTP 状态（字面量类型） */
+    status = 500;
+    constructor(type, context, message = '') {
+        super(message, context);
+        this.type = type;
+        this.context = context;
+        this.name = 'SystemError';
+        Object.defineProperty(this, SYSTEM_ERROR_BRAND, { value: true });
+    }
+}

package/output/app/generate-openapi.test.d.ts

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

package/output/app/generate-openapi.test.d.ts.map

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