yingzios-platform-backend-shared 1.0.1

package/dist/swagger/swagger.decorators.d.ts

@@ -0,0 +1,21 @@
+import { Type } from '@nestjs/common';
+/**
+ * 用于处理 PaginatedResponseDto<T> 泛型的 Swagger 装饰器
+ * 解决 TypeScript 泛型在运行时丢失导致 Swagger 无法正确显示泛型类型的问题
+ *
+ * @param model 泛型类型，如 Plugin
+ */
+export declare const ApiPaginatedResponse: <TModel extends Type<any>>(model: TModel) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+/**
+ * 用于处理 ApiResponseDto<T> 泛型的 Swagger 装饰器
+ *
+ * @param model 泛型类型，如 Plugin
+ */
+export declare const ApiDataResponse: <TModel extends Type<any>>(model: TModel) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+/**
+ * 用于创建操作的响应装饰器
+ *
+ * @param model 泛型类型，如 Plugin
+ */
+export declare const ApiCreatedDataResponse: <TModel extends Type<any>>(model: TModel) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;
+//# sourceMappingURL=swagger.decorators.d.ts.map

package/dist/swagger/swagger.decorators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger.decorators.d.ts","sourceRoot":"","sources":["../../src/swagger/swagger.decorators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAmB,MAAM,gBAAgB,CAAC;AAIvD;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB,GAAI,MAAM,SAAS,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,MAAM,gJA6D3E,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,SAAS,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,MAAM,gJAgBtE,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,sBAAsB,GAAI,MAAM,SAAS,IAAI,CAAC,GAAG,CAAC,EAAE,OAAO,MAAM,gJAgB7E,CAAC"}

package/dist/swagger/swagger.decorators.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiCreatedDataResponse = exports.ApiDataResponse = exports.ApiPaginatedResponse = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const response_dto_1 = require("../restful/response.dto");
+/**
+ * 用于处理 PaginatedResponseDto<T> 泛型的 Swagger 装饰器
+ * 解决 TypeScript 泛型在运行时丢失导致 Swagger 无法正确显示泛型类型的问题
+ *
+ * @param model 泛型类型，如 Plugin
+ */
+const ApiPaginatedResponse = (model) => {
+    return (0, common_1.applyDecorators)((0, swagger_1.ApiExtraModels)(model), (0, swagger_1.ApiOkResponse)({
+        schema: {
+            allOf: [
+                { $ref: (0, swagger_1.getSchemaPath)(response_dto_1.PaginatedResponseDto) },
+                {
+                    properties: {
+                        code: {
+                            type: 'string',
+                            example: '000000',
+                            description: '响应码',
+                        },
+                        msg: {
+                            type: 'string',
+                            example: 'Success',
+                            description: '响应消息',
+                        },
+                        traceId: {
+                            type: 'string',
+                            description: '追踪ID',
+                            example: 'trace-id-example',
+                        },
+                        data: {
+                            type: 'object',
+                            properties: {
+                                totalCount: {
+                                    type: 'string',
+                                    example: '100',
+                                    description: '总记录数',
+                                },
+                                pageSize: {
+                                    type: 'string',
+                                    example: '10',
+                                    description: '每页记录数',
+                                },
+                                totalPage: {
+                                    type: 'string',
+                                    example: '10',
+                                    description: '总页数',
+                                },
+                                currentPage: {
+                                    type: 'string',
+                                    example: '1',
+                                    description: '当前页码',
+                                },
+                                list: {
+                                    type: 'array',
+                                    items: { $ref: (0, swagger_1.getSchemaPath)(model) },
+                                    description: '数据列表',
+                                },
+                            },
+                            description: '分页数据',
+                        },
+                    },
+                },
+            ],
+        },
+    }));
+};
+exports.ApiPaginatedResponse = ApiPaginatedResponse;
+/**
+ * 用于处理 ApiResponseDto<T> 泛型的 Swagger 装饰器
+ *
+ * @param model 泛型类型，如 Plugin
+ */
+const ApiDataResponse = (model) => {
+    return (0, common_1.applyDecorators)((0, swagger_1.ApiExtraModels)(response_dto_1.ApiResponseDto, model), (0, swagger_1.ApiOkResponse)({
+        schema: {
+            allOf: [
+                { $ref: (0, swagger_1.getSchemaPath)(response_dto_1.ApiResponseDto) },
+                {
+                    properties: {
+                        data: { $ref: (0, swagger_1.getSchemaPath)(model) },
+                    },
+                },
+            ],
+        },
+    }));
+};
+exports.ApiDataResponse = ApiDataResponse;
+/**
+ * 用于创建操作的响应装饰器
+ *
+ * @param model 泛型类型，如 Plugin
+ */
+const ApiCreatedDataResponse = (model) => {
+    return (0, common_1.applyDecorators)((0, swagger_1.ApiExtraModels)(response_dto_1.ApiResponseDto, model), (0, swagger_1.ApiCreatedResponse)({
+        schema: {
+            allOf: [
+                { $ref: (0, swagger_1.getSchemaPath)(response_dto_1.ApiResponseDto) },
+                {
+                    properties: {
+                        data: { $ref: (0, swagger_1.getSchemaPath)(model) },
+                    },
+                },
+            ],
+        },
+    }));
+};
+exports.ApiCreatedDataResponse = ApiCreatedDataResponse;

