@nest-omni/core 4.1.3-3 → 4.1.3-30

package/email-log/utils/pino-transport.utils.js

@@ -0,0 +1,238 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createEmailTransport = createEmailTransport;
+exports.createPinoMultistream = createPinoMultistream;
+exports.createPinoEmailLogger = createPinoEmailLogger;
+exports.attachEmailTransportToLogger = attachEmailTransportToLogger;
+exports.createPinoEmailChildLogger = createPinoEmailChildLogger;
+exports.createEmailTransportFromEnv = createEmailTransportFromEnv;
+const pino_1 = require("pino");
+const pino_email_transport_1 = require("../transports/pino-email.transport");
+/**
+ * Create a Pino transport stream for email logging
+ * This function creates a writable stream that can be used with Pino
+ *
+ * @param options Email log options
+ * @returns A Pino transport configuration
+ *
+ * @example
+ * ```typescript
+ * import { createEmailTransport } from '@nest-omni/core';
+ * import pino from 'pino';
+ *
+ * const transport = createEmailTransport({
+ *   enabled: true,
+ *   to: ['admin@example.com'],
+ *   from: 'noreply@example.com',
+ *   smtpHost: 'smtp.example.com',
+ * });
+ *
+ * const logger = pino(transport);
+ * ```
+ */
+function createEmailTransport(options) {
+    return new pino_email_transport_1.PinoEmailTransport(options);
+}
+/**
+ * Create a Pino multistream configuration that includes email transport
+ *
+ * @param options Email log options
+ * @param emailTransport The email transport service instance or PinoEmailTransport
+ * @returns Pino multistream targets array
+ *
+ * @example
+ * ```typescript
+ * import { createPinoMultistream } from '@nest-omni/core';
+ * import pino from 'pino';
+ *
+ * const streams = createPinoMultistream(options, emailTransport);
+ * const logger = pino(pino.multistream(streams));
+ * ```
+ */
+function createPinoMultistream(options, emailTransport) {
+    const streams = [
+        // Default stdout stream - log everything to console
+        {
+            level: 'trace',
+            stream: process.stdout,
+        },
+    ];
+    // Add email transport if enabled
+    if (options.enabled) {
+        streams.push({
+            level: options.level,
+            stream: emailTransport, // Both EmailLogTransportService and PinoEmailTransport are writable streams
+        });
+    }
+    return streams;
+}
+/**
+ * Create a Pino logger with email transport already configured
+ * This is the simplest way to get started with email logging
+ *
+ * @param options Email log options
+ * @param baseLogger Optional base Pino logger to extend
+ * @returns Pino logger with email transport
+ *
+ * @example
+ * ```typescript
+ * import { createPinoEmailLogger } from '@nest-omni/core';
+ *
+ * const logger = createPinoEmailLogger({
+ *   enabled: true,
+ *   to: ['admin@example.com'],
+ *   from: 'noreply@example.com',
+ *   smtpHost: 'smtp.example.com',
+ * });
+ *
+ * logger.error('Something went wrong!', { userId: '123' });
+ * // This will log to console AND send an email
+ * ```
+ */
+function createPinoEmailLogger(options, baseLogger) {
+    const transport = createEmailTransport(options);
+    if (!options.enabled) {
+        // If disabled, return a basic logger
+        return baseLogger || (0, pino_1.default)({ level: options.level });
+    }
+    const streams = createPinoMultistream(options, transport);
+    if (baseLogger) {
+        // Extend existing logger with email transport
+        return (0, pino_1.default)(Object.assign({}, baseLogger.options), pino_1.default.multistream(streams));
+    }
+    // Create new logger with email transport
+    return (0, pino_1.default)({
+        level: 'trace', // Log everything to console
+    }, pino_1.default.multistream(streams));
+}
+/**
+ * Manually attach email transport to an existing Pino logger
+ * Use this if you want to add email logging to a specific logger instance
+ *
+ * @param logger The Pino logger instance
+ * @param options Email log options
+ * @param emailTransport The email transport service instance
+ *
+ * @example
+ * ```typescript
+ * import { attachEmailTransportToLogger } from '@nest-omni/core';
+ *
+ * attachEmailTransportToLogger(myLogger, options, emailTransport);
+ * ```
+ */
+function attachEmailTransportToLogger(logger, options, emailTransport) {
+    var _a;
+    const minLevel = pino_1.default.levels.values[options.level] || pino_1.default.levels.values.error || 50;
+    // Store original write method
+    const loggerInstance = logger;
+    const originalFlush = (_a = loggerInstance.flush) === null || _a === void 0 ? void 0 : _a.bind(loggerInstance);
+    // Override flush to include email transport flush
+    if (originalFlush) {
+        loggerInstance.flush = (cb) => __awaiter(this, void 0, void 0, function* () {
+            yield originalFlush(cb);
+            if (typeof emailTransport.flush === 'function') {
+                yield emailTransport.flush();
+            }
+        });
+    }
+    // Add the email transport as a child stream
+    const transport = {
+        write: (data) => {
+            const level = typeof data.level === 'number'
+                ? data.level
+                : pino_1.default.levels.values[data.level] || 30;
+            if (level >= minLevel) {
+                emailTransport.write(data);
+            }
+        },
+    };
+    // Try to use pino.multistream if available
+    try {
+        const streams = createPinoMultistream(options, emailTransport);
+        const newLogger = (0, pino_1.default)(pino_1.default.multistream(streams));
+        // Copy all properties from old logger to new one
+        Object.assign(loggerInstance, newLogger);
+    }
+    catch (_b) {
+        // pino.multistream not available, use manual approach
+        emailTransport._loggerTransport = transport;
+    }
+}
+/**
+ * Create a child logger with email context
+ * Useful for adding consistent metadata to all logs from a module
+ *
+ * @param parentLogger The parent Pino logger
+ * @param context Context object to include in all logs
+ * @returns Child Pino logger
+ *
+ * @example
+ * ```typescript
+ * import { createPinoEmailLogger, createPinoEmailChildLogger } from '@nest-omni/core';
+ *
+ * const baseLogger = createPinoEmailLogger(options);
+ * const userServiceLogger = createPinoEmailChildLogger(baseLogger, {
+ *   module: 'UserService',
+ *   version: '1.0.0',
+ * });
+ *
+ * userServiceLogger.error('User creation failed', { userId: '123' });
+ * // Email will include: module, version, userId in context
+ * ```
+ */
+function createPinoEmailChildLogger(parentLogger, context) {
+    return parentLogger.child(context);
+}
+/**
+ * Configure Pino email transport from environment variables
+ * This is a convenience function that reads from process.env
+ *
+ * @returns PinoEmailTransport instance or null if not configured
+ *
+ * @example
+ * ```typescript
+ * import { createEmailTransportFromEnv } from '@nest-omni/core';
+ * import pino from 'pino';
+ *
+ * const emailTransport = createEmailTransportFromEnv();
+ * const logger = emailTransport
+ *   ? pino(pino.multistream([
+ *       { level: 'trace', stream: process.stdout },
+ *       { level: 'error', stream: emailTransport },
+ *     ]))
+ *   : pino();
+ * ```
+ */
+function createEmailTransportFromEnv() {
+    const enabled = process.env.EMAIL_LOG_ENABLED === 'true';
+    if (!enabled) {
+        return null;
+    }
+    const options = {
+        enabled: true,
+        to: (process.env.EMAIL_LOG_TO || '').split(',').map(e => e.trim()).filter(Boolean),
+        from: process.env.EMAIL_LOG_FROM || 'noreply@example.com',
+        level: process.env.EMAIL_LOG_LEVEL || 'error',
+        subjectPrefix: process.env.EMAIL_LOG_SUBJECT_PREFIX || '[Log Alert]',
+        smtpHost: process.env.EMAIL_LOG_SMTP_HOST || 'localhost',
+        smtpPort: parseInt(process.env.EMAIL_LOG_SMTP_PORT || '587'),
+        smtpUsername: process.env.EMAIL_LOG_SMTP_USERNAME || '',
+        smtpPassword: process.env.EMAIL_LOG_SMTP_PASSWORD || '',
+        smtpSecure: process.env.EMAIL_LOG_SMTP_SECURE === 'true',
+        smtpIgnoreTLSError: process.env.EMAIL_LOG_SMTP_IGNORE_TLS_ERROR === 'true',
+        rateLimitMaxEmails: parseInt(process.env.EMAIL_LOG_RATE_LIMIT_MAX_EMAILS || '10'),
+        rateLimitWindowMs: parseInt(process.env.EMAIL_LOG_RATE_LIMIT_WINDOW_MS || '60000'),
+        rateLimitBurstSize: parseInt(process.env.EMAIL_LOG_RATE_LIMIT_BURST_SIZE || '3'),
+        useHtmlFormat: process.env.EMAIL_LOG_USE_HTML_FORMAT !== 'false',
+    };
+    return new pino_email_transport_1.PinoEmailTransport(options);
+}

