@nest-omni/core 4.1.3-2 → 4.1.3-22

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

@@ -21,22 +21,38 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuditContextService = void 0;
 const common_1 = require("@nestjs/common");
 const nestjs_cls_1 = require("nestjs-cls");
+const crypto_1 = require("crypto");
+/**
+ * 审计上下文服务
+ */
 let AuditContextService = class AuditContextService {
     constructor(cls) {
         this.cls = cls;
     }
+    /**
+     * 获取当前上下文
+     */
     getCurrentContext() {
         return __awaiter(this, void 0, void 0, function* () {
             return this.cls.get('auditContext') || this.getDefaultContext();
         });
     }
+    /**
+     * 设置上下文
+     */
     setContext(context) {
         const currentContext = this.cls.get('auditContext') || this.getDefaultContext();
         this.cls.set('auditContext', Object.assign(Object.assign({}, currentContext), context));
     }
+    /**
+     * 清除上下文
+     */
     clearContext() {
         this.cls.set('auditContext', undefined);
     }
+    /**
+     * 获取默认上下文
+     */
     getDefaultContext() {
         return {
             userId: 'system',
@@ -47,6 +63,175 @@ let AuditContextService = class AuditContextService {
             timestamp: new Date(),
         };
     }
+    // ========== 审计动作上下文管理 ==========
+    /**
+     * 获取当前审计动作上下文
+     */
+    getCurrentActionContext() {
+        return this.cls.get('auditActionContext') || null;
+    }
+    /**
+     * 设置审计动作上下文
+     */
+    setActionContext(context) {
+        this.cls.set('auditActionContext', context);
+    }
+    /**
+     * 清除审计动作上下文
+     */
+    clearActionContext() {
+        this.cls.set('auditActionContext', null);
+    }
+    /**
+     * 记录实体变化到当前动作（简单版本）
+     */
+    recordEntityChangeInAction(entityType, entityId, operation) {
+        const actionContext = this.getCurrentActionContext();
+        if (actionContext) {
+            actionContext.entityChanges.push({
+                entityType,
+                entityId,
+                operation,
+                sequence: actionContext.entityChanges.length + 1,
+            });
+        }
+    }
+    /**
+     * 记录详细的实体变化
+     */
+    recordDetailedEntityChange(entityType, entityId, operation, oldValue, newValue, changedFields, metadata) {
+        const actionContext = this.getCurrentActionContext();
+        if (actionContext) {
+            const detail = {
+                entityType,
+                entityId,
+                operation,
+                oldValue,
+                newValue,
+                changedFields,
+                sequence: actionContext.detailedChanges.length + 1,
+                metadata,
+            };
+            actionContext.detailedChanges.push(detail);
+        }
+    }
+    /**
+     * 获取当前动作内的序号
+     */
+    getSequenceInAction() {
+        const actionContext = this.getCurrentActionContext();
+        return actionContext ? actionContext.entityChanges.length + 1 : 0;
+    }
+    /**
+     * 生成审计动作ID
+     */
+    generateActionId() {
+        return (0, crypto_1.randomBytes)(16).toString('hex');
+    }
+    /**
+     * 构建审计参数上下文
+     */
+    buildParamsContext() {
+        const actionContext = this.getCurrentActionContext();
+        if (!actionContext) {
+            return null;
+        }
+        const context = {
+            req: actionContext.req,
+            result: actionContext.result,
+            error: actionContext.error,
+            entityChanges: actionContext.detailedChanges,
+            // 查找单个实体
+            findEntity(entityType, operation) {
+                return context.entityChanges.find((change) => change.entityType === entityType &&
+                    (operation === undefined || change.operation === operation)) || null;
+            },
+            // 查找多个实体
+            findEntities(entityType, operation) {
+                return context.entityChanges.filter((change) => change.entityType === entityType &&
+                    (operation === undefined || change.operation === operation));
+            },
+            // 统计实体数量
+            countEntities(entityType, operation) {
+                return context.findEntities(entityType, operation).length;
+            },
+            // 路径提取
+            extractParams(mapping) {
+                const result = {};
+                for (const [key, value] of Object.entries(mapping)) {
+                    if (typeof value === 'string') {
+                        // 简单路径: 'Order.CREATE.orderSn'
+                        result[key] = this.extractByPath(value);
+                    }
+                    else if (typeof value === 'object' && value.type) {
+                        // 复杂提取: { type: 'join', path: 'OrderItem.CREATE', field: 'name' }
+                        result[key] = this.extractByConfig(value);
+                    }
+                }
+                return result;
+            },
+            extractByPath(path) {
+                const parts = path.split('.');
+                if (parts.length < 2)
+                    return undefined;
+                const [entityType, operationStr, ...fieldParts] = parts;
+                const operation = operationStr;
+                const entity = context.findEntity(entityType, operation);
+                if (!entity)
+                    return undefined;
+                // 支持嵌套字段访问
+                let value = entity.newValue;
+                for (const field of fieldParts) {
+                    if (value && typeof value === 'object') {
+                        value = value[field];
+                    }
+                    else {
+                        return undefined;
+                    }
+                }
+                return value;
+            },
+            extractByConfig(config) {
+                const { type, path, field, separator = ', ' } = config;
+                const parts = path.split('.');
+                const [entityType, operationStr] = parts;
+                const operation = operationStr;
+                const entities = context.findEntities(entityType, operation);
+                switch (type) {
+                    case 'count':
+                        return entities.length;
+                    case 'join': {
+                        const values = entities.map((e) => {
+                            const fieldParts = field.split('.');
+                            let value = e.newValue;
+                            for (const part of fieldParts) {
+                                if (part === 'metadata') {
+                                    value = e.metadata;
+                                }
+                                else if (value && typeof value === 'object') {
+                                    value = value[part];
+                                }
+                                else {
+                                    return undefined;
+                                }
+                            }
+                            return value;
+                        }).filter(Boolean);
+                        return values.join(separator);
+                    }
+                    case 'sum': {
+                        return entities.reduce((sum, e) => {
+                            const value = e.newValue[field];
+                            return sum + (typeof value === 'number' ? value : 0);
+                        }, 0);
+                    }
+                    default:
+                        return undefined;
+                }
+            },
+        };
+        return context;
+    }
 };
 exports.AuditContextService = AuditContextService;
 exports.AuditContextService = AuditContextService = __decorate([

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

@@ -1,5 +1,8 @@
 import { IAuditStrategy, IFieldFilter, AuditConfig } from '../interfaces';
 import { AuditOperation, RecordStrategy, MaskingStrategy } from '../enums';
+/**
+ * 默认字段过滤器
+ */
 export declare class DefaultFieldFilter implements IFieldFilter {
     private readonly includeFields?;
     private readonly excludeFields?;
@@ -10,6 +13,9 @@ export declare class DefaultFieldFilter implements IFieldFilter {
     getMaskingStrategy(fieldName: string, path: string[]): MaskingStrategy;
     private matchPattern;
 }
+/**
+ * 默认审计策略
+ */
 export declare class DefaultAuditStrategy implements IAuditStrategy {
     private readonly config?;
     constructor(config?: AuditConfig);

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

@@ -15,6 +15,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DefaultAuditStrategy = exports.DefaultFieldFilter = void 0;
 const common_1 = require("@nestjs/common");
 const enums_1 = require("../enums");
+/**
+ * 默认字段过滤器
+ */
 class DefaultFieldFilter {
     constructor(includeFields, excludeFields, maskFields) {
         this.includeFields = includeFields;
@@ -23,9 +26,11 @@ class DefaultFieldFilter {
     }
     shouldIncludeField(fieldName, path) {
         const fullPath = [...path, fieldName].join('.');
+        // 如果指定了包含字段，则只记录这些字段
         if (this.includeFields && this.includeFields.length > 0) {
             return this.includeFields.some((pattern) => this.matchPattern(fullPath, pattern));
         }
+        // 如果指定了排除字段，则排除这些字段
         if (this.excludeFields && this.excludeFields.length > 0) {
             return !this.excludeFields.some((pattern) => this.matchPattern(fullPath, pattern));
         }
@@ -40,6 +45,7 @@ class DefaultFieldFilter {
         return enums_1.MaskingStrategy.MASK;
     }
     matchPattern(path, pattern) {
+        // 支持通配符匹配，如 user.address.*
         if (pattern.endsWith('*')) {
             return path.startsWith(pattern.slice(0, -1));
         }
@@ -47,18 +53,24 @@ class DefaultFieldFilter {
     }
 }
 exports.DefaultFieldFilter = DefaultFieldFilter;
+/**
+ * 默认审计策略
+ */
 let DefaultAuditStrategy = class DefaultAuditStrategy {
     constructor(config) {
         this.config = config;
     }
     shouldRecord(entityType, operation) {
         var _a, _b, _c, _d, _e;
+        // 检查全局配置
         const globalEnabled = ((_a = this.config) === null || _a === void 0 ? void 0 : _a.enabled) !== false;
         if (!globalEnabled)
             return false;
+        // 检查实体级别配置
         const entityConfig = (_c = (_b = this.config) === null || _b === void 0 ? void 0 : _b.entities) === null || _c === void 0 ? void 0 : _c[entityType];
         if (entityConfig && entityConfig.enabled === false)
             return false;
+        // 检查操作级别配置
         const operationConfig = (_e = (_d = this.config) === null || _d === void 0 ? void 0 : _d.operations) === null || _e === void 0 ? void 0 : _e[operation];
         if (operationConfig && operationConfig.enabled === false)
             return false;
@@ -66,6 +78,7 @@ let DefaultAuditStrategy = class DefaultAuditStrategy {
     }
     getRecordStrategy(entityType, operation) {
         var _a, _b, _c, _d, _e, _f, _g;
+        // 优先级: 实体级别 > 操作级别 > 全局默认
         const entityStrategy = (_c = (_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.entities) === null || _b === void 0 ? void 0 : _b[entityType]) === null || _c === void 0 ? void 0 : _c.strategy;
         if (entityStrategy)
             return entityStrategy;

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

@@ -1,37 +1,305 @@
 import { Repository, EntityManager } from 'typeorm';
-import { EntityAuditLogEntity, EntityTransactionEntity } from '../entities';
+import { EntityAuditLogEntity, EntityTransactionEntity, ManualOperationLogEntity, AuditActionSummaryEntity } from '../entities';
 import { AuditOperation } from '../enums';
-import { AuditConfig, IAuditStrategy, EntityDifference, RestoreOptions, RestoreResult, PreCheckResult } from '../interfaces';
+import { AuditConfig, IAuditStrategy, EntityDifference, RestoreOptions, RestoreResult, PreCheckResult, ManualOperationData, ChangeDetail } from '../interfaces';
 import { AuditContextService } from './audit-context.service';
 import { MultiDatabaseService } from './multi-database.service';
+import { OperationDescriptionService } from './operation-description.service';
 import { PageDto } from '../../common/dto';
 import { AuditLogQueryDto } from '../dto';
+/**
+ * 审计配置常量
+ */
+export declare const AUDIT_CONSTANTS: {
+    /** 深度比较的最大深度限制 */
+    readonly MAX_DIFF_DEPTH: 5;
+    /** 深度比较的最大键数量限制 */
+    readonly MAX_KEYS: 100;
+    /** 描述的最大长度 */
+    readonly MAX_DESCRIPTION_LENGTH: 1000;
+    /** 哈希截断长度 */
+    readonly HASH_TRUNCATE_LENGTH: 64;
+    /** 部分掩码显示的字符数 */
+    readonly PARTIAL_MASK_CHARS: 2;
+};
+/**
+ * 注册实体类到注册表
+ */
+export declare function registerEntityClass(entityType: string, entityClass: any): void;
+/**
+ * 获取实体类
+ */
+export declare function getEntityClass(entityType: string): any | undefined;
+/**
+ * 实体审计服务
+ */
 export declare class EntityAuditService {
     private readonly auditLogRepository;
     private readonly transactionRepository;
+    private readonly manualOperationRepository;
     private readonly entityManager;
     private readonly contextService;
     private readonly multiDbService;
     private readonly auditStrategy;
     private readonly config?;
+    private readonly actionSummaryRepository?;
+    private readonly descriptionService?;
     private readonly auditConnectionName;
-    constructor(auditLogRepository: Repository<EntityAuditLogEntity>, transactionRepository: Repository<EntityTransactionEntity>, entityManager: EntityManager, contextService: AuditContextService, multiDbService: MultiDatabaseService, auditStrategy?: IAuditStrategy, config?: AuditConfig, auditConnectionName?: string);
+    constructor(auditLogRepository: Repository<EntityAuditLogEntity>, transactionRepository: Repository<EntityTransactionEntity>, manualOperationRepository: Repository<ManualOperationLogEntity>, entityManager: EntityManager, contextService: AuditContextService, multiDbService: MultiDatabaseService, auditStrategy?: IAuditStrategy, config?: AuditConfig, auditConnectionName?: string, actionSummaryRepository?: Repository<AuditActionSummaryEntity>, descriptionService?: OperationDescriptionService);
+    /**
+     * 记录实体变更
+     */
     logEntityChange(entityType: string, entityId: string, operation: AuditOperation, oldValue: Record<string, any>, newValue: Record<string, any>, metadata?: Record<string, any>): Promise<EntityAuditLogEntity | null>;
+    /**
+     * 查询审计日志
+     */
     getAuditLogs(query: AuditLogQueryDto): Promise<PageDto<EntityAuditLogEntity>>;
+    /**
+     * 比较实体差异
+     */
     compareEntities(entityType: string, entityId: string, fromLogId?: string, toLogId?: string): Promise<EntityDifference>;
+    /**
+     * 预检查恢复操作
+     */
     preCheckRestore(entityType: string, entityId: string, auditLogId: string): Promise<PreCheckResult>;
+    /**
+     * 恢复实体
+     */
     restoreEntity(entityType: string, entityId: string, auditLogId: string, options?: RestoreOptions): Promise<RestoreResult>;
+    /**
+     * 计算变更字段（支持嵌套路径）
+     */
     private calculateChangedFields;
-    private calculateChangedFieldPaths;
+    /**
+     * 生成字段级别的变更详情（前后对比，支持嵌套路径和装饰器值映射）
+     */
+    private generateChangeDetails;
+    /**
+     * 深度比较对象
+     */
     private deepEqual;
+    /**
+     * 深度差异比较
+     */
     private deepDiff;
+    /**
+     * 比较快照数据
+     */
     private compareSnapshotData;
+    /**
+     * 过滤和脱敏字段
+     */
     private filterAndMaskFields;
+    /**
+     * 应用脱敏策略
+     */
     private applyMasking;
+    /**
+     * 哈希值
+     */
     private hashValue;
+    /**
+     * 掩码值
+     */
     private maskValue;
+    /**
+     * 部分掩码值
+     */
     private partialMaskValue;
-    private generateHashChain;
+    /**
+     * 生成描述（支持多语言）
+     * @param operation 操作类型
+     * @param entityType 实体类型
+     * @param entityId 实体ID
+     * @param changedFields 变更字段列表
+     * @param language 语言（默认中文）
+     * @param entityClass 实体类（可选，用于获取实体标签）
+     */
+    /**
+     * 使用模板生成描述（优先使用 OperationDescriptionService）
+     */
+    private generateDescriptionFromTemplate;
     private generateDescription;
+    /**
+     * 检测冲突
+     */
     private detectConflicts;
+    /**
+     * 增强的记录实体变更（支持模板和结构化变更详情）
+     * @param data 审计数据
+     * @returns 审计日志实体
+     */
+    logEntityChangeWithTemplate(data: {
+        entityType: string;
+        entityId: string;
+        operation: AuditOperation;
+        oldValue?: Record<string, any>;
+        newValue?: Record<string, any>;
+        changedFields?: string[];
+        operationTemplateKey?: string;
+        descriptionParams?: Record<string, any>;
+        changeDetails?: ChangeDetail[];
+        metadata?: Record<string, any>;
+    }): Promise<EntityAuditLogEntity | null>;
+    /**
+     * 记录手动操作
+     * @param data 手动操作数据
+     * @returns 手动操作日志实体
+     */
+    logManualOperation(data: ManualOperationData): Promise<ManualOperationLogEntity>;
+    /**
+     * 在事务中执行操作
+     * @param fn 执行函数
+     * @param options 事务选项
+     * @returns 执���结果
+     */
+    withTransaction<T>(fn: (transactionId: string) => Promise<T>, options?: {
+        userId?: string;
+        username?: string;
+        requestIp?: string;
+        operationTemplateKey?: string;
+        descriptionParams?: Record<string, any>;
+        metadata?: Record<string, any>;
+    }): Promise<T>;
+    /**
+     * 获取当前事务ID
+     * @returns 当前事务ID或null
+     */
+    getCurrentTransactionId(): Promise<string | null>;
+    /**
+     * 设置当前事务ID
+     * @param transactionId 事务ID
+     */
+    setCurrentTransactionId(transactionId: string | null): Promise<void>;
+    /**
+     * 开始事务
+     * @param userId 用户ID
+     * @param userName 用户名
+     * @param ip IP地址
+     * @param operationTemplateKey 操作模板键
+     * @param descriptionParams 描述参数
+     * @returns 事务ID
+     */
+    beginTransaction(userId?: string, userName?: string, ip?: string, operationTemplateKey?: string, descriptionParams?: Record<string, any>): Promise<string>;
+    /**
+     * 提交事务
+     * @param transactionId 事务ID
+     */
+    commitTransaction(transactionId: string): Promise<void>;
+    /**
+     * 回滚事务
+     * @param transactionId 事务ID
+     */
+    rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * 查询审计动作汇总记录
+     */
+    getAuditActions(options: {
+        userId?: string;
+        username?: string;
+        actionName?: string;
+        success?: boolean;
+        startTime?: Date;
+        endTime?: Date;
+        page?: number;
+        limit?: number;
+        keyword?: string;
+    }): Promise<PageDto<AuditActionSummaryEntity>>;
+    /**
+     * 查询单个审计动作的详细信息（包含关联的实体变更）
+     * @param actionId 动作ID
+     * @param language 语言代码 (zh/en/ja)，默认 zh
+     */
+    getAuditActionDetail(actionId: string, language?: string): Promise<{
+        summary: {
+            id: string;
+            actionName: string;
+            operationTemplateKey: string;
+            description: string;
+            descriptionParams: Record<string, any>;
+            success: boolean;
+            errorMessage: string;
+            duration: number;
+            userId: string;
+            username: string;
+            requestId: string;
+            requestIp: string;
+            userAgent: string;
+            entityChangesCount: number;
+            entityTypes: string[];
+            operationStats: Record<string, number>;
+            createdAt: Date;
+            metadata: Record<string, any>;
+        };
+        entityChanges: EntityAuditLogEntity[];
+        detailedChanges: {
+            id: string;
+            entityType: string;
+            entityId: string;
+            operation: AuditOperation;
+            operationLabel: string;
+            description: string;
+            sequenceInAction: number;
+            createdAt: Date;
+            oldValue: Record<string, any>;
+            newValue: Record<string, any>;
+            changeDetails: ChangeDetail[];
+            changedFieldsCount: number;
+            changedFields: string[];
+        }[];
+        statistics: {
+            totalChanges: number;
+            totalFieldChanges: number;
+            byEntityType: Record<string, number>;
+            byOperation: Record<string, number>;
+            operationSequence: {
+                sequence: number;
+                entityType: string;
+                operation: AuditOperation;
+            }[];
+        };
+    }>;
+    /**
+     * 生成本地化的描述文本
+     */
+    private generateLocalizedDescription;
+    /**
+     * 替换模板中的占位符
+     * @param template 模板字符串，如 "创建了产品 {name}，价格 ¥{price}"
+     * @param params 参数对象，如 { name: "iPhone", price: 999 }
+     * @returns 替换后的字符串
+     */
+    private replaceTemplatePlaceholders;
+    /**
+     * 获取嵌套对象的值
+     * @param obj 对象
+     * @param path 路径，如 "user.name" 或 "user.profile.age"
+     * @returns 值或 undefined
+     */
+    private getNestedValue;
+    /**
+     * 本地化 changeDetails（根据语言转换 fieldLabel 和 displayValue）
+     */
+    private localizeChangeDetails;
+    /**
+     * 获取操作标签（支持多语言）
+     */
+    private getOperationLabel;
+    /**
+     * 分析字段变化（支持多语言）
+     * @param oldValue 旧值
+     * @param newValue 新值
+     * @param operation 操作类型
+     * @param entityClass 实体类（可选，用于获取字段和值的多语言标签）
+     * @param language 语言（默认中文）
+     */
+    private analyzeFieldChanges;
+    /**
+     * 格式化显示值
+     */
+    private formatDisplayValue;
+    /**
+     * 按字段分组统计
+     */
+    private groupBy;
 }