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

package/output/app/core/cookie.js

@@ -0,0 +1,22 @@
+import cookie from '@fastify/cookie'; // eslint-disable-line import/default -- @fastify/cookie 是 CJS `export =`，esModuleInterop 下默认导入即正确用法
+/** 从 `readConfig('server')` 的返回值读取 cookie 名列表（缺省 `['token']`，对齐四家现状） */
+export function resolveCookieNames(server) {
+    const names = server?.cookieNames;
+    return Array.isArray(names) && names.length > 0 ? names : ['token'];
+}
+/** 从 `readConfig('server')` 的返回值读取 cookie domain */
+export function resolveCookieDomain(server) {
+    return server?.domain;
+}
+export function registerCookie(app, options) {
+    app.register(cookie);
+    app.decorateReply('setAuthCookie', function setAuthCookie(name, value, cookieOptions = {}) {
+        this.setCookie(name, value, {
+            path: cookieOptions.path ?? '/',
+            maxAge: cookieOptions.maxAge,
+            domain: cookieOptions.domain ?? resolveCookieDomain(options.readConfig('server')),
+            sameSite: 'lax',
+            secure: options.env.ENV === 'production',
+        });
+    });
+}

package/output/app/core/identity.d.ts

@@ -0,0 +1,12 @@
+import type { AppIdentity } from '../types.js';
+/**
+ * 身份块在 `app` 上的存放键（Symbol，**不进公共契约**）。
+ *
+ * `defineServer({ app })` 的身份块只属于定义产物；`middlewares` / `routers` 的 ctx 里没有它
+ * （可见性按需收窄），框架内置单元（`auth` 权限自注册 / `rateLimit` 前缀）需要 `service` /
+ * `version` 时从这里读。
+ */
+export declare const SERVER_IDENTITY: unique symbol;
+export declare function attachServerIdentity(app: unknown, identity: AppIdentity): void;
+export declare function readServerIdentity(app: unknown): AppIdentity | undefined;
+//# sourceMappingURL=identity.d.ts.map

package/output/app/core/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../../source/app/core/identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAE9C;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,eAAwC,CAAA;AAEpE,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,GAAG,IAAI,CAE9E;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAExE"}

package/output/app/core/identity.js

@@ -0,0 +1,14 @@
+/**
+ * 身份块在 `app` 上的存放键（Symbol，**不进公共契约**）。
+ *
+ * `defineServer({ app })` 的身份块只属于定义产物；`middlewares` / `routers` 的 ctx 里没有它
+ * （可见性按需收窄），框架内置单元（`auth` 权限自注册 / `rateLimit` 前缀）需要 `service` /
+ * `version` 时从这里读。
+ */
+export const SERVER_IDENTITY = Symbol.for('taicode.server/identity');
+export function attachServerIdentity(app, identity) {
+    Object.defineProperty(app, SERVER_IDENTITY, { value: identity, enumerable: false, configurable: true });
+}
+export function readServerIdentity(app) {
+    return app?.[SERVER_IDENTITY];
+}

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

