@nest-omni/core 4.1.3-10 → 4.1.3-12

package/file-upload/utils/filename.util.js

@@ -0,0 +1,184 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileNameUtil = void 0;
+const path = require("path");
+/**
+ * 文件名处理工具类
+ * 统一管理文件名的编码、清理、截取等操作
+ */
+class FileNameUtil {
+    /**
+     * 解码并标准化文件名
+     * 1. Multer 默认使用 Latin1 解码，需要转换为 UTF-8
+     * 2. 移除特殊字符和控制字符
+     * 3. 截取超长文件名到指定长度
+     *
+     * @param filename 原始文件名
+     * @param maxLength 最大长度（默认 100 字符）
+     * @returns 处理后的文件名
+     */
+    static decodeAndNormalize(filename, maxLength = 100) {
+        if (!filename) {
+            return 'unknown';
+        }
+        let decoded;
+        // 尝试从 Latin1 转换（这是 Multer 的常见情况）
+        try {
+            const buffer = Buffer.from(filename, 'latin1');
+            decoded = buffer.toString('utf8');
+            // 检查转换结果是否包含 UTF-8 替换字符（表示可能有乱码）
+            if (!decoded.includes('\uFFFD') && this.hasValidCharacters(decoded)) {
+                // 转换成功且看起来有效
+            }
+            else {
+                // 可能不是 Latin1 编码，保持原始字符串
+                decoded = filename;
+            }
+        }
+        catch (_a) {
+            // 转换失败，保持原始字符串
+            decoded = filename;
+        }
+        // 移除不可见控制字符（但保留换行符）
+        decoded = decoded.replace(/[\x00-\x08\x0B-\x0C\x0E-\x1F\x7F-\x9F]/g, '');
+        // 移除常见乱码字符（替换符）
+        decoded = decoded.replace(/\uFFFD/g, '');
+        // 移除前后空格
+        decoded = decoded.trim();
+        // 截取长度（按字符数，不是字节数）
+        if (decoded.length > maxLength) {
+            return this.truncateWithExtension(decoded, maxLength);
+        }
+        return decoded;
+    }
+    /**
+     * 智能截取文件名（保留扩展名）
+     *
+     * @param filename 文件名
+     * @param maxLength 最大长度
+     * @returns 截取后的文件名
+     */
+    static truncateWithExtension(filename, maxLength) {
+        // 如果文件名长度不超过限制，直接返回
+        if (filename.length <= maxLength) {
+            return filename;
+        }
+        // 保留文件扩展名
+        const extMatch = filename.match(/\.[^.]+$/);
+        const ext = extMatch ? extMatch[0] : '';
+        const nameWithoutExt = ext ? filename.slice(0, -ext.length) : filename;
+        // 如果没有扩展名，直接截断到指定长度
+        if (!ext) {
+            return filename.slice(0, maxLength);
+        }
+        // 计算可用的文件名长度
+        const availableLength = maxLength - ext.length - 3; // 预留 3 个字符用于 "..."
+        if (availableLength > 0) {
+            return nameWithoutExt.slice(0, availableLength) + '...' + ext;
+        }
+        else {
+            // 如果扩展名本身就超过限制，直接截取
+            return filename.slice(0, maxLength);
+        }
+    }
+    /**
+     * 清理文件名（移除危险字符）
+     * 移除路径遍历、路径分隔符、控制字符等
+     *
+     * @param filename 文件名
+     * @returns 清理后的文件名
+     */
+    static sanitize(filename) {
+        // 移除路径遍历字符
+        let sanitized = filename.replace(/\.\./g, '');
+        // 移除路径分隔符
+        sanitized = sanitized.replace(/[\/\\]/g, '');
+        // 移除控制字符
+        sanitized = sanitized.replace(/[\x00-\x1f\x80-\x9f]/g, '');
+        // 保留空格，只替换其他特殊字符
+        sanitized = sanitized.replace(/[^a-zA-Z0-9.\-_\s\u4e00-\u9fa5]/g, '_');
+        // 移除前导/尾随空格和点
+        sanitized = sanitized
+            .trim()
+            .replace(/^\.+|\.+$/g, '')
+            .replace(/^_+|_+$/g, '');
+        return sanitized;
+    }
+    /**
+     * 清理并保留原始文件名结构
+     * 先解码 UTF-8，再清理危险字符
+     *
+     * @param filename 文件名
+     * @returns 清理后的文件名
+     */
+    static sanitizeOriginal(filename) {
+        // 1. 解码 UTF-8
+        const decoded = this.decodeAndNormalize(filename);
+        // 2. 移除路径遍历字符
+        let sanitized = decoded.replace(/\.\./g, '');
+        sanitized = sanitized.replace(/[\/\\]/g, '');
+        // 3. 移除控制字符
+        sanitized = sanitized.replace(/[\x00-\x1f\x80-\x9f]/g, '');
+        // 4. 移除前导/尾随空格和点
+        sanitized = sanitized.trim().replace(/^\.+|\.+$/g, '');
+        return sanitized;
+    }
+    /**
+     * 提取文件扩展名
+     *
+     * @param filename 文件名
+     * @returns 扩展名（包含点）或空字符串
+     */
+    static extractExtension(filename) {
+        const lastDotIndex = filename.lastIndexOf('.');
+        // 如果没有点、点是第一个字符（隐藏文件）、或点是最后一个字符
+        if (lastDotIndex === -1 ||
+            lastDotIndex === 0 ||
+            lastDotIndex === filename.length - 1) {
+            return '';
+        }
+        return filename.substring(lastDotIndex);
+    }
+    /**
+     * 获取不包含扩展名的文件名
+     *
+     * @param filename 文件名
+     * @returns 不包含扩展名的文件名
+     */
+    static getBaseName(filename) {
+        return path.basename(filename, this.extractExtension(filename));
+    }
+    /**
+     * 检查字符串是否包含有效的字符
+     */
+    static hasValidCharacters(str) {
+        // 如果字符串太短，无法判断
+        if (str.length === 0)
+            return true;
+        // 计算有效字符的比例
+        let validCount = 0;
+        for (let i = 0; i < str.length; i++) {
+            const char = str[i];
+            const code = char.charCodeAt(0);
+            // ASCII 可打印字符
+            if (code >= 0x20 && code <= 0x7e) {
+                validCount++;
+            }
+            // 基本拉丁字母扩展
+            else if (code >= 0xa0 && code <= 0xff) {
+                validCount++;
+            }
+            // 中文、日文、韩文等 CJK 字符
+            else if (code >= 0x4e00 && code <= 0x9fff) {
+                validCount++;
+            }
+            // 其他 Unicode 字符
+            else if (code > 0xff) {
+                validCount++;
+            }
+        }
+        // 如果超过 70% 的字符是有效的，认为是有效的字符串
+        return validCount / str.length > 0.7;
+    }
+}
+exports.FileNameUtil = FileNameUtil;

