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

package/output/core/modules/request-id/index.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';
+const REQUEST_ID_LOG_LABEL = 'requestId';
+/** 归一化入站 header 值（设计 §5.1）：数组取首个；**trim 后为空视为缺失**（返回 `undefined`） */
+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/core/modules/response/index.d.ts

@@ -0,0 +1,50 @@
+import type { FastifyInstance } from 'fastify';
+import type { ErrorClassifier } from '../../types.js';
+declare const SUCCESS_STATUS = "SUCCESS";
+/** 成功信封的固定 `message`（错误信封的 `message` 是业务文案，不固定） */
+declare const SUCCESS_MESSAGE = "ok";
+/**
+ * 响应信封（成功与错误同一形状，只有 `data` 与 `status` 的含义不同）。
+ *
+ * ## `status` 为什么是字面量 `'SUCCESS'` 而不是 `string`
+ *
+ * 类型必须**不宽于**运行时 schema，否则它就不是一个可用的类型：
+ * 框架的 `responseSchema()` 把成功响应声明为 `z.enum(['SUCCESS'])`（即 `'SUCCESS'`
+ * 字面量）。如果这里写 `status: string`，路由 handler 返回 `createSuccessResponse(x)`
+ * 就**不满足自己声明的响应 schema**——类型检查要么报错、要么被上游 `as` 掉。
+ *
+ * 各仓遇到这个矛盾时会自己再写一份「更窄的同名函数」（account 一直有一份），
+ * 结果同一个信封在四个仓里有四个实现，而差异只在一个类型宽度上。宽度对齐后
+ * 那份副本就没有存在理由了。
+ *
+ * 错误信封用 {@link createErrorResponse}，它的 `status` 是错误码（`string`）。
+ * 两种信封共用一个接口，所以 `ResponseEnvelope.status` 的类型是
+ * `'SUCCESS' | string`——对它求值为 `string`，但 `createSuccessResponse` 的返回类型
+ * 单独收窄为 {@link SuccessResponse}，路由 handler 拿到的就是字面量。
+ */
+export interface ResponseEnvelope<T> {
+    status: string;
+    message: string;
+    data: T;
+}
+/** 成功信封：`status` / `message` 都是固定字面量（与 `responseSchema()` 一致） */
+export interface SuccessResponse<T> {
+    status: typeof SUCCESS_STATUS;
+    message: typeof SUCCESS_MESSAGE;
+    data: T;
+}
+export declare function createSuccessResponse<T>(data: T): SuccessResponse<T>;
+export declare function createErrorResponse(status: string, message: string): ResponseEnvelope<null>;
+/**
+ * 资源错误分类器（单一来源：`types.ts`）。
+ *
+ * **每个资源注册自己的分类器**（一个资源一个，各管各的错误域）；由服务仓在 `resources(ctx)` 里
+ * 通过 `ctx.registerClassifyError` 注册；未注册时错误落 `UNKNOWN_ERROR` 兜底。
+ */
+export type { ErrorClassifier };
+export interface ResponseCoreOptions {
+    /** 资源错误分类（各资源经 `ctx.registerClassifyError` 注册；缺省 = 不做资源错误分类） */
+    classifyResourceError?: ErrorClassifier;
+}
+export declare function registerResponse(app: FastifyInstance, options?: ResponseCoreOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/output/core/modules/response/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/response/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAA;AA2BrD,QAAA,MAAM,cAAc,YAAY,CAAA;AAShC,mDAAmD;AACnD,QAAA,MAAM,eAAe,OAAO,CAAA;AAE5B;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,gBAAgB,CAAC,CAAC;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,EAAE,CAAC,CAAA;CACR;AAED,iEAAiE;AACjE,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,MAAM,EAAE,OAAO,cAAc,CAAA;IAC7B,OAAO,EAAE,OAAO,eAAe,CAAA;IAC/B,IAAI,EAAE,CAAC,CAAA;CACR;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,eAAe,CAAC,CAAC,CAAC,CAEpE;AAED,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAE3F;AAsBD;;;;;GAKG;AACH,YAAY,EAAE,eAAe,EAAE,CAAA;AAE/B,MAAM,WAAW,mBAAmB;IAClC,gEAAgE;IAChE,qBAAqB,CAAC,EAAE,eAAe,CAAA;CACxC;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,GAAE,mBAAwB,GAAG,IAAI,CAyD9F"}

package/output/core/modules/response/index.js

@@ -0,0 +1,102 @@
+import { SystemError, UserError } from '@taicode/common-base';
+import { hasZodFastifySchemaValidationErrors, isResponseSerializationError } from 'fastify-type-provider-zod';
+/**
+ * core `response`（设计 §5.1 / §8，错误契约 D7）——**框架内置、锁定、不可替换/修改**。
+ *
+ * - 成功信封 `{ status: 'SUCCESS', message: 'ok', data }`（由 `preSerialization` 统一包裹）。
+ * - 错误信封 `{ status: <错误码字符串>, message, data: null }`。
+ * - `setErrorHandler` 固定分支：`UserError`→400 / `SystemError`→500 /
+ *   zod→400 / serde→500 / 资源（各资源 `ctx.registerClassifyError` 注册的分类器）→500 / 未知→500；**禁止按 `error.type` 细分**。
+ * - `setNotFoundHandler` → 404 + `NOT_IMPLEMENTED`（落 `warn`，文案对齐 expense/notice）。
+ * - 错误日志分级：`UserError` / zod → `warn`，其余 → `error`（带 stack）。
+ * - **错误只给稳定码**（`status` 放错误码字符串），文案不归框架（由前端 / i18n 决定，§10-6）。
+ *
+ * 错误类型本身**不在这里定义**：`UserError` / `SystemError` 复用 `@taicode/common-base` 的
+ * 单一来源（连 `Symbol.for` 品牌都同名，故 base 抛出的同类错误同样被识别），框架只负责
+ * **状态码映射**与响应信封，不重复实现错误类。
+ */
+/**
+ * 固定状态码映射（D7）：`UserError`→400 / `SystemError`→500。
+ *
+ * 映射写在框架侧而非错误类上（base 的类不带 `status`）。判定一律走 `is()` 品牌守卫，
+ * **不用 `instanceof`**——跨包 / 编译后 / 原型链丢失都仍然可靠；**禁止按 `error.type` 细分**。
+ */
+const USER_ERROR_STATUS = 400;
+const SYSTEM_ERROR_STATUS = 500;
+const SUCCESS_STATUS = 'SUCCESS';
+const NOT_IMPLEMENTED_STATUS = 'NOT_IMPLEMENTED';
+const INVALID_INPUT_STATUS = 'INVALID_INPUT';
+const SERIALIZATION_ERROR_STATUS = 'RESPONSE_SERIALIZATION_ERROR';
+const UNKNOWN_ERROR_STATUS = 'UNKNOWN_ERROR';
+/** 通用兜底文案（仅在 `error.message` 为空时使用） */
+const DEFAULT_SYSTEM_MESSAGE = '系统错误';
+/** 成功信封的固定 `message`（错误信封的 `message` 是业务文案，不固定） */
+const SUCCESS_MESSAGE = 'ok';
+export function createSuccessResponse(data) {
+    return { status: SUCCESS_STATUS, message: SUCCESS_MESSAGE, 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(USER_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(SYSTEM_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));
+        }
+        // ⑤ 资源错误（各资源注册的分类器依次认领）→ 500
+        const resourceError = options.classifyResourceError?.(error);
+        if (resourceError) {
+            request.log.error({ err: error }, '[response] resource error');
+            return reply
+                .code(500)
+                .send(createErrorResponse(resourceError.type, resolveMessage(resourceError)));
+        }
+        // ⑥ 未知 → 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/{schema/index.d.ts → core/modules/schema/builders.d.ts}

@@ -172,6 +172,13 @@ interface RouterSchema extends FastifySchema {
     operationId: string;
     description: string;
 }
+/**
+ * 路由 schema 工厂：**四项元信息全部必填**，不留默认值。
+ *
+ * `operationId` / `summary` / `description` / `tags` 是权限目录与文档可读性的下限，
+ * core 的 `installRouteSchemaGuard` 会对运行时缺失逐项报错；这里在类型层面就要求写全，
+ * 避免「先给个默认值让它跑起来，回头再补」——补是不会发生的。
+ */
 export declare function routerSchema<T extends RouterSchema>(schema: T & RouterSchema): T & RouterSchema;
 export {};
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=builders.d.ts.map

package/output/core/modules/schema/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/schema/builders.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AACzC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AA2B5C;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;;;;;;;;;;;;;kBAMlF;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;kBAKxD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,kCAE/B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;kBAKvD;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;;;;;;;;;;kBAMvF;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;mBAK7D;AAED;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;;;;;;;;;kBAMjE;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;mBAKjE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;;;;;;;;;;;;;kBAMtF;AAED;;;;;GAKG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC;;;kBAK5D;AAGD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;;;;kBAMlF;AAED,wBAAgB,cAAc,CAAC,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,SAAS,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;;;;;;;;;;;;;;;;;;EAMvG;AAED,UAAU,YAAa,SAAQ,aAAa;IAC1C,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,WAAW,EAAE,MAAM,CAAA;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,CAAC,SAAS,YAAY,EAAE,MAAM,EAAE,CAAC,GAAG,YAAY,GAAG,CAAC,GAAG,YAAY,CAO/F"}

package/output/{schema/index.js → core/modules/schema/builders.js}

@@ -167,14 +167,17 @@ export function responseSchema(t, u, e) {
         '500': responseDataSchema(z.null(), e),
     };
 }
+/**
+ * 路由 schema 工厂：**四项元信息全部必填**，不留默认值。
+ *
+ * `operationId` / `summary` / `description` / `tags` 是权限目录与文档可读性的下限，
+ * core 的 `installRouteSchemaGuard` 会对运行时缺失逐项报错；这里在类型层面就要求写全，
+ * 避免「先给个默认值让它跑起来，回头再补」——补是不会发生的。
+ */
 export function routerSchema(schema) {
     // 验证必需字段
     if (!schema.operationId) {
         throw new Error('routerSchema requires operationId');
     }
-    // 如果没有提供 tags，设置默认值
-    if (!schema.tags) {
-        schema.tags = ['默认'];
-    }
     return { ...schema };
 }

package/output/core/modules/schema/index.d.ts

@@ -0,0 +1,34 @@
+import type { FastifyInstance } from 'fastify';
+/**
+ * core `schema`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * 三部分：
+ * 1. `registerSchema`：装配 `fastify-type-provider-zod` 的 validator / serializer compiler；
+ * 2. `installRouteSchemaGuard`：**强制每条路由声明 schema**（`operationId` / `summary` /
+ *    `description` / `tags` 缺一即启动失败）；
+ * 3. `builders`：业务侧构造路由 schema 的约定工厂（`responseSchema` / `routerSchema` / 分页等）。
+ */
+export declare function registerSchema(app: FastifyInstance): void;
+/**
+ * 强制所有业务路由提供 schema（**注册处即失败**，不给「先跑起来再补」的口子）。
+ *
+ * 为什么必须硬性：
+ *
+ * - OpenAPI 文档是**权限目录的唯一来源**（`auth` 的权限自注册直接读文档）。一条路由没
+ *   `operationId`，它就在权限系统里**不存在**——表现为「接口永远判不过」，且没有任何报错。
+ *   这种失败必须发生在启动期，不能留到线上。
+ * - `summary` / `description` / `tags` 是文档可读性的下限；没有它们的文档等于没有文档。
+ *
+ * ## 为什么没有「声明一个标记就不检查」的入口
+ *
+ * 守卫要防的就是「路由活着、权限系统里却没有」。任何**按路由声明**的布尔值能放宽它，
+ * 都等于把这个洞重新打开，而且是**显式地**打开——比遗漏更危险，因为它看起来像设计。
+ *
+ * 所以只有两类被排除，且全是方法级的结构事实，路由无法参与决定：
+ * `HEAD`（GET 自动派生）与 `OPTIONS`（CORS 预检）。
+ *
+ * 也没有「不进文档」的隐藏开关：文档就是权限目录，两者不能有分歧。
+ */
+export declare function installRouteSchemaGuard(app: FastifyInstance): void;
+export * from './builders.js';
+//# sourceMappingURL=index.d.ts.map

package/output/core/modules/schema/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/schema/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAiB,MAAM,SAAS,CAAA;AAE7D;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAMzD;AAeD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAqBlE;AAED,cAAc,eAAe,CAAA"}

package/output/core/modules/schema/index.js

@@ -0,0 +1,62 @@
+import { serializerCompiler, validatorCompiler } from 'fastify-type-provider-zod';
+/**
+ * core `schema`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * 三部分：
+ * 1. `registerSchema`：装配 `fastify-type-provider-zod` 的 validator / serializer compiler；
+ * 2. `installRouteSchemaGuard`：**强制每条路由声明 schema**（`operationId` / `summary` /
+ *    `description` / `tags` 缺一即启动失败）；
+ * 3. `builders`：业务侧构造路由 schema 的约定工厂（`responseSchema` / `routerSchema` / 分页等）。
+ */
+export function registerSchema(app) {
+    app.setValidatorCompiler(validatorCompiler);
+    app.setSerializerCompiler(serializerCompiler);
+}
+/** 每条路由必须声明的 schema 字段（与权限目录同源：OpenAPI 文档就是权限目录的唯一来源） */
+const REQUIRED_SCHEMA_FIELDS = ['operationId', 'summary', 'description', 'tags'];
+/**
+ * 被排除在外的**方法**（结构事实，不是路由声明）。
+ *
+ * - `HEAD`：Fastify 为 GET 自动派生，schema 与 GET 完全相同，重复校验无意义；
+ * - `OPTIONS`：CORS 预检（`@fastify/cors` 注册的 `OPTIONS *`），永远不是业务操作。
+ */
+const NON_OPERATION_METHODS = new Set(['HEAD', 'OPTIONS']);
+/**
+ * 强制所有业务路由提供 schema（**注册处即失败**，不给「先跑起来再补」的口子）。
+ *
+ * 为什么必须硬性：
+ *
+ * - OpenAPI 文档是**权限目录的唯一来源**（`auth` 的权限自注册直接读文档）。一条路由没
+ *   `operationId`，它就在权限系统里**不存在**——表现为「接口永远判不过」，且没有任何报错。
+ *   这种失败必须发生在启动期，不能留到线上。
+ * - `summary` / `description` / `tags` 是文档可读性的下限；没有它们的文档等于没有文档。
+ *
+ * ## 为什么没有「声明一个标记就不检查」的入口
+ *
+ * 守卫要防的就是「路由活着、权限系统里却没有」。任何**按路由声明**的布尔值能放宽它，
+ * 都等于把这个洞重新打开，而且是**显式地**打开——比遗漏更危险，因为它看起来像设计。
+ *
+ * 所以只有两类被排除，且全是方法级的结构事实，路由无法参与决定：
+ * `HEAD`（GET 自动派生）与 `OPTIONS`（CORS 预检）。
+ *
+ * 也没有「不进文档」的隐藏开关：文档就是权限目录，两者不能有分歧。
+ */
+export function installRouteSchemaGuard(app) {
+    app.addHook('onRoute', (routeOptions) => {
+        const methods = Array.isArray(routeOptions.method) ? routeOptions.method : [routeOptions.method];
+        if (methods.every((method) => NON_OPERATION_METHODS.has(method))) {
+            return;
+        }
+        const schema = routeOptions.schema;
+        const missing = REQUIRED_SCHEMA_FIELDS.filter((field) => {
+            const value = schema?.[field];
+            return value === undefined || value === null || (Array.isArray(value) ? value.length === 0 : value === '');
+        });
+        if (missing.length > 0) {
+            throw new Error(`[schema] 路由 ${methods.join(',')} ${routeOptions.url} 缺少 schema.${missing.join(' / schema.')}：` +
+                '所有业务路由都必须用 `routerSchema({ operationId, summary, description, tags, ... })` 声明，' +
+                '权限目录直接由 OpenAPI 文档生成，未声明的路由在权限系统里不存在');
+        }
+    });
+}
+export * from './builders.js';

package/output/core/modules/schema/index.test.d.ts

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

package/output/core/modules/schema/index.test.d.ts.map

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

package/output/core/modules/schema/index.test.js

@@ -0,0 +1,55 @@
+import Fastify from 'fastify';
+import { describe, expect, it } from 'vitest';
+import { installRouteSchemaGuard, registerSchema } from './index.js';
+const FULL_SCHEMA = {
+    operationId: 'listUser',
+    summary: '列表',
+    description: '分页列出用户',
+    tags: ['用户'],
+};
+function buildApp() {
+    const app = Fastify();
+    registerSchema(app);
+    installRouteSchemaGuard(app);
+    return app;
+}
+describe('installRouteSchemaGuard', () => {
+    it('声明完整 schema 的路由通过（含 Fastify 自动派生的 HEAD）', async () => {
+        const app = buildApp();
+        app.get('/user', { schema: FULL_SCHEMA }, async () => ({ ok: true }));
+        await expect(app.ready()).resolves.toBeDefined();
+        await app.close();
+    });
+    it('缺少 schema 时在注册处即抛错（不等启动）', async () => {
+        const app = buildApp();
+        expect(() => app.get('/user', async () => ({ ok: true }))).toThrow(/GET \/user 缺少 schema\.operationId/);
+        await app.close();
+    });
+    it('缺少 summary / description / tags 时逐个列出', async () => {
+        const app = buildApp();
+        expect(() => app.post('/user', { schema: { operationId: 'createUser' } }, async () => ({ ok: true }))).toThrow(/schema\.summary \/ schema\.description \/ schema\.tags/);
+        await app.close();
+    });
+    it('OPTIONS 按方法豁免（CORS 预检不是业务操作）', async () => {
+        const app = buildApp();
+        app.options('/user', async () => ({}));
+        await expect(app.ready()).resolves.toBeDefined();
+        await app.close();
+    });
+    it('插件内注册的路由同样受约束（错误冒泡成启动失败）', async () => {
+        const app = buildApp();
+        let caught;
+        try {
+            await app.register(async (instance) => {
+                instance.get('/nested', async () => ({ ok: true }));
+            });
+            await app.ready();
+        }
+        catch (error) {
+            caught = error;
+        }
+        expect(caught).toBeInstanceOf(Error);
+        expect(caught.message).toMatch(/GET \/nested 缺少 schema/);
+        await app.close();
+    });
+});

package/output/core/modules/system-routes/index.d.ts

@@ -0,0 +1,15 @@
+import type { AppIdentity, AppInstance } from '../../types.js';
+export interface SystemRoutesOptions {
+    /** 身份块（`service` / `title` / `version`）：`GET /` 与 `/system/info` 从这里派生 */
+    identity: AppIdentity;
+    /** 已构造的 services 实体（`ctx.services`）：健康检查遍历其可选 `health()` */
+    services: Record<string, unknown>;
+    /** 取**已加载**配置中某个键的访问器（请求期惰性现读；出 spec 路径不得调用） */
+    readConfig: (key: string) => unknown;
+}
+/**
+ * 注册框架内置系统路由（5 个端点）。由 `registerSystemRoutesStep` 在 `server.routers(...)` **之前**调用，
+ * 保证框架路由先就位。
+ */
+export declare function registerSystemRoutes(app: AppInstance, options: SystemRoutesOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/output/core/modules/system-routes/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/system-routes/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAmB,MAAM,gBAAgB,CAAA;AA4K/E,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,QAAQ,EAAE,WAAW,CAAA;IACrB,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,gDAAgD;IAChD,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACrC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB,GAAG,IAAI,CA2DzF"}