@taicode/common-server 3.8.0 → 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/core/modules/cookie/index.js

@@ -0,0 +1,17 @@
+import cookie from '@fastify/cookie'; // eslint-disable-line import/default -- @fastify/cookie 是 CJS `export =`，esModuleInterop 下默认导入即正确用法
+/** 从 `readConfig('server')` 的返回值读取 cookie domain */
+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/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/core/modules/identity/index.js

@@ -0,0 +1,14 @@
+/**
+ * 身份块在 `app` 上的存放键（Symbol，**不进公共契约**）。
+ *
+ * `defineServer({ app })` 的身份块只属于定义产物；`middlewares` / `routers` 的 ctx 里没有它
+ * （可见性按需收窄），框架内置单元（`auth` 权限自注册 / `rateLimit` 前缀）需要 `service` /
+ * `version` 时从这里读。
+ */
+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/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/core/modules/logging/index.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） */
+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/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/core/modules/openapi/index.js

@@ -0,0 +1,41 @@
+import swagger from '@fastify/swagger';
+import { createJsonSchemaTransform } from 'fastify-type-provider-zod';
+/**
+ * core `openapi`（设计 §5.1）——**框架内置、锁定、不可替换/修改**。
+ *
+ * 只做**文档生成**：`@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。
+ */
+/** OpenAPI 规范版本（固定，不可配置） */
+const OPENAPI_SPEC_VERSION = '3.0.3';
+export async function registerOpenApi(app, options) {
+    await 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: [] }),
+    });
+    // 确定性冲刷插件队列：让 swagger 的 root `onRoute` 钩子在**任何路由注册之前**就位——
+    // 后续 `routers` 阶段注册的路由才会被采集进文档。不得依赖「恰好有 cors 等其它
+    // `app.register` 顺带冲刷队列」这种隐式巧合（设计 §5.2 / §10-18）。
+    await app.after();
+    app.addHook('onListen', () => {
+        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/core/modules/request-id/index.d.ts

@@ -0,0 +1,33 @@
+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";
+/** 传给 `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=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"}