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

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

@@ -1,37 +1,264 @@
 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, RollbackAction } from '../interfaces';
 import { AuditContextService } from './audit-context.service';
 import { MultiDatabaseService } from './multi-database.service';
 import { PageDto } from '../../common/dto';
 import { AuditLogQueryDto } from '../dto';
+/**
+ * 实体审计服务
+ */
 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 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>);
+    /**
+     * 记录实体变更
+     */
     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 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 实体类（可选，用于获取实体标签）
+     */
     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[];
+        rollbackActions?: RollbackAction[];
+        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;
+    }): Promise<PageDto<AuditActionSummaryEntity>>;
+    /**
+     * 查询单个审计动作的详细信息（包含关联的实体变更）
+     */
+    getAuditActionDetail(actionId: 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>;
+            fieldChanges: {
+                field: string;
+                fieldLabel: string;
+                oldValue: any;
+                newValue: any;
+                changeType: "added" | "removed" | "modified" | "unchanged";
+                displayOldValue?: string;
+                displayNewValue?: string;
+            }[];
+            changedFieldsCount: number;
+            changedFields: string[];
+        }[];
+        statistics: {
+            totalChanges: number;
+            totalFieldChanges: number;
+            byEntityType: Record<string, number>;
+            byOperation: Record<string, number>;
+            operationSequence: {
+                sequence: number;
+                entityType: string;
+                operation: AuditOperation;
+            }[];
+        };
+    }>;
+    /**
+     * 分析字段变化（支持多语言）
+     * @param oldValue 旧值
+     * @param newValue 新值
+     * @param operation 操作类型
+     * @param entityClass 实体类（可选，用于获取字段和值的多语言标签）
+     * @param language 语言（默认中文）
+     */
+    private analyzeFieldChanges;
+    /**
+     * 格式化显示值
+     */
+    private formatDisplayValue;
+    /**
+     * 获取操作标签
+     */
+    private getOperationLabel;
+    /**
+     * 按字段分组统计
+     */
+    private groupBy;
 }