package/file-upload/controllers/file-access.controller.d.ts

@@ -0,0 +1,23 @@
+import { StreamableFile } from '@nestjs/common';
+import { Response } from 'express';
+import { FileService } from '../services/file.service';
+/**
+ * 文件访问控制器
+ * 提供文件下载和预览功能
+ * 注意：Controller 仅负责 HTTP 层逻辑，业务逻辑在 FileService
+ */
+export declare class FileAccessController {
+    private readonly fileService;
+    private readonly logger;
+    constructor(fileService: FileService);
+    /**
+     * 通过文件 ID 下载/访问文件
+     * GET /files/:id
+     */
+    getFile(id: string, res: Response): Promise<StreamableFile>;
+    /**
+     * 通过文件 ID 下载文件（强制下载）
+     * GET /files/:id/download
+     */
+    downloadFile(id: string, res: Response): Promise<StreamableFile>;
+}

package/file-upload/controllers/file-access.controller.js

@@ -0,0 +1,128 @@
+"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 __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var FileAccessController_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileAccessController = void 0;
+const common_1 = require("@nestjs/common");
+const file_service_1 = require("../services/file.service");
+/**
+ * 文件访问控制器
+ * 提供文件下载和预览功能
+ * 注意：Controller 仅负责 HTTP 层逻辑，业务逻辑在 FileService
+ */
+let FileAccessController = FileAccessController_1 = class FileAccessController {
+    constructor(fileService) {
+        this.fileService = fileService;
+        this.logger = new common_1.Logger(FileAccessController_1.name);
+    }
+    /**
+     * 通过文件 ID 下载/访问文件
+     * GET /files/:id
+     */
+    getFile(id, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            // 从数据库获取文件记录
+            const fileEntity = yield this.fileService.findById(id);
+            if (!fileEntity) {
+                throw new common_1.NotFoundException(`文件不存在: ${id}`);
+            }
+            // 检查文件是否可访问
+            if (fileEntity.status !== 'completed') {
+                throw new common_1.NotFoundException(`文件尚未准备就绪: ${id}`);
+            }
+            // 对象存储：重定向到预签名 URL
+            if (['s3', 'oss', 'minio', 'cdn'].includes(fileEntity.storageProvider)) {
+                try {
+                    const signedUrl = yield this.fileService.getSignedUrl(id);
+                    res.redirect(302, signedUrl);
+                    return;
+                }
+                catch (error) {
+                    this.logger.error(`Failed to get signed URL for file ${id}: ${error.message}`);
+                    throw new common_1.NotFoundException(`无法访问文件: ${id}`);
+                }
+            }
+            // 本地存储：流式返回
+            if (fileEntity.storageProvider === 'local') {
+                try {
+                    const stream = yield this.fileService.getFileStream(id);
+                    res.set({
+                        'Content-Type': fileEntity.mimeType,
+                        'Content-Length': fileEntity.size.toString(),
+                    });
+                    return new common_1.StreamableFile(stream);
+                }
+                catch (error) {
+                    this.logger.error(`Failed to stream file ${id}: ${error.message}`);
+                    throw new common_1.NotFoundException(`无法访问文件: ${id}`);
+                }
+            }
+            // 不支持的存储类型
+            throw new common_1.NotFoundException(`不支持的存储类型: ${fileEntity.storageProvider}`);
+        });
+    }
+    /**
+     * 通过文件 ID 下载文件（强制下载）
+     * GET /files/:id/download
+     */
+    downloadFile(id, res) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const fileEntity = yield this.fileService.findById(id);
+            if (!fileEntity) {
+                throw new common_1.NotFoundException(`文件不存在: ${id}`);
+            }
+            if (fileEntity.status !== 'completed') {
+                throw new common_1.NotFoundException(`文件尚未准备就绪: ${id}`);
+            }
+            // 设置下载响应头
+            res.set({
+                'Content-Disposition': `attachment; filename="${encodeURIComponent(fileEntity.originalName)}"`,
+            });
+            // 复用 getFile 逻辑
+            return this.getFile(id, res);
+        });
+    }
+};
+exports.FileAccessController = FileAccessController;
+__decorate([
+    (0, common_1.Get)(':id'),
+    (0, common_1.Header)('Cache-Control', 'public, max-age=31536000') // 缓存1年
+    ,
+    __param(0, (0, common_1.Param)('id')),
+    __param(1, (0, common_1.Res)({ passthrough: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], FileAccessController.prototype, "getFile", null);
+__decorate([
+    (0, common_1.Get)(':id/download'),
+    __param(0, (0, common_1.Param)('id')),
+    __param(1, (0, common_1.Res)({ passthrough: true })),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], FileAccessController.prototype, "downloadFile", null);
+exports.FileAccessController = FileAccessController = FileAccessController_1 = __decorate([
+    (0, common_1.Controller)('files'),
+    __metadata("design:paramtypes", [file_service_1.FileService])
+], FileAccessController);

package/file-upload/decorators/column.decorator.d.ts

@@ -0,0 +1,151 @@
+import 'reflect-metadata';
+/**
+ * CSV列名映射元数据键
+ */
+export declare const CSV_COLUMN_METADATA = "csv:column";
+/**
+ * Excel列名映射元数据键
+ */
+export declare const EXCEL_COLUMN_METADATA = "excel:column";
+/**
+ * 列标识类型
+ * 可以是列名（字符串）、列序号（数字）或Excel列名（A, B, C）
+ */
+export type ColumnIdentifier = string | number;
+/**
+ * CSV列装饰器
+ * 用于指定CSV文件中列与DTO属性的映射关系
+ * 支持列名、列序号（从0开始）或Excel列名（A, B, C）
+ *
+ * @example
+ * ```typescript
+ * export class UserImportDto {
+ *   @CSVColumn('姓名')  // 使用列名
+ *   @CSVColumn(0)       // 使用列序号（第一列）
+ *   @CSVColumn('A')     // 使用Excel列名
+ *   @IsString()
+ *   @Length(2, 50)
+ *   name: string;
+ *
+ *   @CSVColumn('年龄')  // 使用列名
+ *   @CSVColumn(1)       // 使用列序号（第二列）
+ *   @CSVColumn('B')     // 使用Excel列名
+ *   @IsNumber()
+ *   @Min(0)
+ *   @Max(150)
+ *   age: number;
+ * }
+ * ```
+ */
+export declare function CSVColumn(columnIdentifier: ColumnIdentifier): PropertyDecorator;
+/**
+ * Excel列装饰器
+ * 用于指定Excel文件中列与DTO属性的映射关系
+ * 支持列名、列序号（从0开始）或Excel列名（A, B, C）
+ *
+ * @example
+ * ```typescript
+ * export class ProductImportDto {
+ *   @ExcelColumn('产品名称')  // 使用列名
+ *   @ExcelColumn(0)           // 使用列序号（第一列）
+ *   @ExcelColumn('A')         // 使用Excel列名
+ *   @IsString()
+ *   @Length(2, 200)
+ *   name: string;
+ *
+ *   @ExcelColumn('价格')     // 使用列名
+ *   @ExcelColumn(1)           // 使用列序号（第二列）
+ *   @ExcelColumn('B')         // 使用Excel列名
+ *   @IsNumber()
+ *   @Min(0)
+ *   price: number;
+ * }
+ * ```
+ */
+export declare function ExcelColumn(columnIdentifier: ColumnIdentifier): PropertyDecorator;
+/**
+ * 获取CSV列映射信息
+ * 返回列标识到属性名的映射Map
+ *
+ * @param dtoClass DTO类
+ * @returns Map<列标识, 属性名>
+ */
+export declare function getCsvColumnMapping(dtoClass: any): Map<ColumnIdentifier, string>;
+/**
+ * 获取Excel列映射信息
+ * 返回列标识到属性名的映射Map
+ *
+ * @param dtoClass DTO类
+ * @returns Map<列标识, 属性名>
+ */
+export declare function getExcelColumnMapping(dtoClass: any): Map<ColumnIdentifier, string>;
+/**
+ * Excel列名转数字（A=0, B=1, ..., AA=26, AB=27）
+ */
+export declare function excelColumnToNumber(columnLetter: string): number;
+/**
+ * 处理行数据
+ * 将原始数据行转换为DTO实例，支持多语言错误信息
+ * 支持列名、列序号和Excel列名（A, B, C）
+ *
+ * @param rowData 原始行数据
+ * @param dtoClass DTO类
+ * @param columnMapping 列映射
+ * @param type 数据类型（csv/excel）
+ * @returns 转换结果
+ */
+export declare function processRowWithMapping<T>(rowData: any, dtoClass: new () => T, columnMapping: Map<ColumnIdentifier, string>, type: 'csv' | 'excel'): {
+    instance: T;
+    errors: ValidationError[];
+};
+/**
+ * 数字转Excel列名（0=A, 1=B, ..., 26=AA, 27=AB）
+ */
+export declare function numberToExcelColumn(num: number): string;
+/**
+ * 验证错误接口
+ */
+interface ValidationError {
+    property: string;
+    value: any;
+    constraints: {
+        [key: string]: {
+            message: string;
+            values?: any[];
+        };
+    };
+}
+/**
+ * 格式化验证错误为多语言
+ * 支持中英文错误信息
+ *
+ * @param errors class-validator错误数组
+ * @returns 格式化后的错误信息
+ */
+export declare function formatValidationErrors(errors: ValidationError[]): string[];
+/**
+ * 创建CSV数据导入结果
+ * @param data 成功导入的数据
+ * @param errors 错误信息
+ * @param totalRows 总行数
+ * @param headers 表头信息
+ * @returns 导入结果对象
+ */
+export declare function createImportResult<T>(data: T[], errors: {
+    row: number;
+    errors: string[];
+    data: any;
+}[], totalRows: number, headers?: string[]): {
+    success: boolean;
+    data: T[];
+    errors: {
+        row: number;
+        errors: string[];
+        data: any;
+    }[];
+    totalCount: number;
+    successCount: number;
+    errorCount: number;
+    headers?: string[];
+};
+export {};