@@ -0,0 +1,44 @@
+import type { ErrorClassifier } from './response.js';
+import type { ConfigEnv } from '../env.js';
+import type { AppIdentity } from '../types.js';
+import type { FastifyInstance } from 'fastify';
+export { registerCookie, resolveCookieNames, resolveCookieDomain } from './cookie.js';
+export { registerResponse, createSuccessResponse, createErrorResponse } from './response.js';
+export { registerOpenApi, DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './openapi.js';
+export { registerRequestId, REQUEST_ID_HEADER, REQUEST_ID_LOG_LABEL } from './request-id.js';
+export { createLoggerOptions, LOG_REDACT_PATHS } from './logging.js';
+export { SERVER_IDENTITY, attachServerIdentity, readServerIdentity } from './identity.js';
+export type { AuthCookieOptions, CookieCoreOptions } from './cookie.js';
+export type { ResponseCoreOptions, ResponseEnvelope } from './response.js';
+export type { OpenApiCoreOptions } from './openapi.js';
+/**
+ * core `schema`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * 装配 `fastify-type-provider-zod` 的 validator / serializer compiler；响应 schema 由框架统一
+ * 生成（业务侧用 `../schema/index.js` 的 `responseSchema`）。
+ */
+export declare function registerSchema(app: FastifyInstance): void;
+/**
+ * core 步骤 `createFastify`（`prepare`）。
+ *
+ * **总是**建 pino logger（level = `LOG_LEVEL`，默认 `info`） + 内置 `requestId`（入站 `x-request-id`
+ * 复用 / `randomUUID`，日志字段 `requestId`）。`trustProxy: true` 与四家现状一致。
+ */
+export declare function createFastify(env: ConfigEnv): FastifyInstance;
+/** core 装配入参 */
+export interface CoreRegistrationOptions {
+    /** 身份块（`service` / `title` / `version`）：openapi + 内置单元从这里读 */
+    identity: AppIdentity;
+    env: ConfigEnv;
+    /** 数据层错误分类（资源包提供；缺省 = 落 `UNKNOWN_ERROR`） */
+    classifyError?: ErrorClassifier;
+    /** 取**已加载**配置中某个键的访问器（cookie domain 等**惰性**取值；不得在构造期调用） */
+    readConfig: (key: string) => unknown;
+}
+/**
+ * core 装配：`schema` → `cookie` → `response` → `openapi` → 路由注册表。
+ * `requestId` 的响应回吐 hook 一并注册。**构造期不读配置**（`cookie` 的 domain 在请求期惰性读取），
+ * 故出 spec 路径（`readConfig` 不可用）不会触发。
+ */
+export declare function registerCore(app: FastifyInstance, options: CoreRegistrationOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../source/app/core/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAA;AACrF,OAAO,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAA;AAC5F,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAChF,OAAO,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAA;AAC5F,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAA;AACpE,OAAO,EAAE,eAAe,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEzF,YAAY,EAAE,iBAAiB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACvE,YAAY,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAC1E,YAAY,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAEtD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAMzD;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,SAAS,GAAG,eAAe,CAM7D;AAED,gBAAgB;AAChB,MAAM,WAAW,uBAAuB;IACtC,8DAA8D;IAC9D,QAAQ,EAAE,WAAW,CAAA;IACrB,GAAG,EAAE,SAAS,CAAA;IACd,4CAA4C;IAC5C,aAAa,CAAC,EAAE,eAAe,CAAA;IAC/B,2DAA2D;IAC3D,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACrC;AAED;;;;GAIG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,IAAI,CAAC,CAaxG"}

package/output/app/core/index.js

@@ -0,0 +1,57 @@
+import Fastify from 'fastify';
+import { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
+import { installRegisteredOperations } from '../permission-operations.js';
+import { registerCookie } from './cookie.js';
+import { attachServerIdentity } from './identity.js';
+import { createLoggerOptions } from './logging.js';
+import { registerOpenApi } from './openapi.js';
+import { createRequestIdOptions, registerRequestId } from './request-id.js';
+import { registerResponse } from './response.js';
+export { registerCookie, resolveCookieNames, resolveCookieDomain } from './cookie.js';
+export { registerResponse, createSuccessResponse, createErrorResponse } from './response.js';
+export { registerOpenApi, DOC_ROUTE_PREFIX, DOC_SPEC_ROUTE } from './openapi.js';
+export { registerRequestId, REQUEST_ID_HEADER, REQUEST_ID_LOG_LABEL } from './request-id.js';
+export { createLoggerOptions, LOG_REDACT_PATHS } from './logging.js';
+export { SERVER_IDENTITY, attachServerIdentity, readServerIdentity } from './identity.js';
+/**
+ * core `schema`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * 装配 `fastify-type-provider-zod` 的 validator / serializer compiler；响应 schema 由框架统一
+ * 生成（业务侧用 `../schema/index.js` 的 `responseSchema`）。
+ */
+export function registerSchema(app) {
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+}
+/**
+ * core 步骤 `createFastify`（`prepare`）。
+ *
+ * **总是**建 pino logger（level = `LOG_LEVEL`，默认 `info`） + 内置 `requestId`（入站 `x-request-id`
+ * 复用 / `randomUUID`，日志字段 `requestId`）。`trustProxy: true` 与四家现状一致。
+ */
+export function createFastify(env) {
+    return Fastify({
+        trustProxy: true,
+        logger: createLoggerOptions(env),
+        ...createRequestIdOptions(),
+    });
+}
+/**
+ * core 装配：`schema` → `cookie` → `response` → `openapi` → 路由注册表。
+ * `requestId` 的响应回吐 hook 一并注册。**构造期不读配置**（`cookie` 的 domain 在请求期惰性读取），
+ * 故出 spec 路径（`readConfig` 不可用）不会触发。
+ */
+export async function registerCore(app, options) {
+    attachServerIdentity(app, options.identity);
+    registerSchema(app); // schema → zod compiler
+    registerCookie(app, { env: options.env, readConfig: options.readConfig });
+    registerResponse(app, { classifyError: options.classifyError });
+    // await：确定性冲刷插件队列，保证 swagger 的 root `onRoute` 钩子在路由注册之前就位
+    await registerOpenApi(app, {
+        title: options.identity.title,
+        version: options.identity.version,
+    });
+    // 路由注册表：在 routers 阶段之前挂 root `onRoute`，供 `auth` 权限自注册读取（与 swagger 解耦）
+    installRegisteredOperations(app);
+    registerRequestId(app); // 响应回吐 x-request-id
+}

package/output/app/core/logging.d.ts

@@ -0,0 +1,13 @@
+import type { ConfigEnv } from '../env.js';
+import type { FastifyServerOptions } from 'fastify';
+/**
+ * core `logging`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * `createFastify` **总是**建 pino logger（级别取 `LOG_LEVEL`，默认 `info`）；原 `logging: false`
+ * 开关随 `CoreOptions` 一并删除，日志始终开启，不再由 `debug` 控制。
+ */
+/** 默认 `redact` 路径（设计 §5.1） */
+export declare const LOG_REDACT_PATHS: readonly ["authorization", "cookie", "set-cookie", "req.headers.authorization", "req.headers.cookie", "*.token", "*.password", "*.secretKey", "*.secretValue"];
+/** 构造 Fastify 的 logger 选项 */
+export declare function createLoggerOptions(env: ConfigEnv): FastifyServerOptions['logger'];
+//# sourceMappingURL=logging.d.ts.map

package/output/app/core/logging.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.d.ts","sourceRoot":"","sources":["../../../source/app/core/logging.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAA;AAC1C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAEnD;;;;;GAKG;AAEH,8BAA8B;AAC9B,eAAO,MAAM,gBAAgB,gKAUnB,CAAA;AAEV,6BAA6B;AAC7B,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAQlF"}

package/output/app/core/logging.js

@@ -0,0 +1,29 @@
+import { DEFAULT_LOG_LEVEL } from '../env.js';
+/**
+ * core `logging`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * `createFastify` **总是**建 pino logger（级别取 `LOG_LEVEL`，默认 `info`）；原 `logging: false`
+ * 开关随 `CoreOptions` 一并删除，日志始终开启，不再由 `debug` 控制。
+ */
+/** 默认 `redact` 路径（设计 §5.1） */
+export const LOG_REDACT_PATHS = [
+    'authorization',
+    'cookie',
+    'set-cookie',
+    'req.headers.authorization',
+    'req.headers.cookie',
+    '*.token',
+    '*.password',
+    '*.secretKey',
+    '*.secretValue',
+];
+/** 构造 Fastify 的 logger 选项 */
+export function createLoggerOptions(env) {
+    return {
+        level: env.LOG_LEVEL || DEFAULT_LOG_LEVEL,
+        redact: {
+            paths: [...LOG_REDACT_PATHS],
+            censor: '[Redacted]',
+        },
+    };
+}

package/output/app/core/openapi.d.ts

@@ -0,0 +1,17 @@
+import type { FastifyInstance } from 'fastify';
+/**
+ * core `openapi`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * `@fastify/swagger` + `@scalar/fastify-api-reference`；`/reference` 与 `/reference/openapi.json`；
+ * `servers: [{ url: '/' }]`（构建期不依赖 env / DB）；`version` 取 `app.version`（必填，无默认）；
+ * `securitySchemes.bearerAuth`；`onListen` 打印实际地址。
+ */
+export declare const DOC_ROUTE_PREFIX = "/reference";
+export declare const DOC_SPEC_ROUTE = "/reference/openapi.json";
+export declare const OPENAPI_SPEC_VERSION = "3.0.3";
+export interface OpenApiCoreOptions {
+    title: string;
+    version: string;
+}
+export declare function registerOpenApi(app: FastifyInstance, options: OpenApiCoreOptions): Promise<void>;
+//# sourceMappingURL=openapi.d.ts.map

package/output/app/core/openapi.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../../source/app/core/openapi.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;GAMG;AAEH,eAAO,MAAM,gBAAgB,eAAe,CAAA;AAC5C,eAAO,MAAM,cAAc,4BAA4B,CAAA;AACvD,eAAO,MAAM,oBAAoB,UAAU,CAAA;AAE3C,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,wBAAsB,eAAe,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BtG"}

package/output/app/core/openapi.js

@@ -0,0 +1,42 @@
+import scalar from '@scalar/fastify-api-reference';
+import swagger from '@fastify/swagger';
+import { createJsonSchemaTransform } from 'fastify-type-provider-zod';
+/**
+ * core `openapi`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * `@fastify/swagger` + `@scalar/fastify-api-reference`；`/reference` 与 `/reference/openapi.json`；
+ * `servers: [{ url: '/' }]`（构建期不依赖 env / DB）；`version` 取 `app.version`（必填，无默认）；
+ * `securitySchemes.bearerAuth`；`onListen` 打印实际地址。
+ */
+export const DOC_ROUTE_PREFIX = '/reference';
+export const DOC_SPEC_ROUTE = '/reference/openapi.json';
+export const OPENAPI_SPEC_VERSION = '3.0.3';
+export async function registerOpenApi(app, options) {
+    app.register(swagger, {
+        openapi: {
+            openapi: OPENAPI_SPEC_VERSION,
+            info: {
+                title: options.title,
+                version: options.version,
+            },
+            // 构建期不依赖 env / DB（设计 §5.1 / §3.2 规则 A/B）
+            servers: [{ url: '/' }],
+            components: {
+                securitySchemes: {
+                    bearerAuth: { type: 'http', scheme: 'bearer' },
+                },
+            },
+            security: [{ bearerAuth: [] }],
+        },
+        transform: createJsonSchemaTransform({ skipList: [] }),
+    });
+    app.register(scalar, { routePrefix: DOC_ROUTE_PREFIX });
+    // 确定性冲刷插件队列：让 swagger / scalar 的插件体在**任何路由注册之前**执行完——
+    // @fastify/swagger 经 fastify-plugin 在 root 上挂 `onRoute` 钩子，只有它先就位，
+    // 后续 `routers` 阶段注册的路由才会被采集进文档。不得依赖「恰好有 cors 等其它
+    // `app.register` 顺带冲刷队列」这种隐式巧合（设计 §5.2 / §10-18）。
+    await app.after();
+    app.addHook('onListen', () => {
+        app.log.info({ docPath: DOC_SPEC_ROUTE }, '[openapi] api reference ready');
+    });
+}

package/output/app/core/request-id.d.ts

@@ -0,0 +1,36 @@
+import type { FastifyInstance } from 'fastify';
+/**
+ * core `requestId`（设计 §5.1 / §8）——**框架内置、锁定、不可替换/修改**。
+ *
+ * 入站 header（固定 `x-request-id`）存在且**非空** → 复用，否则用 `randomUUID` 写入 `request.id`；
+ * **响应统一回吐 `reply.header('x-request-id', request.id)`**（进日志 + 进响应 header，
+ * **不进响应体**）；日志字段键名统一为全拼 `requestId`。
+ *
+ * 归一语义（实现裁定 §10-8）：入站值 **trim 后为空**视为缺失 → 重新生成 `randomUUID`；
+ * 非空则 **trim 后复用**。Fastify 的 `requestIdHeader` 对**已存在**的 header 直接取用
+ * （`headers[name] || genReqId`），故空白串（`'   '`）会原样透传、带空格的也会保留——由下面的
+ * `onRequest` 钩子在链路最前补齐归一，并同步 `request.id` / 日志字段 / 响应 header。
+ */
+export declare const REQUEST_ID_HEADER = "x-request-id";
+export declare const REQUEST_ID_LOG_LABEL = "requestId";
+/** 归一化入站 header 值（设计 §5.1）：数组取首个；**trim 后为空视为缺失**（返回 `undefined`） */
+export declare function normalizeInboundRequestId(inbound: string | string[] | undefined): string | undefined;
+/** 传给 `Fastify()` 的 requestId 相关选项 */
+export declare function createRequestIdOptions(): {
+    requestIdHeader: string;
+    requestIdLogLabel: string;
+    genReqId: (request: {
+        headers: Record<string, string | string[] | undefined>;
+    }) => string;
+};
+/**
+ * 注册 `requestId` 钩子（设计 §5.1 / §8）：
+ *
+ * ① `onRequest` 归一化入站 `x-request-id`——`trim` 后为空 → 重新 `randomUUID`，非空 → `trim` 后复用。
+ * ② `onSend` 响应统一回吐 `x-request-id`（进日志 + 进响应 header，**不进响应体**）。
+ *
+ * Fastify 在 `onRequest` **之前**已用原始值建好 child logger，故归一后须重绑日志，才能保证
+ * 入口 `request.id`、日志字段 `requestId`、响应 header 三处一致。
+ */
+export declare function registerRequestId(app: FastifyInstance): void;
+//# sourceMappingURL=request-id.d.ts.map

package/output/app/core/request-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request-id.d.ts","sourceRoot":"","sources":["../../../source/app/core/request-id.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,iBAAiB,iBAAiB,CAAA;AAC/C,eAAO,MAAM,oBAAoB,cAAc,CAAA;AAE/C,qEAAqE;AACrE,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAOpG;AAED,sCAAsC;AACtC,wBAAgB,sBAAsB,IAAI;IACxC,eAAe,EAAE,MAAM,CAAA;IACvB,iBAAiB,EAAE,MAAM,CAAA;IACzB,QAAQ,EAAE,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;KAAE,KAAK,MAAM,CAAA;CAC1F,CAOA;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAwB5D"}

package/output/app/core/request-id.js

@@ -0,0 +1,66 @@
+import { randomUUID } from 'node:crypto';
+/**
+ * core `requestId`（设计 §5.1 / §8）——**框架内置、锁定、不可替换/修改**。
+ *
+ * 入站 header（固定 `x-request-id`）存在且**非空** → 复用，否则用 `randomUUID` 写入 `request.id`；
+ * **响应统一回吐 `reply.header('x-request-id', request.id)`**（进日志 + 进响应 header，
+ * **不进响应体**）；日志字段键名统一为全拼 `requestId`。
+ *
+ * 归一语义（实现裁定 §10-8）：入站值 **trim 后为空**视为缺失 → 重新生成 `randomUUID`；
+ * 非空则 **trim 后复用**。Fastify 的 `requestIdHeader` 对**已存在**的 header 直接取用
+ * （`headers[name] || genReqId`），故空白串（`'   '`）会原样透传、带空格的也会保留——由下面的
+ * `onRequest` 钩子在链路最前补齐归一，并同步 `request.id` / 日志字段 / 响应 header。
+ */
+export const REQUEST_ID_HEADER = 'x-request-id';
+export const REQUEST_ID_LOG_LABEL = 'requestId';
+/** 归一化入站 header 值（设计 §5.1）：数组取首个；**trim 后为空视为缺失**（返回 `undefined`） */
+export function normalizeInboundRequestId(inbound) {
+    const value = Array.isArray(inbound) ? inbound[0] : inbound;
+    if (typeof value !== 'string') {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/** 传给 `Fastify()` 的 requestId 相关选项 */
+export function createRequestIdOptions() {
+    return {
+        requestIdHeader: REQUEST_ID_HEADER,
+        requestIdLogLabel: REQUEST_ID_LOG_LABEL,
+        // Fastify 仅在「入站 header 缺失 / 为空串」时调用它（空白串为真值，走 `requestIdHeader` 短路）
+        genReqId: (request) => normalizeInboundRequestId(request.headers[REQUEST_ID_HEADER]) ?? randomUUID(),
+    };
+}
+/**
+ * 注册 `requestId` 钩子（设计 §5.1 / §8）：
+ *
+ * ① `onRequest` 归一化入站 `x-request-id`——`trim` 后为空 → 重新 `randomUUID`，非空 → `trim` 后复用。
+ * ② `onSend` 响应统一回吐 `x-request-id`（进日志 + 进响应 header，**不进响应体**）。
+ *
+ * Fastify 在 `onRequest` **之前**已用原始值建好 child logger，故归一后须重绑日志，才能保证
+ * 入口 `request.id`、日志字段 `requestId`、响应 header 三处一致。
+ */
+export function registerRequestId(app) {
+    app.addHook('onRequest', (request, reply, done) => {
+        const inbound = request.headers[REQUEST_ID_HEADER];
+        if (inbound === undefined) {
+            // 缺失：`genReqId` 已生成 `randomUUID`
+            done();
+            return;
+        }
+        const normalized = normalizeInboundRequestId(inbound) ?? randomUUID();
+        if (normalized !== request.id) {
+            request.id = normalized;
+            // 从根 logger 重建（而非在原 child 上再 child，避免 JSON 出现重复 `requestId` 键），
+            // 效果等同「入站 header 一开始就是干净值」；请求侧与响应侧同步，保证三处一致。
+            const log = request.server.log.child({ [REQUEST_ID_LOG_LABEL]: normalized });
+            request.log = log;
+            reply.log = log;
+        }
+        done();
+    });
+    app.addHook('onSend', (request, reply, payload, done) => {
+        reply.header(REQUEST_ID_HEADER, request.id);
+        done(null, payload);
+    });
+}

package/output/app/core/response.d.ts

@@ -0,0 +1,41 @@
+import { SystemError } from '../errors.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * core `response`（设计 §5.1 / §8，错误契约 D7）——**框架内置、锁定、不可替换/修改**。
+ *
+ * - 成功信封 `{ status: 'SUCCESS', message: 'ok', data }`（由 `preSerialization` 统一包裹）。
+ * - 错误信封 `{ status: <错误码字符串>, message, data: null }`。
+ * - `setErrorHandler` 固定分支：`UserError`→400（`error.status` 字面量）/ `SystemError`→500 /
+ *   zod→400 / serde→500 / 数据层（资源包的 `classifyError`）→500 / 未知→500；**禁止按 `error.type` 细分**。
+ * - `setNotFoundHandler` → 404 + `NOT_IMPLEMENTED`（落 `warn`，文案对齐 expense/notice）。
+ * - 错误日志分级：`UserError` / zod → `warn`，其余 → `error`（带 stack）。
+ * - **错误只给稳定码**（`status` 放错误码字符串），文案不归框架（由前端 / i18n 决定，§10-6）。
+ */
+export declare const SUCCESS_STATUS = "SUCCESS";
+export declare const NOT_IMPLEMENTED_STATUS = "NOT_IMPLEMENTED";
+export declare const INVALID_INPUT_STATUS = "INVALID_INPUT";
+export declare const SERIALIZATION_ERROR_STATUS = "RESPONSE_SERIALIZATION_ERROR";
+export declare const UNKNOWN_ERROR_STATUS = "UNKNOWN_ERROR";
+/** 通用兜底文案（仅在 `error.message` 为空时使用） */
+export declare const DEFAULT_USER_MESSAGE = "\u8BF7\u6C42\u5931\u8D25";
+export declare const DEFAULT_SYSTEM_MESSAGE = "\u7CFB\u7EDF\u9519\u8BEF";
+export interface ResponseEnvelope<T> {
+    status: string;
+    message: string;
+    data: T;
+}
+export declare function createSuccessResponse<T>(data: T): ResponseEnvelope<T>;
+export declare function createErrorResponse(status: string, message: string): ResponseEnvelope<null>;
+/**
+ * 数据层错误分类器（资源包里带 `classifyError` 的值的裸函数形态）。
+ *
+ * 资源包（`resources` 槽位返回值）里任何提供 `classifyError` 的值都会被用作响应错误分类；
+ * 都没有时错误落 `UNKNOWN_ERROR` 兜底。
+ */
+export type ErrorClassifier = (error: unknown) => SystemError | null;
+export interface ResponseCoreOptions {
+    /** Prisma / 数据层错误分类（缺省 = 不做数据层分类） */
+    classifyError?: ErrorClassifier;
+}
+export declare function registerResponse(app: FastifyInstance, options?: ResponseCoreOptions): void;
+//# sourceMappingURL=response.d.ts.map

package/output/app/core/response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response.d.ts","sourceRoot":"","sources":["../../../source/app/core/response.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,WAAW,EAAa,MAAM,cAAc,CAAA;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;GAUG;AAEH,eAAO,MAAM,cAAc,YAAY,CAAA;AACvC,eAAO,MAAM,sBAAsB,oBAAoB,CAAA;AACvD,eAAO,MAAM,oBAAoB,kBAAkB,CAAA;AACnD,eAAO,MAAM,0BAA0B,iCAAiC,CAAA;AACxE,eAAO,MAAM,oBAAoB,kBAAkB,CAAA;AAEnD,uCAAuC;AACvC,eAAO,MAAM,oBAAoB,6BAAS,CAAA;AAC1C,eAAO,MAAM,sBAAsB,6BAAS,CAAA;AAE5C,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,CAAC,CAAA;CACR;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,gBAAgB,CAAC,CAAC,CAAC,CAErE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAE3F;AAsBD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,OAAO,KAAK,WAAW,GAAG,IAAI,CAAA;AAEpE,MAAM,WAAW,mBAAmB;IAClC,qCAAqC;IACrC,aAAa,CAAC,EAAE,eAAe,CAAA;CAChC;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,GAAE,mBAAwB,GAAG,IAAI,CAyD9F"}

package/output/app/core/response.js

@@ -0,0 +1,89 @@
+import { hasZodFastifySchemaValidationErrors, isResponseSerializationError } from 'fastify-type-provider-zod';
+import { SystemError, UserError } from '../errors.js';
+/**
+ * core `response`（设计 §5.1 / §8，错误契约 D7）——**框架内置、锁定、不可替换/修改**。
+ *
+ * - 成功信封 `{ status: 'SUCCESS', message: 'ok', data }`（由 `preSerialization` 统一包裹）。
+ * - 错误信封 `{ status: <错误码字符串>, message, data: null }`。
+ * - `setErrorHandler` 固定分支：`UserError`→400（`error.status` 字面量）/ `SystemError`→500 /
+ *   zod→400 / serde→500 / 数据层（资源包的 `classifyError`）→500 / 未知→500；**禁止按 `error.type` 细分**。
+ * - `setNotFoundHandler` → 404 + `NOT_IMPLEMENTED`（落 `warn`，文案对齐 expense/notice）。
+ * - 错误日志分级：`UserError` / zod → `warn`，其余 → `error`（带 stack）。
+ * - **错误只给稳定码**（`status` 放错误码字符串），文案不归框架（由前端 / i18n 决定，§10-6）。
+ */
+export const SUCCESS_STATUS = 'SUCCESS';
+export const NOT_IMPLEMENTED_STATUS = 'NOT_IMPLEMENTED';
+export const INVALID_INPUT_STATUS = 'INVALID_INPUT';
+export const SERIALIZATION_ERROR_STATUS = 'RESPONSE_SERIALIZATION_ERROR';
+export const UNKNOWN_ERROR_STATUS = 'UNKNOWN_ERROR';
+/** 通用兜底文案（仅在 `error.message` 为空时使用） */
+export const DEFAULT_USER_MESSAGE = '请求失败';
+export const DEFAULT_SYSTEM_MESSAGE = '系统错误';
+export function createSuccessResponse(data) {
+    return { status: SUCCESS_STATUS, message: 'ok', data };
+}
+export function createErrorResponse(status, message) {
+    return { status, message, data: null };
+}
+function isEnvelope(payload) {
+    return (typeof payload === 'object' &&
+        payload !== null &&
+        typeof payload.status === 'string' &&
+        typeof payload.message === 'string' &&
+        'data' in payload);
+}
+function resolveMessage(error) {
+    const explicit = typeof error.message === 'string' ? error.message : '';
+    return explicit || DEFAULT_SYSTEM_MESSAGE;
+}
+export function registerResponse(app, options = {}) {
+    // 成功信封：统一包裹非信封载荷（错误 / 404 已自带信封，不会被二次包裹）
+    app.addHook('preSerialization', (_request, _reply, payload, done) => {
+        if (payload === undefined || payload === null || isEnvelope(payload)) {
+            done(null, payload);
+            return;
+        }
+        done(null, createSuccessResponse(payload));
+    });
+    app.setNotFoundHandler((request, reply) => {
+        request.log.warn({ url: request.url }, '[response] route not found');
+        return reply
+            .code(404)
+            .send(createErrorResponse(NOT_IMPLEMENTED_STATUS, `接口不存在：${request.method} ${request.url}`));
+    });
+    app.setErrorHandler((error, request, reply) => {
+        // ① UserError → 400
+        if (UserError.is(error)) {
+            request.log.warn({ err: error }, '[response] user error');
+            return reply.code(error.status).send(createErrorResponse(error.type, resolveMessage(error)));
+        }
+        // ② SystemError → 500
+        if (SystemError.is(error)) {
+            request.log.error({ err: error }, '[response] system error');
+            return reply.code(error.status).send(createErrorResponse(error.type, resolveMessage(error)));
+        }
+        // ③ zod 校验失败 → 400
+        if (hasZodFastifySchemaValidationErrors(error)) {
+            request.log.warn({ err: error }, '[response] zod validation error');
+            return reply.code(400).send(createErrorResponse(INVALID_INPUT_STATUS, error.message));
+        }
+        // ④ 响应序列化失败 → 500
+        if (isResponseSerializationError(error)) {
+            request.log.error({ err: error }, '[response] response serialization error');
+            return reply.code(500).send(createErrorResponse(SERIALIZATION_ERROR_STATUS, error.message));
+        }
+        // ⑤ 数据层（Prisma 等）分类 → 500
+        const databaseError = options.classifyError?.(error);
+        if (databaseError) {
+            request.log.error({ err: error }, '[response] database error');
+            return reply
+                .code(500)
+                .send(createErrorResponse(databaseError.type, resolveMessage(databaseError)));
+        }
+        // ⑥ 未知 → 500
+        request.log.error({ err: error }, '[response] unknown error');
+        const cause = error;
+        const message = typeof cause.message === 'string' && cause.message ? cause.message : DEFAULT_SYSTEM_MESSAGE;
+        return reply.code(500).send(createErrorResponse(UNKNOWN_ERROR_STATUS, message));
+    });
+}

package/output/app/define-server.negative-cases.d.ts

@@ -0,0 +1,32 @@
+import type { ServerConfig } from './types.js';
+/** #1 `resources` 看不到 `config` */
+export declare function resourcesCannotSeeConfig(): void;
+/** #2 `resources` 看不到 `services` */
+export declare function resourcesCannotSeeServices(): void;
+/** #3 `config` 看不到 `services` */
+export declare function configCannotSeeServices(): void;
+/** #4 `services` 看不到 `services`（禁 service 互依） */
+export declare function servicesCannotSeeServices(): void;
+/** #5 `routers` 看不到 `resources`（禁绕层直连数据层） */
+export declare function routersCannotSeeResources(): void;
+/** #6 `routers` 看不到 `config` */
+export declare function routersCannotSeeConfig(): void;
+/** #7 service 值声明 `dependsOn` → 该值塌成 `never` */
+export declare function serviceValueCannotDeclareDependsOn(): void;
+/** #8 service 值是原始类型 → 被拒（防把配置塞进 services） */
+export declare function serviceValueCannotBePrimitive(): void;
+/** #9 `startServer` 只接受品牌产物，裸 `ServerConfig` 编译失败 */
+export declare function startServerRejectsBareConfig(bare: ServerConfig<unknown, unknown, unknown>): void;
+/** #10 `app.version` 必填 */
+export declare function appVersionIsRequired(): void;
+/** #11 `cache: false` 静态关闭：键被 `Live<>` 从资源视图剔除 */
+export declare function staticallyDisabledResourceIsRemoved(): void;
+/** #12 `config` 看不到 `app` */
+export declare function configCannotSeeApp(): void;
+/** #13 `middlewares` 看不到 `resources`（中间件禁直连数据层） */
+export declare function middlewaresCannotSeeResources(): void;
+/** #14 `middlewares` 看不到 `env` */
+export declare function middlewaresCannotSeeEnv(): void;
+/** #15 `services` 看不到 `env`（服务层禁读 env） */
+export declare function servicesCannotSeeEnv(): void;
+//# sourceMappingURL=define-server.negative-cases.d.ts.map

package/output/app/define-server.negative-cases.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-server.negative-cases.d.ts","sourceRoot":"","sources":["../../source/app/define-server.negative-cases.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAgB9C,kCAAkC;AAClC,wBAAgB,wBAAwB,IAAI,IAAI,CAU/C;AAED,oCAAoC;AACpC,wBAAgB,0BAA0B,IAAI,IAAI,CAUjD;AAED,iCAAiC;AACjC,wBAAgB,uBAAuB,IAAI,IAAI,CAa9C;AAED,iDAAiD;AACjD,wBAAgB,yBAAyB,IAAI,IAAI,CAahD;AAED,6CAA6C;AAC7C,wBAAgB,yBAAyB,IAAI,IAAI,CAYhD;AAED,gCAAgC;AAChC,wBAAgB,sBAAsB,IAAI,IAAI,CAY7C;AAED,gDAAgD;AAChD,wBAAgB,kCAAkC,IAAI,IAAI,CAUzD;AAED,8CAA8C;AAC9C,wBAAgB,6BAA6B,IAAI,IAAI,CAUpD;AAED,qDAAqD;AACrD,wBAAgB,4BAA4B,CAAC,IAAI,EAAE,YAAY,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,IAAI,CAGhG;AAED,2BAA2B;AAC3B,wBAAgB,oBAAoB,IAAI,IAAI,CAU3C;AAED,kDAAkD;AAClD,wBAAgB,mCAAmC,IAAI,IAAI,CAa1D;AAED,6BAA6B;AAC7B,wBAAgB,kBAAkB,IAAI,IAAI,CAazC;AAED,mDAAmD;AACnD,wBAAgB,6BAA6B,IAAI,IAAI,CAapD;AAED,kCAAkC;AAClC,wBAAgB,uBAAuB,IAAI,IAAI,CAa9C;AAED,0CAA0C;AAC1C,wBAAgB,oBAAoB,IAAI,IAAI,CAa3C"}