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

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

@@ -1,26 +1,39 @@
+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 /
- *   zod→400 / serde→500 / 数据层（资源包的 `classifyError`）→500 / 未知→500；**禁止按 `error.type` 细分**。
+ * - `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 = '系统错误';
+/** 成功信封的固定 `message`（错误信封的 `message` 是业务文案，不固定） */
+const SUCCESS_MESSAGE = 'ok';
 export function createSuccessResponse(data) {
-    return { status: SUCCESS_STATUS, message: 'ok', data };
+    return { status: SUCCESS_STATUS, message: SUCCESS_MESSAGE, data };
 }
 export function createErrorResponse(status, message) {
     return { status, message, data: null };
@@ -55,12 +68,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)) {
@@ -72,13 +85,13 @@ export function registerResponse(app, options = {}) {
             request.log.error({ err: error }, '[response] response serialization error');
             return reply.code(500).send(createErrorResponse(SERIALIZATION_ERROR_STATUS, error.message));
         }
-        // ⑤ 数据层（Prisma 等）分类 → 500
-        const databaseError = options.classifyError?.(error);
-        if (databaseError) {
-            request.log.error({ err: error }, '[response] database error');
+        // ⑤ 资源错误（各资源注册的分类器依次认领）→ 500
+        const resourceError = options.classifyResourceError?.(error);
+        if (resourceError) {
+            request.log.error({ err: error }, '[response] resource error');
             return reply
                 .code(500)
-                .send(createErrorResponse(databaseError.type, resolveMessage(databaseError)));
+                .send(createErrorResponse(resourceError.type, resolveMessage(resourceError)));
         }
         // ⑥ 未知 → 500
         request.log.error({ err: error }, '[response] unknown 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":"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"}

package/output/core/modules/system-routes/index.js

@@ -0,0 +1,205 @@
+import { catchIt, SystemError } from '@taicode/common-base';
+import { z } from 'zod';
+import { createSuccessResponse } from '../response/index.js';
+import { routerSchema } from '../schema/builders.js';
+/**
+ * 框架内置系统路由（`app/core/system-routes.ts`）——**框架自动注册、应用侧零注册**。
+ *
+ * 背景：各应用此前各自维护一份 `modules/system/router.ts`（account / release / notice /
+ * expense / open-trade / observai 各写一份），契约容易漂移。现收进框架 core，由 `registerSystemRoutesStep`
+ * 在 `routers` 阶段**之前**统一注册，从 `AppIdentity` + `ctx.services` + `ctx.readConfig` 派生。
+ *
+ * 与既有应用 router 对齐的契约（路径 / 方法 / 响应信封 / NoLogin 语义）：
+ *
+ * | 方法 | 路径 | 说明 | 信封 `data` |
+ * |------|------|------|-------------|
+ * | GET  | `/`              | 服务可用性 | `string`（`identity.service`） |
+ * | GET  | `/health`        | k8s probe（NoLoginRequired） | `{ healthy: true }` |
+ * | GET  | `/system/openapi`| OpenAPI 文档（NoLoginRequired，**原样返回、不套信封**） | — |
+ * | POST | `/system/health` | API 版健康检查 | `{ healthy: true }` |
+ * | POST | `/system/info`   | 版本 + 运行时信息（NoLoginRequired，**不得含管理员等内部配置**） | `{ version, runtime }` |
+ *
+ * 健康检查：遍历 `services` 的**可选** `health()`，任一失败 / 非 `true` → 整体不健康，
+ * 抛 `SystemError('UNKNOWN_ERROR', { operation: 'healthCheck' })`（错误码与信封稳定，不得改）。
+ *
+ * `readConfig` 为**请求期惰性读取**（出 spec 路径不跑 `config` 槽位，故任何读取都必须发生在
+ * 请求处理器内，而非注册期）。
+ */
+/**
+ * 响应信封助手：**直接用 `core/response` 的实现**。
+ *
+ * 这里曾经保留一份更窄的本地副本，理由写的是「框架的 `createSuccessResponse`
+ * 返回 `status: string` 过宽」——那其实是框架自己的类型缺陷（见 `core/modules/response`
+ * 里 `SuccessResponse` 的说明），修在源头之后副本就没有存在理由了。
+ *
+ * 同一个信封在一个仓里有多份实现，迟早会出现「某一份改了、其他没改」的局部不一致，
+ * 而它们的目标形状本应完全一样。
+ */
+/** 响应信封（成功 `status: 'SUCCESS'`；错误 `data: null`，`status` 放稳定错误码字符串） */
+function successEnvelope(data) {
+    return z.object({
+        status: z.enum(['SUCCESS']),
+        message: z.string(),
+        data,
+    });
+}
+/** 错误分支信封：`status` 放开为字符串（错误码集合不由框架枚举），`data` 恒为 `null` */
+function errorEnvelope() {
+    return z.object({
+        status: z.string(),
+        message: z.string(),
+        data: z.null(),
+    });
+}
+/** 200 / 400 / 500 三分支响应（与各应用 `responseSchema` 同形） */
+function responseEnvelopeSchema(data) {
+    return {
+        200: successEnvelope(data),
+        400: errorEnvelope(),
+        500: errorEnvelope(),
+    };
+}
+const RootSchema = routerSchema({
+    operationId: 'getRoot',
+    summary: '根路由',
+    tags: ['系统'],
+    description: '服务可用性检查（无需认证）',
+    response: responseEnvelopeSchema(z.string()),
+});
+const HealthCheckSchema = routerSchema({
+    operationId: 'healthCheck',
+    summary: '健康检查',
+    tags: ['系统'],
+    description: '检查服务及其依赖是否正常运行（无需认证，用于 k8s readiness/liveness probe）',
+    response: responseEnvelopeSchema(z.object({ healthy: z.boolean().describe('服务是否健康') })),
+});
+const SystemHealthCheckSchema = routerSchema({
+    operationId: 'systemHealthCheck',
+    summary: '健康检查（API）',
+    tags: ['系统'],
+    description: '检查服务及其依赖是否正常运行（API 调用版）',
+    response: responseEnvelopeSchema(z.object({ healthy: z.boolean().describe('服务是否健康') })),
+});
+const SystemInfoSchema = routerSchema({
+    operationId: 'getSystemInfo',
+    summary: '获取系统信息',
+    tags: ['系统'],
+    description: '获取系统版本、运行时配置等信息（无需认证）',
+    response: responseEnvelopeSchema(z.object({
+        version: z
+            .object({
+            app: z.string().describe('应用版本'),
+            name: z.string().describe('应用名称（`identity.service`）'),
+            title: z.string().describe('应用标题（`identity.title`）'),
+            node: z.string().describe('Node.js 版本'),
+            platform: z.string().describe('运行平台'),
+            buildTime: z.string().optional().describe('构建时间'),
+            gitCommit: z.string().optional().describe('Git 提交哈希'),
+        })
+            .describe('版本信息'),
+        runtime: z
+            .object({
+            serverUrl: z.string().nullable().describe('服务公网地址'),
+            cookieNames: z
+                .array(z.string())
+                .describe('Cookie 名称列表（取自已加载配置的 `server.cookieNames`）'),
+        })
+            .describe('运行时配置'),
+    })),
+});
+function readStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === 'string') : undefined;
+}
+/** 遍历 services 的可选 `health()`：任一失败 / 非 `true` → false */
+async function checkHealth(services) {
+    for (const service of Object.values(services)) {
+        const health = service?.health;
+        if (typeof health !== 'function') {
+            continue;
+        }
+        const result = await catchIt(health());
+        if (result.isError()) {
+            return false;
+        }
+        if (result.value !== true) {
+            return false;
+        }
+    }
+    return true;
+}
+/** `/health` 与 `/system/health` 的共用处理器：不健康则抛 `UNKNOWN_ERROR`（k8s probe 依赖 5xx） */
+async function assertHealthy(services) {
+    const result = await catchIt(checkHealth(services));
+    const ok = result.isError() ? false : result.value;
+    if (!ok) {
+        throw new SystemError('UNKNOWN_ERROR', {
+            operation: 'healthCheck',
+            cause: result.isError() ? result.error : 'Service health check failed',
+        });
+    }
+}
+/** `GET /system/openapi` 的路由元信息 */
+const OpenApiSpecSchema = routerSchema({
+    operationId: 'getOpenApiDocument',
+    summary: '获取 OpenAPI 文档',
+    tags: ['系统'],
+    description: '返回本服务的 OpenAPI 文档（无需认证，原样返回、不套响应信封）',
+});
+/**
+ * 注册框架内置系统路由（5 个端点）。由 `registerSystemRoutesStep` 在 `server.routers(...)` **之前**调用，
+ * 保证框架路由先就位。
+ */
+export function registerSystemRoutes(app, options) {
+    const { identity, services, readConfig } = options;
+    // GET / —— 服务可用性（服务名取自身份块）
+    app.get('/', { config: { accessControls: ['NoLoginRequired'] }, schema: RootSchema }, async () => {
+        return createSuccessResponse(identity.service);
+    });
+    // GET /health —— k8s probe（保持 GET，NoLoginRequired）
+    app.get('/health', { config: { accessControls: ['NoLoginRequired'] }, schema: HealthCheckSchema }, async () => {
+        await assertHealthy(services);
+        return createSuccessResponse({ healthy: true });
+    });
+    // POST /system/health —— API 版健康检查
+    app.post('/system/health', { schema: SystemHealthCheckSchema }, async () => {
+        await assertHealthy(services);
+        return createSuccessResponse({ healthy: true });
+    });
+    // GET /system/openapi —— OpenAPI 文档出口（NoLoginRequired）
+    //
+    // **原样返回、不套信封**：文档是机器可读契约（各仓 `api-gen` / `openapi-ts` 直接消费），
+    // 包一层 `{ status, message, data }` 就不再是合法 OpenAPI 文档。
+    // 实现上返回**已序列化的 JSON 字符串**：Fastify 对 `string` payload 不触发
+    // `preSerialization`，`core/response` 的统一信封因而不会介入；`content-type` 显式设为
+    // `application/json` 保证客户端按 JSON 解析。
+    app.get('/system/openapi', { config: { accessControls: ['NoLoginRequired'] }, schema: OpenApiSpecSchema }, async (_request, reply) => {
+        const document = app.swagger();
+        return reply.type('application/json').send(JSON.stringify(document));
+    });
+    // POST /system/info —— 版本 + 运行时（请求期现读配置）
+    //
+    // ⚠️ **这是公开接口**（不含 `admin` 等内部配置）：任何从这里出去的字段都等于公开。
+    // 管理员用户名 / 内部账号列表这类信息**永远不返回**——它是撞库与提权的直接输入，
+    // 不是「运行时信息」。需要排查管理员配置走运维通道（日志 / 数据库），不走 HTTP。
+    //
+    // `NoLoginRequired` 与「它是公开接口」是同一件事的两半，必须成对声明：少了这一行，
+    // auth 中间件会把探活 / 版本查询挡成 400，客户端与探针都拿不到运行时信息。
+    app.post('/system/info', { config: { accessControls: ['NoLoginRequired'] }, schema: SystemInfoSchema }, async () => {
+        const server = readConfig('server');
+        return createSuccessResponse({
+            version: {
+                app: identity.version,
+                name: identity.service,
+                title: identity.title,
+                node: process.version,
+                platform: process.platform,
+                buildTime: process.env.BUILD_TIME,
+                gitCommit: process.env.GIT_COMMIT,
+            },
+            runtime: {
+                serverUrl: server?.url ?? server?.serverUrl ?? null,
+                cookieNames: readStringArray(server?.cookieNames) ?? [],
+            },
+        });
+    });
+}

package/output/core/resource.d.ts

@@ -0,0 +1,56 @@
+import type { ResourceLifecycle, ResourceUnit } from './types.js';
+/**
+ * 构造资源单元（唯一的正当方式）。
+ *
+ * ## 为什么需要外壳
+ *
+ * 资源多是**第三方对象**：`PrismaClient`、Redis client、HTTP 连接池⋯⋯它们的形状改不了。
+ * service 可以直接在对象上挂 `init()`（因为 service 是本仓自己写的），资源不行——
+ * `prisma.setup = …` 是在改别人的类型，运行期也未必允许。
+ *
+ * 所以 `setup()` 挂在**框架私有外壳**上，`value` 原样保留：
+ *
+ * ```ts
+ * resources: (ctx) => ({
+ *   database: defineResource(createPrisma(ctx.env.DATABASE_URL), {
+ *     async setup() { await pushSchema(ctx.env.DATABASE_URL) },
+ *   }),
+ * })
+ * ```
+ *
+ * 消费方读 `ctx.resources.database` 拿到的是 `PrismaClient` 本身
+ * （`ResourcesView` 会解包），不是 `ResourceUnit<PrismaClient>`。
+ *
+ * ## 单元是可选的
+ *
+ * 裸对象照旧可用（无 `setup`、无解包开销）：`resources: () => ({ database: prisma })`。
+ * 只有需要「装配期准备」的资源才包一层。
+ *
+ * ## `setup` 何时跑、谁跑
+ *
+ * - **何时**：`resources` 槽位构造完成后、`config` 槽位之前；按**对象声明序**逐项 `await`。
+ *   排在 `config` 前是硬要求——`config` 常从数据库读（如 `SystemConfig` 表），库没准备好
+ *   它就连不上。
+ * - **谁**：框架。`startServer` / `createTestServer` 都调；`generateOpenApi` 不调
+ *   （出 spec 不构造资源）。应用**永不手调**。
+ * - **失败**：立即中断装配并把错误抛给入口（已构造的资源照常释放）。资源准备失败后
+ *   `config` / `services` 都没有意义，所以不吞。
+ *
+ * ## 不要在里面写 `if (ENV === 'test')`
+ *
+ * 准备动作本身应当是**状态驱动**的：`prisma db push` / `migrate deploy` 都会自己比对现状、
+ * 只补差量，生产与测试跑同一份代码。需要区分环境的细节应当从 `ctx.env` 取，而不是让
+ * 「跑不跑这个函数」变成环境分支。
+ *
+ * ## 用例间重置不在本文件
+ *
+ * 「清表 / 清缓存 / 重新插入样本数据」不适合挂在资源上：资源只知道有哪些表、哪些 key，
+ * 不知道**谁往里写了什么**。写在资源上就变成了「新增一个 model 就得回去改一次清库清单」，
+ * 漏改只会安静地变脏。
+ *
+ * 所以它单独成机制：**`packages/server/testdata/*.ts|js`，每个脚本自带 `load()` / `cleanup()`**，
+ * 由框架在 `development` / `test` 下自动装载并执行（见 `core/test-support/testdata.ts`）。
+ * 数据脚本自己知道要插入什么，也就自己知道怎么删干净。
+ */
+export declare function defineResource<Value>(value: Value, lifecycle?: ResourceLifecycle): ResourceUnit<Value>;
+//# sourceMappingURL=resource.d.ts.map