package/file-upload/utils/filepath.util.d.ts

@@ -0,0 +1,70 @@
+/**
+ * 文件路径处理工具类
+ * 统一管理文件上传路径、相对路径转换等操作
+ */
+export declare class FilePathUtil {
+    /**
+     * 获取上传根目录
+     * 优先使用环境变量 FILE_UPLOAD_PATH，否则使用 process.cwd()/uploads
+     *
+     * @returns 上传根目录的绝对路径
+     */
+    static getUploadDir(): string;
+    /**
+     * 生成日期子目录格式 (YYYY/MM/DD)
+     *
+     * @returns 日期子目录路径
+     */
+    static getDateSubdirectory(): string;
+    /**
+     * 获取完整的上传目录（包含日期子目录）
+     *
+     * @returns 完整的上传目录路径
+     */
+    static getFullUploadPath(): string;
+    /**
+     * 将绝对路径转换为相对路径（相对于上传根目录）
+     * 例如: /Users/.../uploads/2025/11/30/xxx.txt -> 2025/11/30/xxx.txt
+     *
+     * @param absolutePath 绝对路径
+     * @returns 相对路径
+     */
+    static toRelativePath(absolutePath: string): string;
+    /**
+     * 将相对路径转换为绝对路径（物理路径）
+     * 例如: 2025/11/30/xxx.txt -> /Users/.../uploads/2025/11/30/xxx.txt
+     *
+     * @param relativePath 相对路径
+     * @returns 绝对路径
+     */
+    static toAbsolutePath(relativePath: string): string;
+    /**
+     * 规范化路径（统一使用正斜杠）
+     *
+     * @param filePath 文件路径
+     * @returns 规范化后的路径
+     */
+    static normalize(filePath: string): string;
+    /**
+     * 检查路径是否为绝对路径
+     *
+     * @param filePath 文件路径
+     * @returns 是否为绝对路径
+     */
+    static isAbsolute(filePath: string): boolean;
+    /**
+     * 检查文件是否存在
+     *
+     * @param filePath 文件路径（绝对或相对）
+     * @returns 文件是否存在
+     */
+    static exists(filePath: string): boolean;
+    /**
+     * 获取文件的物理路径（用于文件系统访问）
+     *
+     * @param relativePath 相对路径
+     * @param storageProvider 存储提供商
+     * @returns 物理路径或相对路径（对象存储）
+     */
+    static getPhysicalPath(relativePath: string, storageProvider?: string): string;
+}

