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

package/output/core/env.test.js

@@ -0,0 +1,105 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { loadEnvironment } from './env.js';
+const ORIGINAL_ENV = { ...process.env };
+const ORIGINAL_CWD = process.cwd();
+const TEMP_ROOTS = [];
+afterEach(() => {
+    process.env = { ...ORIGINAL_ENV };
+    process.chdir(ORIGINAL_CWD);
+    for (const root of TEMP_ROOTS.splice(0)) {
+        rmSync(root, { recursive: true, force: true });
+    }
+    vi.resetModules();
+});
+/** 在临时目录里起一个项目根并写文件，然后切过去（`dotenv` 按 `process.cwd()` 解析相对路径） */
+function useTempProject(files) {
+    const root = mkdtempSync(join(tmpdir(), 'common-env-'));
+    TEMP_ROOTS.push(root);
+    for (const [name, content] of Object.entries(files)) {
+        writeFileSync(join(root, name), content);
+    }
+    process.chdir(root);
+}
+describe('loadEnvironment · runtime（工具进程 / startServer）', () => {
+    it('加载 .env.dev / .env / .env.local 三层，且逐层覆盖', () => {
+        useTempProject({
+            '.env.dev': 'PROBE_LAYER=dev\nPROBE_DEV_ONLY=yes\n',
+            '.env': 'PROBE_LAYER=env\n',
+            '.env.local': 'PROBE_LAYER=local\n',
+        });
+        delete process.env.PROBE_LAYER;
+        delete process.env.PROBE_DEV_ONLY;
+        loadEnvironment();
+        expect(process.env.PROBE_LAYER).toBe('local');
+        expect(process.env.PROBE_DEV_ONLY).toBe('yes');
+    });
+    it('不加载测试层（ENV 不是 test 时）', () => {
+        useTempProject({ '.env.test': 'PROBE_TEST_ONLY=yes\n' });
+        process.env.ENV = 'development';
+        delete process.env.PROBE_TEST_ONLY;
+        loadEnvironment();
+        expect(process.env.PROBE_TEST_ONLY).toBeUndefined();
+    });
+    it('ENV=test 时追加测试层', () => {
+        useTempProject({ '.env.test': 'PROBE_TEST_ONLY=yes\n' });
+        process.env.ENV = 'test';
+        delete process.env.PROBE_TEST_ONLY;
+        loadEnvironment();
+        expect(process.env.PROBE_TEST_ONLY).toBe('yes');
+    });
+    it('不给 ENV 时不兜底（运行期必须有明确身份）', () => {
+        useTempProject({});
+        delete process.env.ENV;
+        expect(loadEnvironment().ENV).toBe('');
+    });
+});
+describe('loadEnvironment · test（测试入口）', () => {
+    it('无条件加载测试层，不需要调用方先声明 ENV=test', () => {
+        useTempProject({ '.env.test': 'PROBE_TEST_ONLY=yes\n' });
+        process.env.ENV = 'development';
+        delete process.env.PROBE_TEST_ONLY;
+        loadEnvironment({ mode: 'test' });
+        expect(process.env.PROBE_TEST_ONLY).toBe('yes');
+    });
+    it('.env.test.local 覆盖 .env.test', () => {
+        useTempProject({
+            '.env.test': 'PROBE_LAYER=from-test\n',
+            '.env.test.local': 'PROBE_LAYER=from-local\n',
+        });
+        delete process.env.PROBE_LAYER;
+        loadEnvironment({ mode: 'test' });
+        expect(process.env.PROBE_LAYER).toBe('from-local');
+    });
+    it('没有任何 ENV 时兜底成 test', () => {
+        useTempProject({});
+        delete process.env.ENV;
+        expect(loadEnvironment({ mode: 'test' }).ENV).toBe('test');
+    });
+    it('已声明 ENV 时不被兜底改写', () => {
+        useTempProject({});
+        process.env.ENV = 'development';
+        expect(loadEnvironment({ mode: 'test' }).ENV).toBe('development');
+    });
+});
+describe('外部注入优先级（两种模式都必须成立）', () => {
+    it('runtime：.env 不覆盖进程已注入的值', async () => {
+        useTempProject({ '.env': 'PROBE_LAYER=from-file\n' });
+        // 同上：外部注入的快照在模块 import 时建立，重新 import 才能模拟真实注入时机
+        vi.resetModules();
+        process.env.PROBE_LAYER = 'from-process';
+        const fresh = await import('./env.js');
+        fresh.loadEnvironment();
+        expect(process.env.PROBE_LAYER).toBe('from-process');
+    });
+    it('test：线上注入的 ENV=production 不被 .env.test 顶掉（环境闸门因此仍会拒绝）', async () => {
+        useTempProject({ '.env.test': 'ENV=test\n' });
+        // EXTERNAL_ENV 是模块首次 import 时的快照，重新 import 才能模拟「进程启动前注入」
+        vi.resetModules();
+        process.env.ENV = 'production';
+        const fresh = await import('./env.js');
+        expect(fresh.loadEnvironment({ mode: 'test' }).ENV).toBe('production');
+    });
+});

