@taicode/common-server 4.0.0-beta.2 → 4.0.0-beta.4

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

@@ -0,0 +1,21 @@
+import type { ConfigEnv } from '../../env.js';
+import type { FastifyInstance } from 'fastify';
+/**
+ * core `cookie`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * `@fastify/cookie`；cookie 的 domain 从 `ctx.readConfig('server')` 取（**请求期惰性现读**，刷新后即生效），
+ * cookie 名由调用方（`auth` 中间件）显式给出；显式设 `sameSite`（默认 `lax`）与 `secure`
+ * （默认 `ENV === 'production'`）；注册在 `auth` 之前（框架内置序），故 `auth` 读 cookie 无需用户保证。
+ */
+export interface AuthCookieOptions {
+    maxAge?: number;
+    path?: string;
+    domain?: string;
+}
+export interface CookieCoreOptions {
+    env: ConfigEnv;
+    /** 取最新配置中某个键的访问器（**每次调用现读**，不得缓存返回值） */
+    readConfig: (key: string) => unknown;
+}
+export declare function registerCookie(app: FastifyInstance, options: CookieCoreOptions): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/cookie/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,eAAe,EAAgB,MAAM,SAAS,CAAA;AAE5D;;;;;;GAMG;AAEH,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAMD,MAAM,WAAW,iBAAiB;IAChC,GAAG,EAAE,SAAS,CAAA;IACd,wCAAwC;IACxC,UAAU,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACrC;AAOD,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,EAAE,OAAO,EAAE,iBAAiB,GAAG,IAAI,CAerF"}

package/output/{app/core/cookie.js → core/modules/cookie/index.js}