package/dist/swagger/swagger.module.d.ts

@@ -0,0 +1,15 @@
+import { DynamicModule } from '@nestjs/common';
+import { ISwaggerConfig } from './swagger.config';
+/**
+ * Swagger模块
+ * 支持 forRoot() 模式进行配置
+ */
+export declare class SwaggerModule {
+    /**
+     * 静态方法：配置Swagger模块
+     * 用于根模块注册
+     * @param options Swagger配置选项
+     */
+    static forRoot(options?: ISwaggerConfig): DynamicModule;
+}
+//# sourceMappingURL=swagger.module.d.ts.map

package/dist/swagger/swagger.module.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger.module.d.ts","sourceRoot":"","sources":["../../src/swagger/swagger.module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAkB,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAkB,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElE;;;GAGG;AACH,qBAEa,aAAa;IACxB;;;;OAIG;IACH,MAAM,CAAC,OAAO,CAAC,OAAO,GAAE,cAAmB,GAAG,aAAa;CAoB5D"}

package/dist/swagger/swagger.module.js

@@ -0,0 +1,49 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var SwaggerModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerModule = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_service_1 = require("./swagger.service");
+const swagger_config_1 = require("./swagger.config");
+/**
+ * Swagger模块
+ * 支持 forRoot() 模式进行配置
+ */
+let SwaggerModule = SwaggerModule_1 = class SwaggerModule {
+    /**
+     * 静态方法：配置Swagger模块
+     * 用于根模块注册
+     * @param options Swagger配置选项
+     */
+    static forRoot(options = {}) {
+        const mergedConfig = {
+            ...swagger_config_1.SWAGGER_CONFIG,
+            ...options,
+        };
+        return {
+            module: SwaggerModule_1,
+            providers: [
+                {
+                    provide: 'SWAGGER_OPTIONS',
+                    useValue: mergedConfig,
+                },
+                {
+                    provide: 'SWAGGER_SERVICE',
+                    useClass: swagger_service_1.SwaggerService,
+                },
+            ],
+            exports: ['SWAGGER_SERVICE'],
+        };
+    }
+};
+exports.SwaggerModule = SwaggerModule;
+exports.SwaggerModule = SwaggerModule = SwaggerModule_1 = __decorate([
+    (0, common_1.Global)(),
+    (0, common_1.Module)({})
+], SwaggerModule);

package/dist/swagger/swagger.service.d.ts

@@ -0,0 +1,44 @@
+import { INestApplication } from '@nestjs/common';
+import type { ISwaggerConfig } from './swagger.config';
+export interface ISwaggerService {
+    configure(app: INestApplication): void;
+}
+/**
+ * Swagger服务
+ * 用于配置和设置Swagger文档
+ *
+ * 功能:
+ * 1. 为当前服务生成独立的 Swagger 文档
+ * 2. (可选) 启用文档聚合功能，汇总多个微服务的文档
+ */
+export declare class SwaggerService implements ISwaggerService {
+    private readonly logger;
+    private options;
+    constructor(options?: ISwaggerConfig);
+    /**
+     * 配置Swagger文档
+     * 执行顺序:
+     * 1. 生成当前服务的独立文档 (必选)
+     * 2. 启用文档聚合功能 (可选，基于配置)
+     */
+    configure(app: INestApplication): void;
+    /**
+     * 设置独立的 Swagger 文档
+     * 为当前服务生成 /swagger 和 /swagger-json 端点
+     */
+    private setupStandaloneSwagger;
+    /**
+     * 设置文档聚合功能
+     * 注册一个聚合路由，展示配置中所有服务的文档
+     *
+     * 依据: Swagger UI 官方多 URL 配置
+     * https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md
+     */
+    private setupAggregation;
+    /**
+     * 生成聚合文档的 HTML 页面
+     * 使用 Swagger UI 原生的多 URL 配置
+     */
+    private generateAggregationHtml;
+}
+//# sourceMappingURL=swagger.service.d.ts.map