package/file-upload/utils/filepath.util.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FilePathUtil = void 0;
+const path = require("path");
+const fs = require("fs");
+/**
+ * 文件路径处理工具类
+ * 统一管理文件上传路径、相对路径转换等操作
+ */
+class FilePathUtil {
+    /**
+     * 获取上传根目录
+     * 优先使用环境变量 FILE_UPLOAD_PATH，否则使用 process.cwd()/uploads
+     *
+     * @returns 上传根目录的绝对路径
+     */
+    static getUploadDir() {
+        const uploadPath = process.env.FILE_UPLOAD_PATH || path.join(process.cwd(), 'uploads');
+        // 确保目录存在
+        if (!fs.existsSync(uploadPath)) {
+            fs.mkdirSync(uploadPath, { recursive: true });
+        }
+        return uploadPath;
+    }
+    /**
+     * 生成日期子目录格式 (YYYY/MM/DD)
+     *
+     * @returns 日期子目录路径
+     */
+    static getDateSubdirectory() {
+        const now = new Date();
+        const year = now.getFullYear();
+        const month = String(now.getMonth() + 1).padStart(2, '0');
+        const day = String(now.getDate()).padStart(2, '0');
+        return path.join(String(year), month, day);
+    }
+    /**
+     * 获取完整的上传目录（包含日期子目录）
+     *
+     * @returns 完整的上传目录路径
+     */
+    static getFullUploadPath() {
+        const basePath = this.getUploadDir();
+        const subDir = this.getDateSubdirectory();
+        const fullPath = path.join(basePath, subDir);
+        // 确保目录存在
+        if (!fs.existsSync(fullPath)) {
+            fs.mkdirSync(fullPath, { recursive: true });
+        }
+        return fullPath;
+    }
+    /**
+     * 将绝对路径转换为相对路径（相对于上传根目录）
+     * 例如: /Users/.../uploads/2025/11/30/xxx.txt -> 2025/11/30/xxx.txt
+     *
+     * @param absolutePath 绝对路径
+     * @returns 相对路径
+     */
+    static toRelativePath(absolutePath) {
+        if (!absolutePath) {
+            return '';
+        }
+        const uploadDir = this.getUploadDir();
+        // 方法1: 使用 startsWith 精确匹配
+        if (absolutePath.startsWith(uploadDir)) {
+            return absolutePath.substring(uploadDir.length).replace(/^[\/\\]+/, '');
+        }
+        // 方法2: 兼容处理 - 如果包含 /uploads/，从该位置开始截取
+        if (absolutePath.includes('/uploads/')) {
+            const uploadIndex = absolutePath.indexOf('/uploads/');
+            return absolutePath.substring(uploadIndex + '/uploads/'.length);
+        }
+        // 方法3: 兼容 Windows 路径
+        if (absolutePath.includes('\\uploads\\')) {
+            const uploadIndex = absolutePath.indexOf('\\uploads\\');
+            return absolutePath
+                .substring(uploadIndex + '\\uploads\\'.length)
+                .replace(/\\/g, '/');
+        }
+        // 如果都不匹配，返回原路径
+        return absolutePath;
+    }
+    /**
+     * 将相对路径转换为绝对路径（物理路径）
+     * 例如: 2025/11/30/xxx.txt -> /Users/.../uploads/2025/11/30/xxx.txt
+     *
+     * @param relativePath 相对路径
+     * @returns 绝对路径
+     */
+    static toAbsolutePath(relativePath) {
+        if (!relativePath) {
+            return '';
+        }
+        const uploadDir = this.getUploadDir();
+        return path.join(uploadDir, relativePath);
+    }
+    /**
+     * 规范化路径（统一使用正斜杠）
+     *
+     * @param filePath 文件路径
+     * @returns 规范化后的路径
+     */
+    static normalize(filePath) {
+        return filePath.replace(/\\/g, '/');
+    }
+    /**
+     * 检查路径是否为绝对路径
+     *
+     * @param filePath 文件路径
+     * @returns 是否为绝对路径
+     */
+    static isAbsolute(filePath) {
+        return path.isAbsolute(filePath);
+    }
+    /**
+     * 检查文件是否存在
+     *
+     * @param filePath 文件路径（绝对或相对）
+     * @returns 文件是否存在
+     */
+    static exists(filePath) {
+        const absolutePath = this.isAbsolute(filePath)
+            ? filePath
+            : this.toAbsolutePath(filePath);
+        return fs.existsSync(absolutePath);
+    }
+    /**
+     * 获取文件的物理路径（用于文件系统访问）
+     *
+     * @param relativePath 相对路径
+     * @param storageProvider 存储提供商
+     * @returns 物理路径或相对路径（对象存储）
+     */
+    static getPhysicalPath(relativePath, storageProvider = 'local') {
+        if (!relativePath) {
+            return '';
+        }
+        switch (storageProvider) {
+            case 'local':
+                return this.toAbsolutePath(relativePath);
+            case 's3':
+            case 'oss':
+            case 'minio':
+            case 'cdn':
+                // 对象存储返回相对路径，由存储服务处理
+                return relativePath;
+            default:
+                return relativePath;
+        }
+    }
+}
+exports.FilePathUtil = FilePathUtil;

