@nest-omni/core 4.1.3-3 → 4.1.3-30

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

@@ -1,24 +1,51 @@
 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);
     /**
      * 记录实体变更
      */
@@ -40,13 +67,13 @@ export declare class EntityAuditService {
      */
     restoreEntity(entityType: string, entityId: string, auditLogId: string, options?: RestoreOptions): Promise<RestoreResult>;
     /**
-     * 计算变更字段
+     * 计算变更字段（支持嵌套路径）
      */
     private calculateChangedFields;
     /**
-     * 计算变更字段路径
+     * 生成字段级别的变更详情（前后对比，支持嵌套路径和装饰器值映射）
      */
-    private calculateChangedFieldPaths;
+    private generateChangeDetails;
     /**
      * 深度比较对象
      */
@@ -80,15 +107,199 @@ export declare class EntityAuditService {
      */
     private partialMaskValue;
     /**
-     * 生成哈希链
+     * 生成描述（支持多语言）
+     * @param operation 操作类型
+     * @param entityType 实体类型
+     * @param entityId 实体ID
+     * @param changedFields 变更字段列表
+     * @param language 语言（默认中文）
+     * @param entityClass 实体类（可选，用于获取实体标签）
      */
-    private generateHashChain;
     /**
-     * 生成描述
+     * 使用模板生成描述（优先使用 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;
 }