@@ -1,11 +1,6 @@
 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) {
+function resolveCookieDomain(server) {
     return server?.domain;
 }
 export function registerCookie(app, options) {

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

@@ -0,0 +1,4 @@
+import type { AppIdentity } from '../../types.js';
+export declare function attachServerIdentity(app: unknown, identity: AppIdentity): void;
+export declare function readServerIdentity(app: unknown): AppIdentity | undefined;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/identity/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AAWjD,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 → core/modules/identity/index.js}

@@ -5,7 +5,7 @@
  * （可见性按需收窄），框架内置单元（`auth` 权限自注册 / `rateLimit` 前缀）需要 `service` /
  * `version` 时从这里读。
  */
-export const SERVER_IDENTITY = Symbol.for('taicode.server/identity');
+const SERVER_IDENTITY = Symbol.for('taicode.server/identity');
 export function attachServerIdentity(app, identity) {
     Object.defineProperty(app, SERVER_IDENTITY, { value: identity, enumerable: false, configurable: true });
 }

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

@@ -0,0 +1,5 @@
+import type { ConfigEnv } from '../../env.js';
+import type { FastifyServerOptions } from 'fastify';
+/** 构造 Fastify 的 logger 选项 */
+export declare function createLoggerOptions(env: ConfigEnv): FastifyServerOptions['logger'];
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/logging/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAC7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAsBnD,6BAA6B;AAC7B,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,SAAS,GAAG,oBAAoB,CAAC,QAAQ,CAAC,CAQlF"}

package/output/{app/core/logging.js → core/modules/logging/index.js}

@@ -1,4 +1,4 @@
-import { DEFAULT_LOG_LEVEL } from '../env.js';
+import { DEFAULT_LOG_LEVEL } from '../../env.js';
 /**
  * core `logging`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
  *
@@ -6,7 +6,7 @@ import { DEFAULT_LOG_LEVEL } from '../env.js';
  * 开关随 `CoreOptions` 一并删除，日志始终开启，不再由 `debug` 控制。
  */
 /** 默认 `redact` 路径（设计 §5.1） */
-export const LOG_REDACT_PATHS = [
+const LOG_REDACT_PATHS = [
     'authorization',
     'cookie',
     'set-cookie',

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

@@ -0,0 +1,7 @@
+import type { FastifyInstance } from 'fastify';
+export interface OpenApiCoreOptions {
+    title: string;
+    version: string;
+}
+export declare function registerOpenApi(app: FastifyInstance, options: OpenApiCoreOptions): Promise<void>;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/openapi/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAgB9C,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,CA4BtG"}

package/output/{app/core/openapi.js → core/modules/openapi/index.js}

@@ -1,18 +1,19 @@
-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` 打印实际地址。
+ * 只做**文档生成**：`@fastify/swagger` 动态模式（不注册任何 HTTP 路由），`servers: [{ url: '/' }]`
+ * （构建期不依赖 env / DB）、`version` 取 `app.version`（必填，无默认）、`securitySchemes.bearerAuth`。
+ *
+ * 文档的**出口**在系统路由里（`GET /system/openapi`，见 `core/modules/system-routes`）：
+ * 文档是服务的一部分元信息，不该单独占一个顶层前缀；也不再需要 UI——
+ * `@scalar/fastify-api-reference` 已移除，各仓 console 用自己的 api-gen 消费 spec。
  */
-export const DOC_ROUTE_PREFIX = '/reference';
-export const DOC_SPEC_ROUTE = '/reference/openapi.json';
-export const OPENAPI_SPEC_VERSION = '3.0.3';
+/** OpenAPI 规范版本（固定，不可配置） */
+const OPENAPI_SPEC_VERSION = '3.0.3';
 export async function registerOpenApi(app, options) {
-    app.register(swagger, {
+    await app.register(swagger, {
         openapi: {
             openapi: OPENAPI_SPEC_VERSION,
             info: {
@@ -30,13 +31,11 @@ export async function registerOpenApi(app, options) {
         },
         transform: createJsonSchemaTransform({ skipList: [] }),
     });
-    app.register(scalar, { routePrefix: DOC_ROUTE_PREFIX });
-    // 确定性冲刷插件队列：让 swagger / scalar 的插件体在**任何路由注册之前**执行完——
-    // @fastify/swagger 经 fastify-plugin 在 root 上挂 `onRoute` 钩子，只有它先就位，
+    // 确定性冲刷插件队列：让 swagger 的 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');
+        app.log.info({ docPath: '/system/openapi' }, '[openapi] spec ready');
     });
 }

package/output/core/modules/permission-operations/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 权限操作提取（设计 §5.2）——**框架内置**。
+ *
+ * **唯一来源是 OpenAPI 文档**：`openapi` 已是 core 内置能力（§5.1），文档里的 `paths` 就是
+ * 本服务对外的完整操作面。权限目录直接从文档提取，**不再自建第二份路由注册表**——两套来源
+ * 必然漂移（`HEAD` / 前缀 / 插件路由的处理只要有一处不同就会对不上）。
+ *
+ * 文档里有什么就是什么：框架不给任何路由开「不进文档」的口子，因此也不存在
+ * 「路由活着、权限系统里却没有」的隐式状态。
+ *
+ * 目录元素形状（`{ operation, summary?, description?, tags? }`）与各仓原自写实现一致：
+ *
+ * - 缺 `operationId` 的条目（如 `parameters` / vendor 扩展）**跳过**；
+ * - 缺 `paths` / 空文档 → 返回 `[]`；
+ * - `summary` / `description` / `tags` 缺省分别归一为 `''` / `''` / `[]`。
+ *   （正常路径下不会发生：core 的 schema 守卫已在注册期强制四项齐全。）
+ */
+/** 单条权限操作（对齐 account `POST /permission/operation/register` 的 `operations` 元素） */
+export interface PermissionOperation {
+    operation: string;
+    summary: string;
+    description: string;
+    tags: string[];
+}
+export declare function extractPermissionOperations(openApiSpec: unknown): PermissionOperation[];
+//# sourceMappingURL=index.d.ts.map

package/output/core/modules/permission-operations/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/permission-operations/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,IAAI,EAAE,MAAM,EAAE,CAAA;CACf;AAeD,wBAAgB,2BAA2B,CAAC,WAAW,EAAE,OAAO,GAAG,mBAAmB,EAAE,CAoBvF"}

package/output/core/modules/permission-operations/index.js

@@ -0,0 +1,36 @@
+/**
+ * 权限操作提取（设计 §5.2）——**框架内置**。
+ *
+ * **唯一来源是 OpenAPI 文档**：`openapi` 已是 core 内置能力（§5.1），文档里的 `paths` 就是
+ * 本服务对外的完整操作面。权限目录直接从文档提取，**不再自建第二份路由注册表**——两套来源
+ * 必然漂移（`HEAD` / 前缀 / 插件路由的处理只要有一处不同就会对不上）。
+ *
+ * 文档里有什么就是什么：框架不给任何路由开「不进文档」的口子，因此也不存在
+ * 「路由活着、权限系统里却没有」的隐式状态。
+ *
+ * 目录元素形状（`{ operation, summary?, description?, tags? }`）与各仓原自写实现一致：
+ *
+ * - 缺 `operationId` 的条目（如 `parameters` / vendor 扩展）**跳过**；
+ * - 缺 `paths` / 空文档 → 返回 `[]`；
+ * - `summary` / `description` / `tags` 缺省分别归一为 `''` / `''` / `[]`。
+ *   （正常路径下不会发生：core 的 schema 守卫已在注册期强制四项齐全。）
+ */
+export function extractPermissionOperations(openApiSpec) {
+    // 出 spec 路径拿到的文档是未知形态；只按结构取字段，缺什么就跳过什么
+    const spec = (openApiSpec ?? {});
+    const operations = [];
+    for (const pathItem of Object.values(spec.paths ?? {})) {
+        for (const operation of Object.values(pathItem ?? {})) {
+            if (!operation?.operationId) {
+                continue;
+            }
+            operations.push({
+                operation: operation.operationId,
+                summary: operation.summary ?? '',
+                description: operation.description ?? '',
+                tags: operation.tags ?? [],
+            });
+        }
+    }
+    return operations;
+}

package/output/core/modules/permission-operations/index.test.d.ts

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

package/output/core/modules/permission-operations/index.test.d.ts.map

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

package/output/core/modules/permission-operations/index.test.js

@@ -0,0 +1,45 @@
+import { describe, expect, it } from 'vitest';
+import { extractPermissionOperations } from './index.js';
+describe('extractPermissionOperations', () => {
+    it('从 OpenAPI 文档的 paths 提取操作', () => {
+        const spec = {
+            paths: {
+                '/user': {
+                    get: { operationId: 'listUser', summary: '列表', description: '分页列出用户', tags: ['用户'] },
+                    post: { operationId: 'createUser', summary: '创建', description: '创建用户', tags: ['用户'] },
+                },
+            },
+        };
+        expect(extractPermissionOperations(spec)).toEqual([
+            { operation: 'listUser', summary: '列表', description: '分页列出用户', tags: ['用户'] },
+            { operation: 'createUser', summary: '创建', description: '创建用户', tags: ['用户'] },
+        ]);
+    });
+    it('跳过没有 operationId 的条目（parameters / vendor 扩展 / 未声明 schema 的路由）', () => {
+        const spec = {
+            paths: {
+                '/user': {
+                    parameters: [{ name: 'id', in: 'path' }],
+                    get: { operationId: 'listUser' },
+                },
+            },
+        };
+        expect(extractPermissionOperations(spec).map((item) => item.operation)).toEqual(['listUser']);
+    });
+    it('summary / description / tags 缺省归一为空值', () => {
+        const spec = { paths: { '/user': { get: { operationId: 'listUser' } } } };
+        expect(extractPermissionOperations(spec)).toEqual([
+            { operation: 'listUser', summary: '', description: '', tags: [] },
+        ]);
+    });
+    it('文档缺失或没有 paths 时返回空数组', () => {
+        expect(extractPermissionOperations(undefined)).toEqual([]);
+        expect(extractPermissionOperations(null)).toEqual([]);
+        expect(extractPermissionOperations({})).toEqual([]);
+        expect(extractPermissionOperations({ paths: {} })).toEqual([]);
+    });
+    it('只按 paths 取，文档里没有的条目不会凭空出现', () => {
+        const spec = { paths: { '/user': { get: { operationId: 'listUser' } } } };
+        expect(extractPermissionOperations(spec).map((item) => item.operation)).toEqual(['listUser']);
+    });
+});

package/output/{app/core/request-id.d.ts → core/modules/request-id/index.d.ts}

@@ -12,9 +12,6 @@ import type { FastifyInstance } from 'fastify';
  * `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;
@@ -33,4 +30,4 @@ export declare function createRequestIdOptions(): {
  * 入口 `request.id`、日志字段 `requestId`、响应 header 三处一致。
  */
 export declare function registerRequestId(app: FastifyInstance): void;
-//# sourceMappingURL=request-id.d.ts.map
+//# sourceMappingURL=index.d.ts.map

package/output/core/modules/request-id/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/request-id/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAE9C;;;;;;;;;;;GAWG;AAEH,eAAO,MAAM,iBAAiB,iBAAiB,CAAA;AAa/C,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 → core/modules/request-id/index.js}

@@ -12,9 +12,9 @@ import { randomUUID } from 'node:crypto';
  * `onRequest` 钩子在链路最前补齐归一，并同步 `request.id` / 日志字段 / 响应 header。
  */
 export const REQUEST_ID_HEADER = 'x-request-id';
-export const REQUEST_ID_LOG_LABEL = 'requestId';
+const REQUEST_ID_LOG_LABEL = 'requestId';
 /** 归一化入站 header 值（设计 §5.1）：数组取首个；**trim 后为空视为缺失**（返回 `undefined`） */
-export function normalizeInboundRequestId(inbound) {
+function normalizeInboundRequestId(inbound) {
     const value = Array.isArray(inbound) ? inbound[0] : inbound;
     if (typeof value !== 'string') {
         return undefined;

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

@@ -0,0 +1,22 @@
+import type { FastifyInstance } from 'fastify';
+import type { ErrorClassifier } from '../../types.js';
+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>;
+/**
+ * 资源错误分类器（单一来源：`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;AAoCrD,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,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/{app/core/response.js → core/modules/response/index.js}

@@ -1,24 +1,35 @@
+import { SystemError, UserError } from '@taicode/common-base';
 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 /
+ * - `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` 细分**。
  */
-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';
+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` 为空时使用） */
-export const DEFAULT_USER_MESSAGE = '请求失败';
-export const DEFAULT_SYSTEM_MESSAGE = '系统错误';
+const DEFAULT_SYSTEM_MESSAGE = '系统错误';
 export function createSuccessResponse(data) {
     return { status: SUCCESS_STATUS, message: 'ok', data };
 }
@@ -55,12 +66,12 @@ export function registerResponse(app, options = {}) {
         // ① 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)));
+            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(error.status).send(createErrorResponse(error.type, resolveMessage(error)));
+            return reply.code(SYSTEM_ERROR_STATUS).send(createErrorResponse(error.type, resolveMessage(error)));
         }
         // ③ zod 校验失败 → 400
         if (hasZodFastifySchemaValidationErrors(error)) {

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":"AAKA,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAmB,MAAM,gBAAgB,CAAA;AA+K/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,CAwDzF"}