package/file-upload/utils/index.d.ts

@@ -0,0 +1,4 @@
+export * from './dynamic-import.util';
+export * from './checksum.util';
+export * from './filename.util';
+export * from './filepath.util';

package/file-upload/utils/index.js

@@ -0,0 +1,20 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./dynamic-import.util"), exports);
+__exportStar(require("./checksum.util"), exports);
+__exportStar(require("./filename.util"), exports);
+__exportStar(require("./filepath.util"), exports);

package/http-client/http-client.module.js

@@ -18,7 +18,6 @@ var HttpClientModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.HttpClientModule = void 0;
 const common_1 = require("@nestjs/common");
-const schedule_1 = require("@nestjs/schedule");
 const config_1 = require("@nestjs/config");
 const typeorm_1 = require("@nestjs/typeorm");
 const cache_service_1 = require("../cache/cache.service");
@@ -41,7 +40,7 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
      * 动态注册HTTP客户端模块
      */
     static forRoot(config = {}) {
-        var _a, _b, _c;
+        var _a, _b;
         // 基础服务提供者
         const baseProviders = [
             {
@@ -87,9 +86,6 @@ let HttpClientModule = HttpClientModule_1 = class HttpClientModule {
         if ((_b = (_a = config.logging) === null || _a === void 0 ? void 0 : _a.databaseLogging) === null || _b === void 0 ? void 0 : _b.enabled) {
             dynamicImports.push(typeorm_1.TypeOrmModule.forFeature([entities_1.HttpLogEntity]));
         }
-        if ((_c = config.logCleanup) === null || _c === void 0 ? void 0 : _c.enabled) {
-            dynamicImports.push(schedule_1.ScheduleModule.forRoot());
-        }
         return {
             module: HttpClientModule_1,
             imports: dynamicImports,

package/index.d.ts

@@ -1,3 +1,4 @@
+export * from './common';
 export * from './constants';
 export * from './decorators';
 export * from './exceptions';
@@ -7,10 +8,10 @@ export * from './interceptors';
 export * from './shared';
 export * from './middlewares';
 export * from './validators';
-export * from './common';
 export * from './validator-json';
 export * from './helpers';
 export * from './providers';
+export * from './transaction';
 export * from './redis-lock';
 export * from './cache';
 export * from './http-client';
@@ -18,3 +19,4 @@ export * from './vault';
 export * from './setup';
 export * from './health-checker';
 export * from './audit';
+export * from './file-upload';

package/index.js

@@ -15,6 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 // Core modules
+__exportStar(require("./common"), exports);
 __exportStar(require("./constants"), exports);
 __exportStar(require("./decorators"), exports);
 __exportStar(require("./exceptions"), exports);
@@ -24,10 +25,10 @@ __exportStar(require("./interceptors"), exports);
 __exportStar(require("./shared"), exports);
 __exportStar(require("./middlewares"), exports);
 __exportStar(require("./validators"), exports);
-__exportStar(require("./common"), exports);
 __exportStar(require("./validator-json"), exports);
 __exportStar(require("./helpers"), exports);
 __exportStar(require("./providers"), exports);
+__exportStar(require("./transaction"), exports);
 // Lock module
 __exportStar(require("./redis-lock"), exports);
 // Cache module
@@ -42,3 +43,5 @@ __exportStar(require("./setup"), exports);
 __exportStar(require("./health-checker"), exports);
 // Audit module
 __exportStar(require("./audit"), exports);
+// File upload module
+__exportStar(require("./file-upload"), exports);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nest-omni/core",
-  "version": "4.1.3-10",
+  "version": "4.1.3-12",
   "description": "A comprehensive NestJS framework for building enterprise-grade applications with best practices",
   "main": "index.js",
   "types": "index.d.ts",
@@ -47,13 +47,12 @@
     "@types/node": "^24.9.1",
     "@types/sprintf-js": "^1.1.4",
     "@types/uuid": "^11.0.0",
+    "sqlite3": "^5.1.7",
     "typescript": "^5.9.3"
   },
   "dependencies": {
     "@dataui/crud": "^5.3.4",
     "@dataui/crud-typeorm": "^5.3.4",
-    "@nestjs-cls/transactional": "^3.1.0",
-    "@nestjs-cls/transactional-adapter-typeorm": "^1.3.0",
     "@nestjs/bull": "^11.0.4",
     "@nestjs/common": "^11.1.7",
     "@nestjs/config": "^4.0.2",
@@ -89,6 +88,7 @@
     "nestjs-cls": "^6.0.1",
     "nestjs-i18n": "^10.5.1",
     "nestjs-pino": "^4.4.1",
+    "node-vault": "^0.10.9",
     "pino-http": "^11.0.0",
     "pino-pretty": "^13.1.2",
     "reflect-metadata": "^0.2.2",
@@ -96,7 +96,6 @@
     "source-map-support": "^0.5.21",
     "sprintf-js": "^1.1.3",
     "typeorm": "^0.3.27",
-    "uuid": "^13.0.0",
-    "node-vault": "^0.10.9"
+    "uuid": "^13.0.0"
   }
 }

package/redis-lock/lock-heartbeat.service.d.ts

@@ -23,12 +23,12 @@ export declare class LockHeartbeatService implements OnModuleInit, OnModuleDestr
     private heartbeatTimer;
     /**
      * Heartbeat interval in milliseconds
-     * @default 10000 (10 seconds)
+     * @default 5000 (5 seconds) - reduced for faster failure detection
      */
     private readonly heartbeatInterval;
     /**
      * Heartbeat TTL in seconds (3x interval for safety)
-     * @default 30 (30 seconds)
+     * @default 15 (15 seconds) - adjusted to match new interval
      */
     private readonly heartbeatTtl;
     constructor();

package/redis-lock/lock-heartbeat.service.js

@@ -44,14 +44,14 @@ let LockHeartbeatService = LockHeartbeatService_1 = class LockHeartbeatService {
         this.heartbeatTimer = null;
         /**
          * Heartbeat interval in milliseconds
-         * @default 10000 (10 seconds)
+         * @default 5000 (5 seconds) - reduced for faster failure detection
          */
-        this.heartbeatInterval = 10000;
+        this.heartbeatInterval = 5000;
         /**
          * Heartbeat TTL in seconds (3x interval for safety)
-         * @default 30 (30 seconds)
+         * @default 15 (15 seconds) - adjusted to match new interval
          */
-        this.heartbeatTtl = 30;
+        this.heartbeatTtl = 15;
         this.instanceId = this.getInstanceId();
     }
     onModuleInit() {

package/redis-lock/redis-lock.service.d.ts

@@ -69,6 +69,24 @@ export interface LockOptions {
      * @default 0 (no automatic extension)
      */
     autoExtend?: number;
+    /**
+     * Whether to use exponential backoff for retry attempts
+     * If true, retry delay will increase exponentially: retryDelay * 2^(attempt-1)
+     * @default false
+     */
+    useExponentialBackoff?: boolean;
+    /**
+     * Maximum retry delay in milliseconds when using exponential backoff
+     * Ensures retry delay doesn't grow indefinitely
+     * @default 60000 (60 seconds)
+     */
+    maxRetryDelay?: number;
+    /**
+     * Random jitter to add to retry delay in milliseconds
+     * Helps prevent synchronized retries across multiple instances
+     * @default 0 (no jitter)
+     */
+    retryJitter?: number;
 }
 export interface LockResult {
     /**