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

package/audit/services/entity-audit.service.js

@@ -32,6 +32,9 @@ const audit_context_service_1 = require("./audit-context.service");
 const audit_strategy_service_1 = require("./audit-strategy.service");
 const multi_database_service_1 = require("./multi-database.service");
 const dto_1 = require("../../common/dto");
+/**
+ * 实体审计服务
+ */
 let EntityAuditService = class EntityAuditService {
     constructor(auditLogRepository, transactionRepository, entityManager, contextService, multiDbService, auditStrategy = new audit_strategy_service_1.DefaultAuditStrategy(), config, auditConnectionName) {
         this.auditLogRepository = auditLogRepository;
@@ -43,22 +46,32 @@ let EntityAuditService = class EntityAuditService {
         this.config = config;
         this.auditConnectionName = auditConnectionName || 'default';
     }
+    /**
+     * 记录实体变更
+     */
     logEntityChange(entityType_1, entityId_1, operation_1, oldValue_1, newValue_1) {
         return __awaiter(this, arguments, void 0, function* (entityType, entityId, operation, oldValue, newValue, metadata = {}) {
             var _a, _b;
+            // 检查是否应该记录
             if (!this.auditStrategy.shouldRecord(entityType, operation)) {
                 return null;
             }
+            // 获取记录策略
             const recordStrategy = this.auditStrategy.getRecordStrategy(entityType, operation);
             if (recordStrategy === enums_1.RecordStrategy.DISABLED) {
                 return null;
             }
+            // 获取字段过滤器
             const fieldFilter = this.auditStrategy.getFieldFilter(entityType);
+            // 过滤和脱敏字段
             const filteredOldValue = this.filterAndMaskFields(oldValue, fieldFilter);
             const filteredNewValue = this.filterAndMaskFields(newValue, fieldFilter);
+            // 计算变更字段
             const changedFields = this.calculateChangedFields(filteredOldValue, filteredNewValue);
             const changedFieldPaths = this.calculateChangedFieldPaths(filteredOldValue, filteredNewValue);
+            // 获取上下文信息
             const context = yield this.contextService.getCurrentContext();
+            // 创建审计日志
             const auditLog = this.auditLogRepository.create({
                 entityType,
                 entityId,
@@ -77,17 +90,23 @@ let EntityAuditService = class EntityAuditService {
                     ? yield this.generateHashChain(entityType, entityId, filteredNewValue)
                     : undefined,
             });
+            // 保存变更日志
             const savedLog = yield this.auditLogRepository.save(auditLog);
             return savedLog;
         });
     }
+    /**
+     * 查询审计日志
+     */
     getAuditLogs(query) {
         return __awaiter(this, void 0, void 0, function* () {
+            // 应用默认值
             const page = query.page || 1;
             const limit = query.limit || 20;
             const sortBy = query.sortBy || 'createdAt';
             const sortOrder = query.sortOrder || 'DESC';
             const queryBuilder = this.auditLogRepository.createQueryBuilder('log');
+            // 应用过滤条件
             if (query.entityType) {
                 queryBuilder.andWhere('log.entityType = :entityType', { entityType: query.entityType });
             }
@@ -111,7 +130,9 @@ let EntityAuditService = class EntityAuditService {
                     search: `%${query.search}%`,
                 });
             }
+            // 应用排序
             queryBuilder.orderBy(`log.${sortBy}`, sortOrder);
+            // 应用分页
             const skip = (page - 1) * limit;
             queryBuilder.skip(skip).take(limit);
             const [data, total] = yield queryBuilder.getManyAndCount();
@@ -124,6 +145,9 @@ let EntityAuditService = class EntityAuditService {
             return new dto_1.PageDto(data, pageMetaDto);
         });
     }
+    /**
+     * 比较实体差异
+     */
     compareEntities(entityType, entityId, fromLogId, toLogId) {
         return __awaiter(this, void 0, void 0, function* () {
             let fromData = {};
@@ -137,6 +161,7 @@ let EntityAuditService = class EntityAuditService {
                 toData = (toLog === null || toLog === void 0 ? void 0 : toLog.newValue) || {};
             }
             else {
+                // 获取最新的日志
                 const latestLog = yield this.auditLogRepository.findOne({
                     where: { entityType, entityId },
                     order: { createdAt: 'DESC' },
@@ -146,6 +171,9 @@ let EntityAuditService = class EntityAuditService {
             return this.compareSnapshotData(fromData, toData);
         });
     }
+    /**
+     * 预检查恢复操作
+     */
     preCheckRestore(entityType, entityId, auditLogId) {
         return __awaiter(this, void 0, void 0, function* () {
             const auditLog = yield this.auditLogRepository.findOne({ where: { id: auditLogId } });
@@ -163,6 +191,7 @@ let EntityAuditService = class EntityAuditService {
                     warnings: [],
                 };
             }
+            // 获取当前实体状态
             const repository = this.entityManager.getRepository(entityType);
             const currentEntity = yield repository.findOne({ where: { id: entityId } });
             if (!currentEntity) {
@@ -179,6 +208,7 @@ let EntityAuditService = class EntityAuditService {
                     warnings: [],
                 };
             }
+            // 检查冲突
             const conflicts = this.detectConflicts(currentEntity, auditLog.oldValue);
             return {
                 canRestore: conflicts.length === 0,
@@ -187,6 +217,9 @@ let EntityAuditService = class EntityAuditService {
             };
         });
     }
+    /**
+     * 恢复实体
+     */
     restoreEntity(entityType_1, entityId_1, auditLogId_1) {
         return __awaiter(this, arguments, void 0, function* (entityType, entityId, auditLogId, options = {}) {
             const auditLog = yield this.auditLogRepository.findOne({ where: { id: auditLogId } });
@@ -196,6 +229,7 @@ let EntityAuditService = class EntityAuditService {
                     message: '审计日志不存在',
                 };
             }
+            // 预检查
             const preCheckResult = yield this.preCheckRestore(entityType, entityId, auditLogId);
             if (!preCheckResult.canRestore && !options.force) {
                 return {
@@ -205,10 +239,13 @@ let EntityAuditService = class EntityAuditService {
                 };
             }
             try {
+                // 获取指定的数据库连接
                 const connectionName = options.connectionName || 'default';
                 const dataSource = yield this.multiDbService.getDataSource(connectionName);
                 const repository = dataSource.getRepository(entityType);
+                // 恢复实体
                 const restoreData = Object.assign({}, auditLog.oldValue);
+                // 应用字段过滤
                 if (options.includeFields && options.includeFields.length > 0) {
                     Object.keys(restoreData).forEach((key) => {
                         if (!options.includeFields.includes(key)) {
@@ -221,8 +258,10 @@ let EntityAuditService = class EntityAuditService {
                         delete restoreData[field];
                     });
                 }
+                // 执行恢复
                 if (!options.dryRun) {
                     yield repository.update({ id: entityId }, restoreData);
+                    // 记录恢复操作
                     yield this.logEntityChange(entityType, entityId, enums_1.AuditOperation.RESTORE, auditLog.newValue, restoreData);
                 }
                 return {
@@ -239,9 +278,14 @@ let EntityAuditService = class EntityAuditService {
             }
         });
     }
+    /**
+     * 计算变更字段
+     */
     calculateChangedFields(oldValue, newValue) {
         const changedFields = [];
+        // 获取所有字段
         const allFields = new Set([...Object.keys(oldValue || {}), ...Object.keys(newValue || {})]);
+        // 比较每个字段
         for (const field of allFields) {
             const oldVal = oldValue === null || oldValue === void 0 ? void 0 : oldValue[field];
             const newVal = newValue === null || newValue === void 0 ? void 0 : newValue[field];
@@ -251,14 +295,22 @@ let EntityAuditService = class EntityAuditService {
         }
         return changedFields;
     }
+    /**
+     * 计算变更字段路径
+     */
     calculateChangedFieldPaths(oldValue, newValue) {
         const changedPaths = [];
+        // 使用深度比较获取变更路径
         const diff = this.deepDiff(oldValue, newValue);
+        // 提取路径
         for (const change of diff) {
             changedPaths.push(change.path.join('.'));
         }
         return changedPaths;
     }
+    /**
+     * 深度比较对象
+     */
     deepEqual(a, b) {
         if (a === b)
             return true;
@@ -282,13 +334,18 @@ let EntityAuditService = class EntityAuditService {
         }
         return true;
     }
+    /**
+     * 深度差异比较
+     */
     deepDiff(oldObj, newObj, path = []) {
         var _a;
         const changes = [];
         const maxDepth = ((_a = this.config) === null || _a === void 0 ? void 0 : _a.maxDiffDepth) || 5;
+        // 防止过深
         if (path.length > maxDepth) {
             return changes;
         }
+        // 处理基本类型
         if (typeof oldObj !== 'object' || oldObj === null) {
             if (oldObj !== newObj) {
                 changes.push({
@@ -300,6 +357,7 @@ let EntityAuditService = class EntityAuditService {
             }
             return changes;
         }
+        // 处理数组
         if (Array.isArray(oldObj)) {
             if (!Array.isArray(newObj)) {
                 changes.push({
@@ -324,6 +382,7 @@ let EntityAuditService = class EntityAuditService {
             }
             return changes;
         }
+        // 处理对象
         const allKeys = new Set([...Object.keys(oldObj), ...Object.keys(newObj)]);
         for (const key of allKeys) {
             const oldVal = oldObj[key];
@@ -350,6 +409,9 @@ let EntityAuditService = class EntityAuditService {
         }
         return changes;
     }
+    /**
+     * 比较快照数据
+     */
     compareSnapshotData(fromData, toData) {
         const changes = this.deepDiff(fromData, toData);
         return {
@@ -361,6 +423,9 @@ let EntityAuditService = class EntityAuditService {
             },
         };
     }
+    /**
+     * 过滤和脱敏字段
+     */
     filterAndMaskFields(data, fieldFilter, path = []) {
         if (typeof data !== 'object' || data === null) {
             return data;
@@ -368,14 +433,17 @@ let EntityAuditService = class EntityAuditService {
         const result = {};
         for (const [key, value] of Object.entries(data)) {
             const currentPath = [...path, key];
+            // 检查是否应该包含此字段
             if (!fieldFilter.shouldIncludeField(key, currentPath)) {
                 continue;
             }
+            // 检查是否应该脱敏此字段
             if (fieldFilter.shouldMaskField(key, currentPath)) {
                 const maskingStrategy = fieldFilter.getMaskingStrategy(key, currentPath);
                 result[key] = this.applyMasking(value, maskingStrategy);
             }
             else if (typeof value === 'object' && value !== null) {
+                // 递归处理嵌套对象
                 result[key] = this.filterAndMaskFields(value, fieldFilter, currentPath);
             }
             else {
@@ -384,6 +452,9 @@ let EntityAuditService = class EntityAuditService {
         }
         return result;
     }
+    /**
+     * 应用脱敏策略
+     */
     applyMasking(value, strategy) {
         if (value == null)
             return value;
@@ -400,14 +471,23 @@ let EntityAuditService = class EntityAuditService {
                 return '***MASKED***';
         }
     }
+    /**
+     * 哈希值
+     */
     hashValue(value) {
         const strValue = String(value);
         return (0, crypto_1.createHash)('sha256').update(strValue).digest('hex');
     }
+    /**
+     * 掩码值
+     */
     maskValue(value) {
         const strValue = String(value);
         return '*'.repeat(strValue.length);
     }
+    /**
+     * 部分掩码值
+     */
     partialMaskValue(value) {
         const strValue = String(value);
         if (strValue.length <= 4) {
@@ -417,14 +497,19 @@ let EntityAuditService = class EntityAuditService {
             '*'.repeat(strValue.length - 4) +
             strValue.substring(strValue.length - 2));
     }
+    /**
+     * 生成哈希链
+     */
     generateHashChain(entityType, entityId, data) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b, _c;
+            // 获取上一个审计记录的哈希
             const lastLog = yield this.auditLogRepository.findOne({
                 where: { entityType, entityId },
                 order: { createdAt: 'DESC' },
             });
             const previousHash = ((_a = lastLog === null || lastLog === void 0 ? void 0 : lastLog.hashChain) === null || _a === void 0 ? void 0 : _a.currentHash) || '';
+            // 计算当前数据的哈希
             const currentData = JSON.stringify(data);
             const hashAlgorithm = ((_c = (_b = this.config) === null || _b === void 0 ? void 0 : _b.security) === null || _c === void 0 ? void 0 : _c.hashAlgorithm) || 'sha256';
             const currentHash = (0, crypto_1.createHash)(hashAlgorithm).update(currentData + previousHash).digest('hex');
@@ -435,6 +520,9 @@ let EntityAuditService = class EntityAuditService {
             };
         });
     }
+    /**
+     * 生成描述
+     */
     generateDescription(operation, entityType, entityId, changedFields) {
         const operationText = {
             [enums_1.AuditOperation.CREATE]: '创建',
@@ -448,6 +536,9 @@ let EntityAuditService = class EntityAuditService {
         }
         return `${text} ${entityType}(${entityId})`;
     }
+    /**
+     * 检测冲突
+     */
     detectConflicts(currentEntity, targetValue) {
         const conflicts = [];
         for (const [key, targetVal] of Object.entries(targetValue)) {

package/audit/services/manual-audit-log.service.d.ts

@@ -2,6 +2,11 @@ import { Repository, DataSource } from 'typeorm';
 import { ManualOperationLogEntity, EntityTransactionEntity } from '../entities';
 import { AuditContextService } from './audit-context.service';
 import { ManualLogOptions } from '../interfaces';
+/**
+ * 手动审计日志服务
+ *
+ * 提供全局静态方法，在任意地方手动记录操作日志
+ */
 export declare class ManualAuditLogService {
     private readonly manualLogRepository;
     private readonly transactionRepository;
@@ -9,15 +14,134 @@ export declare class ManualAuditLogService {
     private readonly dataSource;
     private static instance;
     constructor(manualLogRepository: Repository<ManualOperationLogEntity>, transactionRepository: Repository<EntityTransactionEntity>, contextService: AuditContextService, dataSource: DataSource);
+    /**
+     * 全局静态方法：记录操作日志
+     *
+     * @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: ManualLogOptions): Promise<ManualOperationLogEntity>;
+    /**
+     * 实例方法：记录操作日志
+     */
     logOperation(options: ManualLogOptions): Promise<ManualOperationLogEntity>;
+    /**
+     * 静态方法：带事务记录
+     *
+     * @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?: string, username?: string): Promise<string>;
+    /**
+     * 静态方法：提交事务
+     */
     static commitTransaction(transactionId: string): Promise<void>;
+    /**
+     * 静态方法：回滚事务
+     */
     static rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * 创建事务
+     */
     private createTransaction;
+    /**
+     * 更新事务状态
+     */
     private updateTransactionStatus;
+    /**
+     * 生成事务ID
+     */
     private generateTransactionId;
+    /**
+     * 批量记录操作日志
+     *
+     * @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: ManualLogOptions[], sharedTransactionId?: string): Promise<ManualOperationLogEntity[]>;
+    /**
+     * 查询操作日志
+     */
     static findLogs(options: {
         templateKey?: string;
         userId?: string;