package/output/core/modules/auth-provider/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `core/modules/auth-provider` 的出口：**只有类型，没有实现、没有地址**。
+ *
+ * 实现由业务服务提供（`createAuthMiddleware({ client })`）：框架不建 HTTP 客户端、
+ * 不认任何地址、不做签名、不管超时——见 `types.ts` 文件头与设计 §5.2.2。
+ *
+ * 提供方是**可替换**的：account 只是当前的主要实现，不是框架的预设。
+ */
+export type { AuthClient, AuthVerifyMetadata, AuthVerifyPayload, AuthVerifyResult, RegisterPermissionOperationsPayload, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/output/core/modules/auth-provider/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/auth-provider/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,YAAY,EACV,UAAU,EACV,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,mCAAmC,GACpC,MAAM,YAAY,CAAA"}

package/output/core/modules/auth-provider/index.js

@@ -0,0 +1,9 @@
+/**
+ * `core/modules/auth-provider` 的出口：**只有类型，没有实现、没有地址**。
+ *
+ * 实现由业务服务提供（`createAuthMiddleware({ client })`）：框架不建 HTTP 客户端、
+ * 不认任何地址、不做签名、不管超时——见 `types.ts` 文件头与设计 §5.2.2。
+ *
+ * 提供方是**可替换**的：account 只是当前的主要实现，不是框架的预设。
+ */
+export {};

package/output/core/modules/auth-provider/types.d.ts

@@ -0,0 +1,71 @@
+import type { PermissionOperation } from '../permission-operations/index.js';
+import type { AccessControl } from '../../type-augment.js';
+/**
+ * core `auth-provider` 集成层：**只有最小接口约束，没有实现、没有地址**。
+ *
+ * 鉴权提供方（Auth Provider）是**可替换**的——account 只是当前的主要实现之一，
+ * 任何能「校验凭证 + 接收权限目录」的系统都可以填进来（自建 IAM、OIDC 网关、
+ * 单点登录服务、甚至进程内的静态校验）。
+ *
+ * 为什么只留契约（设计 §5.2.2）：
+ *
+ * - 客户端的**构造**依赖业务侧才知道的东西——`serviceUrl`（来自配置 / 服务发现 /
+ *   私有网络）、端点路径（属于提供方的业务契约，不在 framework）、服务凭证、
+ *   以及项目自己的 `fetch` / 拦截器 / 超时 / 重试策略。框架猜不出来，也不该猜。
+ * - 所以框架只声明「**调用鉴权提供方需要什么形状**」，由每个服务在自己 `config` /
+ *   `resources` 槽位里实现 `AuthClient`，注入给 `auth` 的 `client` 选项。
+ *
+ * 契约本身是冻结的（框架只用到两个能力：校验凭证、注册权限操作）：改形状等于改契约。
+ * **地址与路径不进 framework**——它们随部署环境变化，属于业务配置。
+ */
+/** 校验请求附带的请求元信息（仅供下游审计 / 日志；不参与鉴权判定） */
+export interface AuthVerifyMetadata {
+    ip?: string;
+    ips?: string[];
+    url?: string;
+    method?: string;
+    referrer?: string;
+    requestId?: string;
+    userAgent?: string;
+}
+/** `verify` 的请求体：调鉴权提供方的校验能力时提交什么 */
+export interface AuthVerifyPayload {
+    token?: string;
+    apiKey?: string;
+    /** 调用方服务名（`AppIdentity.service`） */
+    service: string;
+    /** 操作标识（路由 `schema.operationId`，缺省回落 url） */
+    operation?: string;
+    /** 路由参数（`request.params`），如 `:id` 这类路径参数 */
+    resource?: Record<string, unknown>;
+    accessControls?: AccessControl[];
+    metadata?: AuthVerifyMetadata;
+}
+/** `verify` 的响应数据 */
+export interface AuthVerifyResult {
+    user?: unknown;
+    token?: unknown;
+}
+/** 权限操作自注册的请求体：调鉴权提供方的权限目录端点时提交什么 */
+export interface RegisterPermissionOperationsPayload {
+    service: string;
+    version: string;
+    operations: PermissionOperation[];
+}
+/**
+ * 鉴权客户端契约：框架只需要**两个**方法。
+ *
+ * 实现归业务服务（`createAuthMiddleware` 的 `client` 选项）：**URL / 路径 / 签名 /
+ * 协议（HTTP、gRPC、进程内调用）/ 超时 / 重试全在业务侧**，框架不认识任何地址。
+ * account 只是其中一种实现，不是唯一一种。
+ *
+ * 失败语义：
+ * - `verify` 抛错 = 校验不通过或提供方不可用；提供方应**自己抛** `UserError` /
+ *   `SystemError`（框架原样透出），其余错误统一归类为 `EXTERNAL_SERVICE_ERROR`；
+ * - `registerPermissionOperations` 抛错**不致命**（`auth` 只记日志，不中断启动）。
+ */
+export interface AuthClient {
+    verify(payload: AuthVerifyPayload): Promise<AuthVerifyResult>;
+    registerPermissionOperations(payload: RegisterPermissionOperationsPayload): Promise<void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/output/core/modules/auth-provider/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/auth-provider/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,mCAAmC,CAAA;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAE1D;;;;;;;;;;;;;;;;;GAiBG;AAEH,wCAAwC;AACxC,MAAM,WAAW,kBAAkB;IACjC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,GAAG,CAAC,EAAE,MAAM,EAAE,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,qCAAqC;AACrC,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oCAAoC;IACpC,OAAO,EAAE,MAAM,CAAA;IACf,6CAA6C;IAC7C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4CAA4C;IAC5C,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,cAAc,CAAC,EAAE,aAAa,EAAE,CAAA;IAChC,QAAQ,CAAC,EAAE,kBAAkB,CAAA;CAC9B;AAED,qBAAqB;AACrB,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,qCAAqC;AACrC,MAAM,WAAW,mCAAmC;IAClD,OAAO,EAAE,MAAM,CAAA;IACf,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,mBAAmB,EAAE,CAAA;CAClC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,UAAU;IACzB,MAAM,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAAA;IAC7D,4BAA4B,CAAC,OAAO,EAAE,mCAAmC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1F"}

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

@@ -0,0 +1,18 @@
+import type { FastifyBaseLogger, FastifyInstance, FastifyRequest } from 'fastify';
+/**
+ * core `context`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * 两部分：
+ * 1. `RequestContext` / `createContext`：请求级上下文的形状与构造；
+ * 2. `registerRequestContext`：把上下文装配到 `request.ctx`（`decorateRequest` + `onRequest`）。
+ *
+ * `request.ctx` 是 `type-augment` 对外承诺的类型契约，装配必须由框架保证——不能交由
+ * 各仓决定「装不装 / 装成什么名字」，否则类型存在而运行时缺失。装饰名固定 `ctx`，无选项。
+ */
+export interface RequestContext {
+    log: FastifyBaseLogger;
+}
+export declare function createContext(request: FastifyRequest): RequestContext;
+/** 装配 `request.ctx`（框架固定，先于任何路由 / 业务中间件注册） */
+export declare function registerRequestContext(app: FastifyInstance): void;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../source/core/modules/context/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEjF;;;;;;;;;GASG;AAEH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,iBAAiB,CAAA;CACvB;AAcD,wBAAgB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,CAErE;AAED,8CAA8C;AAC9C,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI,CAOjE"}

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

@@ -0,0 +1,23 @@
+const fallbackLogger = {
+    trace: () => { },
+    debug: () => { },
+    info: () => { },
+    warn: () => { },
+    error: () => { },
+    fatal: () => { },
+    child: () => fallbackLogger,
+    level: 'info',
+    silent: () => { },
+};
+export function createContext(request) {
+    return { log: request.log || fallbackLogger };
+}
+/** 装配 `request.ctx`（框架固定，先于任何路由 / 业务中间件注册） */
+export function registerRequestContext(app) {
+    // 先声明属性（保持 hidden class 稳定），再在 `onRequest` 逐个请求写入
+    app.decorateRequest('ctx', null);
+    app.addHook('onRequest', (request, _reply, done) => {
+        request.ctx = createContext(request);
+        done();
+    });
+}

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

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

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,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"}