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

package/audit/services/manual-audit-log.service.js

@@ -30,14 +30,67 @@ const entities_1 = require("../entities");
 const audit_context_service_1 = require("./audit-context.service");
 const enums_1 = require("../enums");
 const crypto_1 = require("crypto");
+/**
+ * 手动审计日志服务
+ *
+ * 提供全局静态方法，在任意地方手动记录操作日志
+ */
 let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogService {
     constructor(manualLogRepository, transactionRepository, contextService, dataSource) {
         this.manualLogRepository = manualLogRepository;
         this.transactionRepository = transactionRepository;
         this.contextService = contextService;
         this.dataSource = dataSource;
+        // 设置静态实例
         ManualAuditLogService_1.instance = this;
     }
+    /**
+     * 全局静态方法：记录操作日志
+     *
+     * @description
+     * 支持三种记录模式：
+     * 1. 模板键模式：从数据库查找模板
+     * 2. 直接描述模式：直接传入字符串或多语言描述
+     * 3. 内联模板模式：传入多语言模板 + 参数
+     *
+     * @example
+     * // 模式1：模板键模式
+     * await ManualAuditLogService.log({
+     *   templateKey: 'user.login',
+     *   descriptionParams: {
+     *     username: 'john.doe',
+     *     loginTime: new Date().toISOString(),
+     *   },
+     * });
+     *
+     * @example
+     * // 模式2：直接描述模式（字符串）
+     * await ManualAuditLogService.log({
+     *   description: '用户登录系统',
+     * });
+     *
+     * @example
+     * // 模式2：直接描述模式（多语言）
+     * await ManualAuditLogService.log({
+     *   description: {
+     *     zh: '用户登录系统',
+     *     en: 'User logged in',
+     *   },
+     * });
+     *
+     * @example
+     * // 模式3：内联模板模式
+     * await ManualAuditLogService.log({
+     *   descriptionTemplate: {
+     *     zh: '用户 {username} 在 {time} 登录了系统',
+     *     en: 'User {username} logged in at {time}',
+     *   },
+     *   descriptionParams: {
+     *     username: 'john.doe',
+     *     time: new Date().toISOString(),
+     *   },
+     * });
+     */
     static log(options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
@@ -46,30 +99,44 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             return ManualAuditLogService_1.instance.logOperation(options);
         });
     }
+    /**
+     * 实例方法：记录操作日志
+     */
     logOperation(options) {
         return __awaiter(this, void 0, void 0, function* () {
             const { templateKey, description, descriptionTemplate, descriptionParams, userId, username, requestIp, rollbackActions, transactionId, autoCreateTransaction = true, } = options;
+            // 验证参数：至少提供一种模式
             if (!templateKey && !description && !descriptionTemplate) {
                 throw new Error('ManualAuditLogService.log() requires one of: templateKey, description, or descriptionTemplate');
             }
+            // 验证参数冲突
             const modeCount = [templateKey, description, descriptionTemplate].filter(Boolean).length;
             if (modeCount > 1) {
                 throw new Error('ManualAuditLogService.log() accepts only one mode: use either templateKey, description, or descriptionTemplate');
             }
+            // 获取当前上下文（如果有）
             const context = yield this.contextService.getCurrentContext();
+            // 合并用户信息（优先使用传入的参数）
             const finalUserId = userId || context.userId || 'system';
             const finalUsername = username || context.username || 'system';
             const finalRequestIp = requestIp || context.requestIp || 'unknown';
+            // 生成或使用事务ID
             let finalTransactionId = transactionId || context.transactionId;
             if (!finalTransactionId && autoCreateTransaction) {
+                // 自动创建事务
                 finalTransactionId = yield this.createTransaction(finalUserId, finalUsername);
             }
+            // 创建手动操作日志
             const manualLog = this.manualLogRepository.create({
                 transactionId: finalTransactionId,
+                // 模式1: 模板键模式
                 operationTemplateKey: templateKey || null,
                 descriptionParams: descriptionParams || null,
+                // 模式2: 直接描���模式
                 directDescription: description || null,
+                // 模式3: 内联模板模式
                 inlineTemplate: descriptionTemplate || null,
+                // 通用字段
                 userId: finalUserId,
                 username: finalUsername,
                 requestIp: finalRequestIp,
@@ -78,6 +145,30 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             return this.manualLogRepository.save(manualLog);
         });
     }
+    /**
+     * 静态方法：带事务记录
+     *
+     * @example
+     * ```typescript
+     * const txId = await ManualAuditLogService.beginTransaction('user-123', 'John Doe');
+     *
+     * await ManualAuditLogService.log({
+     *   templateKey: 'order.create',
+     *   descriptionParams: { orderId: 'order-1' },
+     *   transactionId: txId,
+     *   autoCreateTransaction: false,
+     * });
+     *
+     * await ManualAuditLogService.log({
+     *   templateKey: 'payment.process',
+     *   descriptionParams: { paymentId: 'pay-1' },
+     *   transactionId: txId,
+     *   autoCreateTransaction: false,
+     * });
+     *
+     * await ManualAuditLogService.commitTransaction(txId);
+     * ```
+     */
     static beginTransaction(userId, username) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
@@ -86,6 +177,9 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             return ManualAuditLogService_1.instance.createTransaction(userId, username);
         });
     }