package/output/core/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../source/core/resource.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,iBAAiB,GAAG,YAAY,CAAC,KAAK,CAAC,CAEtG"}

package/output/core/resource.js

@@ -0,0 +1,56 @@
+/**
+ * 构造资源单元（唯一的正当方式）。
+ *
+ * ## 为什么需要外壳
+ *
+ * 资源多是**第三方对象**：`PrismaClient`、Redis client、HTTP 连接池⋯⋯它们的形状改不了。
+ * service 可以直接在对象上挂 `init()`（因为 service 是本仓自己写的），资源不行——
+ * `prisma.setup = …` 是在改别人的类型，运行期也未必允许。
+ *
+ * 所以 `setup()` 挂在**框架私有外壳**上，`value` 原样保留：
+ *
+ * ```ts
+ * resources: (ctx) => ({
+ *   database: defineResource(createPrisma(ctx.env.DATABASE_URL), {
+ *     async setup() { await pushSchema(ctx.env.DATABASE_URL) },
+ *   }),
+ * })
+ * ```
+ *
+ * 消费方读 `ctx.resources.database` 拿到的是 `PrismaClient` 本身
+ * （`ResourcesView` 会解包），不是 `ResourceUnit<PrismaClient>`。
+ *
+ * ## 单元是可选的
+ *
+ * 裸对象照旧可用（无 `setup`、无解包开销）：`resources: () => ({ database: prisma })`。
+ * 只有需要「装配期准备」的资源才包一层。
+ *
+ * ## `setup` 何时跑、谁跑
+ *
+ * - **何时**：`resources` 槽位构造完成后、`config` 槽位之前；按**对象声明序**逐项 `await`。
+ *   排在 `config` 前是硬要求——`config` 常从数据库读（如 `SystemConfig` 表），库没准备好
+ *   它就连不上。
+ * - **谁**：框架。`startServer` / `createTestServer` 都调；`generateOpenApi` 不调
+ *   （出 spec 不构造资源）。应用**永不手调**。
+ * - **失败**：立即中断装配并把错误抛给入口（已构造的资源照常释放）。资源准备失败后
+ *   `config` / `services` 都没有意义，所以不吞。
+ *
+ * ## 不要在里面写 `if (ENV === 'test')`
+ *
+ * 准备动作本身应当是**状态驱动**的：`prisma db push` / `migrate deploy` 都会自己比对现状、
+ * 只补差量，生产与测试跑同一份代码。需要区分环境的细节应当从 `ctx.env` 取，而不是让
+ * 「跑不跑这个函数」变成环境分支。
+ *
+ * ## 用例间重置不在本文件
+ *
+ * 「清表 / 清缓存 / 重新插入样本数据」不适合挂在资源上：资源只知道有哪些表、哪些 key，
+ * 不知道**谁往里写了什么**。写在资源上就变成了「新增一个 model 就得回去改一次清库清单」，
+ * 漏改只会安静地变脏。
+ *
+ * 所以它单独成机制：**`packages/server/testdata/*.ts|js`，每个脚本自带 `load()` / `cleanup()`**，
+ * 由框架在 `development` / `test` 下自动装载并执行（见 `core/test-support/testdata.ts`）。
+ * 数据脚本自己知道要插入什么，也就自己知道怎么删干净。
+ */
+export function defineResource(value, lifecycle) {
+    return lifecycle ? { value, ...lifecycle } : { value };
+}