package/dist/swagger/swagger.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"swagger.service.d.ts","sourceRoot":"","sources":["../../src/swagger/swagger.service.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAIvD,MAAM,WAAW,eAAe;IAC9B,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,qBACa,cAAe,YAAW,eAAe;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmC;IAC1D,OAAO,CAAC,OAAO,CAAiB;gBAEO,OAAO,CAAC,EAAE,cAAc;IAI/D;;;;;OAKG;IACH,SAAS,CAAC,GAAG,EAAE,gBAAgB,GAAG,IAAI;IAUtC;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IA6C9B;;;;;;OAMG;IACH,OAAO,CAAC,gBAAgB;IAuCxB;;;OAGG;IACH,OAAO,CAAC,uBAAuB;CAiEhC"}

package/dist/swagger/swagger.service.js

@@ -0,0 +1,202 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+var SwaggerService_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SwaggerService = void 0;
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+// 导入常用的模型
+const response_dto_1 = require("../restful/response.dto");
+/**
+ * Swagger服务
+ * 用于配置和设置Swagger文档
+ *
+ * 功能:
+ * 1. 为当前服务生成独立的 Swagger 文档
+ * 2. (可选) 启用文档聚合功能，汇总多个微服务的文档
+ */
+let SwaggerService = SwaggerService_1 = class SwaggerService {
+    logger = new common_1.Logger(SwaggerService_1.name);
+    options;
+    constructor(options) {
+        this.options = options || {};
+    }
+    /**
+     * 配置Swagger文档
+     * 执行顺序:
+     * 1. 生成当前服务的独立文档 (必选)
+     * 2. 启用文档聚合功能 (可选，基于配置)
+     */
+    configure(app) {
+        // 1. 生成独立文档
+        this.setupStandaloneSwagger(app);
+        // 2. 如果配置了聚合功能，则注册聚合路由
+        if (this.options.aggregation?.enabled) {
+            this.setupAggregation(app);
+        }
+    }
+    /**
+     * 设置独立的 Swagger 文档
+     * 为当前服务生成 /swagger 和 /swagger-json 端点
+     */
+    setupStandaloneSwagger(app) {
+        const config = new swagger_1.DocumentBuilder()
+            .setTitle(this.options.title || 'API文档')
+            .setDescription(this.options.description || 'API接口文档')
+            .setVersion(this.options.version || '1.0')
+            .addBearerAuth()
+            .addTag('default', '默认接口');
+        // 添加自定义标签
+        if (this.options.tags && this.options.tags.length > 0) {
+            this.options.tags.forEach((tag) => {
+                config.addTag(tag.name, tag.description);
+            });
+        }
+        // 构建基础文档
+        const documentBuilder = config.build();
+        // 添加额外的模型定义，确保PaginatedResponseDto等模型被正确注册
+        documentBuilder.components = documentBuilder.components || {};
+        documentBuilder.components.schemas = documentBuilder.components.schemas || {};
+        // 生成文档
+        const document = swagger_1.SwaggerModule.createDocument(app, documentBuilder, {
+            extraModels: [response_dto_1.ApiResponseDto, response_dto_1.PaginatedResponseDto], // 自动注册常用模型
+        });
+        // 修复Fastify环境下PaginatedResponseDto引用问题
+        // 确保所有额外模型都被正确添加到文档中
+        if (!document.components) {
+            document.components = {};
+        }
+        if (!document.components.schemas) {
+            document.components.schemas = {};
+        }
+        swagger_1.SwaggerModule.setup(this.options.path, app, document, {
+            customSiteTitle: this.options.customSiteTitle,
+            customfavIcon: this.options.customfavIcon,
+            customCss: this.options.customCss,
+        });
+        this.logger.log(`Swagger文档已配置，访问地址: ${this.options.path || 'api'}`);
+    }
+    /**
+     * 设置文档聚合功能
+     * 注册一个聚合路由，展示配置中所有服务的文档
+     *
+     * 依据: Swagger UI 官方多 URL 配置
+     * https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md
+     */
+    setupAggregation(app) {
+        const aggConfig = this.options.aggregation;
+        const aggPath = aggConfig.path || 'api-docs';
+        // 验证配置
+        if (!aggConfig.services || aggConfig.services.length === 0) {
+            this.logger.warn('文档聚合已启用，但未配置任何服务，跳过聚合路由注册');
+            return;
+        }
+        // 生成 Swagger UI HTML
+        const html = this.generateAggregationHtml(aggConfig);
+        // 使用底层 HTTP adapter 注册路由
+        // 兼容 Express 和 Fastify
+        const httpAdapter = app.getHttpAdapter();
+        const instance = httpAdapter.getInstance();
+        // 注册聚合文档路由
+        // Express: app.get(path, handler)
+        // Fastify: app.get(path, handler)
+        instance.get(`/${aggPath}`, (_req, res) => {
+            // Express
+            if (res.setHeader && res.send) {
+                res.setHeader('Content-Type', 'text/html; charset=utf-8');
+                res.send(html);
+            }
+            // Fastify
+            else if (res.header && res.send) {
+                res.header('Content-Type', 'text/html; charset=utf-8');
+                res.send(html);
+            }
+        });
+        this.logger.log(`文档聚合已启用，访问地址: ${aggPath} (聚合 ${aggConfig.services.length} 个服务)`);
+    }
+    /**
+     * 生成聚合文档的 HTML 页面
+     * 使用 Swagger UI 原生的多 URL 配置
+     */
+    generateAggregationHtml(aggConfig) {
+        const services = aggConfig.services;
+        const primaryName = aggConfig.primaryName || services[0]?.name;
+        return `
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+  <meta charset="UTF-8">
+  <title>YingziOS API 文档中心</title>
+  <link rel="stylesheet" type="text/css" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui.css">
+  <link rel="icon" type="image/png" href="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/favicon-32x32.png" sizes="32x32">
+  <style>
+    html {
+      box-sizing: border-box;
+      overflow: -moz-scrollbars-vertical;
+      overflow-y: scroll;
+    }
+    *, *:before, *:after {
+      box-sizing: inherit;
+    }
+    body {
+      margin: 0;
+      padding: 0;
+    }
+    .topbar {
+      background-color: #1f1f1f !important;
+    }
+    .topbar-wrapper .link {
+      color: #fff !important;
+    }
+  </style>
+</head>
+<body>
+  <div id="swagger-ui"></div>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-bundle.js" charset="UTF-8"></script>
+  <script src="https://cdn.jsdelivr.net/npm/swagger-ui-dist@5/swagger-ui-standalone-preset.js" charset="UTF-8"></script>
+  <script>
+    window.onload = function() {
+      const ui = SwaggerUIBundle({
+        urls: ${JSON.stringify(services, null, 10)},
+        "urls.primaryName": ${JSON.stringify(primaryName)},
+        dom_id: '#swagger-ui',
+        deepLinking: true,
+        presets: [
+          SwaggerUIBundle.presets.apis,
+          SwaggerUIStandalonePreset
+        ],
+        plugins: [
+          SwaggerUIBundle.plugins.DownloadUrl
+        ],
+        layout: "StandaloneLayout",
+        docExpansion: "list",
+        displayRequestDuration: true,
+        filter: true,
+        tryItOutEnabled: false,
+        persistAuthorization: true
+      });
+      window.ui = ui;
+    };
+  </script>
+</body>
+</html>
+    `.trim();
+    }
+};
+exports.SwaggerService = SwaggerService;
+exports.SwaggerService = SwaggerService = SwaggerService_1 = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)('SWAGGER_OPTIONS')),
+    __metadata("design:paramtypes", [Object])
+], SwaggerService);

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "yingzios-platform-backend-shared",
+  "version": "1.0.1",
+  "description": "NestJS 共享模块库",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/your-org/yingzios-platform-portal.git",
+    "directory": "libs/backend-shared"
+  },
+  "keywords": [
+    "nestjs",
+    "nest",
+    "shared",
+    "modules",
+    "sequelize",
+    "jwt",
+    "swagger",
+    "apollo",
+    "nacos"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@keyv/redis": "^5.1.6",
+    "@keyv/sqlite": "^4.0.8",
+    "@nestjs/common": "^11.1.17",
+    "@nestjs/core": "^11.1.17",
+    "@nestjs/jwt": "^11.0.2",
+    "@nestjs/passport": "^11.0.5",
+    "@nestjs/swagger": "^11.2.3",
+    "@sapphire/snowflake": "^3.5.5",
+    "@vodyani/apollo-client": "^1.5.0",
+    "axios": "^1.14.0",
+    "ctrip-apollo": "^4.5.1",
+    "dotenv": "^16.4.5",
+    "express": "^4.18.2",
+    "json-bigint": "^1.0.0",
+    "keyv": "^5.6.0",
+    "lodash": "^4.17.21",
+    "nacos": "^2.6.0",
+    "passport": "^0.7.0",
+    "passport-jwt": "^4.0.1",
+    "pg": "^8.16.3",
+    "rxjs": "^7.8.1",
+    "sequelize": "^6.37.8",
+    "tslib": "^2.8.1",
+    "umzug": "^3.8.2",
+    "winston": "^3.19.0",
+    "winston-daily-rotate-file": "^5.0.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.21",
+    "@types/json-bigint": "^1.0.4",
+    "@types/lodash": "^4.17.21",
+    "@types/node": "^24.10.2",
+    "@types/passport-jwt": "^4.0.1",
+    "@types/pg": "^8.15.6"
+  }
+}