+    /**
+     * 静态方法：提交事务
+     */
     static commitTransaction(transactionId) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
@@ -94,6 +188,9 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             yield ManualAuditLogService_1.instance.updateTransactionStatus(transactionId, enums_1.TransactionStatus.COMMITTED);
         });
     }
+    /**
+     * 静态方法：回滚事务
+     */
     static rollbackTransaction(transactionId) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
@@ -102,6 +199,9 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             yield ManualAuditLogService_1.instance.updateTransactionStatus(transactionId, enums_1.TransactionStatus.ROLLED_BACK);
         });
     }
+    /**
+     * 创建事务
+     */
     createTransaction(userId, username) {
         return __awaiter(this, void 0, void 0, function* () {
             const context = yield this.contextService.getCurrentContext();
@@ -117,19 +217,53 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             return saved.id;
         });
     }
+    /**
+     * 更新事务状态
+     */
     updateTransactionStatus(transactionId, status) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.transactionRepository.update({ id: transactionId }, { status });
         });
     }
+    /**
+     * 生成事务ID
+     */
     generateTransactionId() {
         return `txn-${Date.now()}-${(0, crypto_1.randomBytes)(8).toString('hex')}`;
     }
+    /**
+     * 批量记录操作日志
+     *
+     * @description
+     * 批量记录多个操作，支持所有三种记录模式
+     *
+     * @example
+     * ```typescript
+     * // 混合使用多种模式
+     * await ManualAuditLogService.logBatch([
+     *   {
+     *     templateKey: 'product.update',
+     *     descriptionParams: { productId: 'p1', field: 'price' },
+     *   },
+     *   {
+     *     description: '批量更新库存',
+     *   },
+     *   {
+     *     descriptionTemplate: {
+     *       zh: '更新产品 {productId} 的 {field}',
+     *       en: 'Update {field} of product {productId}',
+     *     },
+     *     descriptionParams: { productId: 'p3', field: 'stock' },
+     *   },
+     * ]);
+     * ```
+     */
     static logBatch(operations, sharedTransactionId) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
                 throw new Error('ManualAuditLogService is not initialized');
             }
+            // 创建共享事务ID
             const transactionId = sharedTransactionId ||
                 (yield ManualAuditLogService_1.instance.createTransaction());
             const results = [];
@@ -137,12 +271,16 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
                 const result = yield ManualAuditLogService_1.instance.logOperation(Object.assign(Object.assign({}, operation), { transactionId, autoCreateTransaction: false }));
                 results.push(result);
             }
+            // 自动提交事务（如果是自动创建的）
             if (!sharedTransactionId) {
                 yield ManualAuditLogService_1.instance.updateTransactionStatus(transactionId, enums_1.TransactionStatus.COMMITTED);
             }
             return results;
         });
     }
+    /**
+     * 查询操作日志
+     */
     static findLogs(options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {

package/audit/services/multi-database.service.d.ts

@@ -1,10 +1,22 @@
 import { DataSource } from 'typeorm';
 import { ModuleRef } from '@nestjs/core';
+/**
+ * 多数据库连接管理服务
+ */
 export declare class MultiDatabaseService {
     private readonly moduleRef;
     private readonly config?;
     constructor(moduleRef: ModuleRef, config?: any);
+    /**
+     * 获取指定连接的 DataSource
+     */
     getDataSource(connectionName?: string): Promise<DataSource>;
+    /**
+     * 获取所有监听的数据库连接
+     */
     getMonitoredConnections(): string[];
+    /**
+     * 获取审计日志存储的数据库连接
+     */
     getAuditConnection(): string;
 }

package/audit/services/multi-database.service.js

@@ -25,11 +25,17 @@ exports.MultiDatabaseService = void 0;
 const common_1 = require("@nestjs/common");
 const typeorm_1 = require("@nestjs/typeorm");
 const core_1 = require("@nestjs/core");
+/**
+ * 多数据库连接管理服务
+ */
 let MultiDatabaseService = class MultiDatabaseService {
     constructor(moduleRef, config) {
         this.moduleRef = moduleRef;
         this.config = config;
     }
+    /**
+     * 获取指定连接的 DataSource
+     */
     getDataSource() {
         return __awaiter(this, arguments, void 0, function* (connectionName = 'default') {
             try {
@@ -41,10 +47,16 @@ let MultiDatabaseService = class MultiDatabaseService {
             }
         });
     }
+    /**
+     * 获取所有监听的数据库连接
+     */
     getMonitoredConnections() {
         var _a, _b;
         return ((_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.connections) === null || _b === void 0 ? void 0 : _b.monitored) || ['default'];
     }
+    /**
+     * 获取审计日志存储的数据库连接
+     */
     getAuditConnection() {
         var _a, _b;
         return ((_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.connections) === null || _b === void 0 ? void 0 : _b.audit) || 'default';

package/audit/services/operation-description.service.d.ts

@@ -1,6 +1,10 @@
 import { Repository } from 'typeorm';
 import { OperationTemplateEntity, EntityTransactionEntity, EntityAuditLogEntity, ManualOperationLogEntity } from '../entities';
 import { ChangeDetail, TransactionDescription } from '../interfaces';
+/**
+ * 操作描述服务
+ * 负责根据模板和参数动态生成多语言描述
+ */
 export declare class OperationDescriptionService {
     private readonly templateRepository;
     private readonly transactionRepository;
@@ -8,14 +12,69 @@ export declare class OperationDescriptionService {
     private readonly manualOperationRepository;
     private templateCache;
     constructor(templateRepository: Repository<OperationTemplateEntity>, transactionRepository: Repository<EntityTransactionEntity>, auditLogRepository: Repository<EntityAuditLogEntity>, manualOperationRepository: Repository<ManualOperationLogEntity>);
+    /**
+     * 动态生成操作名称
+     * @param templateKey 模板键
+     * @param language 语言
+     * @returns 操作名称
+     */
     generateOperationName(templateKey: string, language?: string): Promise<string>;
+    /**
+     * 动态生成操作描述
+     * @param templateKey 模板键
+     * @param descriptionParams 描述参数
+     * @param language 语言
+     * @returns 描述文本
+     */
     generateDescription(templateKey: string, descriptionParams: Record<string, any>, language?: string): Promise<string>;
+    /**
+     * 动态生成变更详情
+     * @param changeDetails 变更详情列表
+     * @param language 语言
+     * @returns 格式化的变更详情
+     */
     generateChangeDetails(changeDetails: ChangeDetail[], language?: string): Promise<any[]>;
+    /**
+     * 获取事务描述（包含所有变更）
+     * @param transactionId 事务ID
+     * @param language 语言
+     * @returns 事务描述对象
+     */
     getTransactionDescription(transactionId: string, language?: string): Promise<TransactionDescription>;
+    /**
+     * 批量获取事务描述
+     * @param transactionIds 事务ID列表
+     * @param language 语言
+     * @returns 事务描述映射
+     */
     batchGetTransactionDescriptions(transactionIds: string[], language?: string): Promise<Record<string, TransactionDescription>>;
+    /**
+     * 填充模板
+     * @param template 模板字符串
+     * @param params 参数
+     * @returns 填充后的字符串
+     */
     private fillTemplate;
+    /**
+     * 格式化显示值
+     * @param value 原始值
+     * @param displayValue 显示值
+     * @returns 格式化后的值
+     */
     private formatDisplayValue;
+    /**
+     * 获取操作模板（带缓存）
+     * @param templateKey 模板键
+     * @returns 操作模板
+     */
     private getOperationTemplate;
+    /**
+     * 清除模板缓存
+     */
     clearTemplateCache(): void;
+    /**
+     * 预加载模板到缓存
+     * @param templateKeys 模板键列表
+     */
     preloadTemplates(templateKeys: string[]): Promise<void>;
 }

package/audit/services/operation-description.service.js

@@ -26,33 +26,57 @@ const common_1 = require("@nestjs/common");
 const typeorm_1 = require("@nestjs/typeorm");
 const typeorm_2 = require("typeorm");
 const entities_1 = require("../entities");
+/**
+ * 操作描述服务
+ * 负责根据模板和参数动态生成多语言描述
+ */
 let OperationDescriptionService = class OperationDescriptionService {
     constructor(templateRepository, transactionRepository, auditLogRepository, manualOperationRepository) {
         this.templateRepository = templateRepository;
         this.transactionRepository = transactionRepository;
         this.auditLogRepository = auditLogRepository;
         this.manualOperationRepository = manualOperationRepository;
+        // 模板缓存
         this.templateCache = new Map();
     }
+    /**
+     * 动态生成操作名称
+     * @param templateKey 模板键
+     * @param language 语言
+     * @returns 操作名称
+     */
     generateOperationName(templateKey_1) {
         return __awaiter(this, arguments, void 0, function* (templateKey, language = 'zh') {
             const template = yield this.getOperationTemplate(templateKey);
             if (!template) {
-                return templateKey;
+                return templateKey; // 如果没有模板，返回模板键
             }
             return template.nameTemplates[language] || template.nameTemplates['zh'] || templateKey;
         });
     }
+    /**
+     * 动态生成操作描述
+     * @param templateKey 模板键
+     * @param descriptionParams 描述参数
+     * @param language 语言
+     * @returns 描述文本
+     */
     generateDescription(templateKey_1, descriptionParams_1) {
         return __awaiter(this, arguments, void 0, function* (templateKey, descriptionParams, language = 'zh') {
             const template = yield this.getOperationTemplate(templateKey);
             if (!template) {
-                return templateKey;
+                return templateKey; // 如果没有模板，返回模板键
             }
             const templateStr = template.descriptionTemplates[language] || template.descriptionTemplates['zh'] || templateKey;
             return this.fillTemplate(templateStr, descriptionParams);
         });
     }
+    /**
+     * 动态生成变更详情
+     * @param changeDetails 变更详情列表
+     * @param language 语言
+     * @returns 格式化的变更详情
+     */
     generateChangeDetails(changeDetails_1) {
         return __awaiter(this, arguments, void 0, function* (changeDetails, language = 'zh') {
             return changeDetails.map((detail) => {
@@ -67,22 +91,32 @@ let OperationDescriptionService = class OperationDescriptionService {
             });
         });
     }
+    /**
+     * 获取事务描述（包含所有变更）
+     * @param transactionId 事务ID
+     * @param language 语言
+     * @returns 事务描述对象
+     */
     getTransactionDescription(transactionId_1) {
         return __awaiter(this, arguments, void 0, function* (transactionId, language = 'zh') {
+            // 获取事务信息
             const transaction = yield this.transactionRepository.findOne({
                 where: { id: transactionId },
             });
             if (!transaction) {
                 throw new Error(`Transaction ${transactionId} not found`);
             }
+            // 获取事务的审计日志
             const auditLogs = yield this.auditLogRepository.find({
                 where: { requestId: transactionId },
                 order: { createdAt: 'ASC' },
             });
+            // 获取事务的手动操作记录
             const manualOperations = yield this.manualOperationRepository.find({
                 where: { transactionId },
                 order: { createdAt: 'ASC' },
             });
+            // 生成操作名称和描述
             let operationName;
             let description;
             if (transaction.operationTemplateKey) {
@@ -90,6 +124,7 @@ let OperationDescriptionService = class OperationDescriptionService {
                 description = yield this.generateDescription(transaction.operationTemplateKey, transaction.descriptionParams || {}, language);
             }
             else {
+                // 如果没有事务级别的模板，使用第一个变更的模板
                 const firstLog = auditLogs[0];
                 if (firstLog && firstLog.operationTemplateKey) {
                     operationName = yield this.generateOperationName(firstLog.operationTemplateKey, language);
@@ -100,7 +135,9 @@ let OperationDescriptionService = class OperationDescriptionService {
                     description = transaction.description || 'Unknown operation';
                 }
             }
+            // 生成变更详情
             const changes = [];
+            // 添加实体变更
             for (const log of auditLogs) {
                 const changeDescription = log.operationTemplateKey
                     ? yield this.generateDescription(log.operationTemplateKey, log.descriptionParams || {}, language)
@@ -117,6 +154,7 @@ let OperationDescriptionService = class OperationDescriptionService {
                     createdAt: log.createdAt,
                 });
             }
+            // 添加手动操作
             for (const manualOp of manualOperations) {
                 const opName = yield this.generateOperationName(manualOp.operationTemplateKey, language);
                 const opDescription = yield this.generateDescription(manualOp.operationTemplateKey, manualOp.descriptionParams, language);
@@ -127,6 +165,7 @@ let OperationDescriptionService = class OperationDescriptionService {
                     createdAt: manualOp.createdAt,
                 });
             }
+            // 按时间排序
             changes.sort((a, b) => new Date(a.createdAt).getTime() - new Date(b.createdAt).getTime());
             return {
                 operationName,
@@ -135,6 +174,12 @@ let OperationDescriptionService = class OperationDescriptionService {
             };
         });
     }
+    /**
+     * 批量获取事务描述
+     * @param transactionIds 事务ID列表
+     * @param language 语言
+     * @returns 事务描述映射
+     */
     batchGetTransactionDescriptions(transactionIds_1) {
         return __awaiter(this, arguments, void 0, function* (transactionIds, language = 'zh') {
             const results = {};
@@ -143,16 +188,24 @@ let OperationDescriptionService = class OperationDescriptionService {
                     results[transactionId] = yield this.getTransactionDescription(transactionId, language);
                 }
                 catch (error) {
+                    // 忽略错误，继续处理其他事务
                     console.error(`Failed to get description for transaction ${transactionId}:`, error);
                 }
             }
             return results;
         });
     }
+    /**
+     * 填充模板
+     * @param template 模板字符串
+     * @param params 参数
+     * @returns 填充后的字符串
+     */
     fillTemplate(template, params) {
         if (!template)
             return '';
         let result = template;
+        // 替换参数 {key} -> value
         for (const [key, value] of Object.entries(params || {})) {
             const placeholder = `{${key}}`;
             if (result.includes(placeholder)) {
@@ -161,6 +214,12 @@ let OperationDescriptionService = class OperationDescriptionService {
         }
         return result;
     }
+    /**
+     * 格式化显示值
+     * @param value 原始值
+     * @param displayValue 显示值
+     * @returns 格式化后的值
+     */
     formatDisplayValue(value, displayValue) {
         if (displayValue !== undefined) {
             return displayValue;
@@ -170,23 +229,38 @@ let OperationDescriptionService = class OperationDescriptionService {
         }
         return String(value);
     }
+    /**
+     * 获取操作模板（带缓存）
+     * @param templateKey 模板键
+     * @returns 操作模板
+     */
     getOperationTemplate(templateKey) {
         return __awaiter(this, void 0, void 0, function* () {
+            // 检查缓存
             if (this.templateCache.has(templateKey)) {
                 return this.templateCache.get(templateKey);
             }
+            // 从数据库查询
             const template = yield this.templateRepository.findOne({
                 where: { key: templateKey },
             });
             if (template) {
+                // 缓存模板
                 this.templateCache.set(templateKey, template);
             }
             return template;
         });
     }
+    /**
+     * 清除模板缓存
+     */
     clearTemplateCache() {
         this.templateCache.clear();
     }
+    /**
+     * 预加载模板到缓存
+     * @param templateKeys 模板键列表
+     */
     preloadTemplates(templateKeys) {
         return __awaiter(this, void 0, void 0, function* () {
             const templates = yield this.templateRepository

package/audit/services/transaction-audit.service.d.ts

@@ -4,19 +4,49 @@ import { AuditOperation } from '../enums';
 import { AuditContextService } from './audit-context.service';
 import { EntityAuditService } from './entity-audit.service';
 import { MultiDatabaseService } from './multi-database.service';
+/**
+ * 事务审计服务
+ */
 export declare class TransactionAuditService {
     private readonly transactionRepository;
     private readonly contextService;
     private readonly auditService;
     private readonly multiDbService;
     constructor(transactionRepository: Repository<EntityTransactionEntity>, contextService: AuditContextService, auditService: EntityAuditService, multiDbService: MultiDatabaseService);
+    /**
+     * 开始事务
+     */
     beginTransaction(description: string): Promise<string>;
+    /**
+     * 提交事务
+     */
     commitTransaction(transactionId: string): Promise<void>;
+    /**
+     * 回滚事务（支持多数据库）
+     */
     rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * 添加实体到事务
+     */
     addEntityToTransaction(transactionId: string, entityType: string, entityId: string, operation: AuditOperation): Promise<void>;
+    /**
+     * 执行回滚（支持多数据库）
+     */
     private performRollback;
+    /**
+     * 按数据库连接分组实体
+     */
     private groupEntitiesByConnection;
+    /**
+     * 在指定连接中回滚实体
+     */
     private rollbackEntitiesInConnection;
+    /**
+     * 回滚单个实体
+     */
     private rollbackSingleEntity;
+    /**
+     * 获取最新的审计日志
+     */
     private getLatestAuditLog;
 }