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

package/audit/interfaces/audit.interfaces.d.ts

@@ -1,4 +1,7 @@
-import { AuditOperation, MaskingStrategy, RecordStrategy } from '../enums/audit.enums';
+import { AuditOperation, MaskingStrategy, RecordStrategy, RollbackActionType, ChangeType } from '../enums/audit.enums';
+/**
+ * 审计上下文
+ */
 export interface AuditContext {
     userId?: string;
     username?: string;
@@ -9,16 +12,25 @@ export interface AuditContext {
     transactionId?: string;
     metadata?: Record<string, any>;
 }
+/**
+ * 审计策略接口
+ */
 export interface IAuditStrategy {
     shouldRecord(entityType: string, operation: AuditOperation): boolean;
     getRecordStrategy(entityType: string, operation: AuditOperation): RecordStrategy;
     getFieldFilter(entityType: string): IFieldFilter;
 }
+/**
+ * 字段过滤器接口
+ */
 export interface IFieldFilter {
     shouldIncludeField(fieldName: string, path: string[]): boolean;
     shouldMaskField(fieldName: string, path: string[]): boolean;
     getMaskingStrategy(fieldName: string, path: string[]): MaskingStrategy;
 }
+/**
+ * 实体差异
+ */
 export interface EntityDifference {
     changes: Array<{
         path: string[];
@@ -32,6 +44,9 @@ export interface EntityDifference {
         changed: number;
     };
 }
+/**
+ * 恢复选项
+ */
 export interface RestoreOptions {
     force?: boolean;
     dryRun?: boolean;
@@ -40,6 +55,9 @@ export interface RestoreOptions {
     skipDependencies?: boolean;
     connectionName?: string;
 }
+/**
+ * 恢复结果
+ */
 export interface RestoreResult {
     success: boolean;
     message?: string;
@@ -54,6 +72,9 @@ export interface RestoreResult {
         entityId: string;
     }>;
 }
+/**
+ * 预检查结果
+ */
 export interface PreCheckResult {
     canRestore: boolean;
     conflicts: Array<{
@@ -64,6 +85,9 @@ export interface PreCheckResult {
     }>;
     warnings: string[];
 }
+/**
+ * 批量操作结果
+ */
 export interface BatchOperationResult {
     total: number;
     success: number;
@@ -74,6 +98,9 @@ export interface BatchOperationResult {
     }>;
     results: any[];
 }
+/**
+ * 审计配置
+ */
 export interface AuditConfig {
     enabled?: boolean;
     defaultStrategy?: RecordStrategy;
@@ -94,26 +121,179 @@ export interface AuditConfig {
         };
     };
 }
+/**
+ * 实体级别审计配置
+ */
+/**
+ * 实体审计配置
+ *
+ * @description
+ * 支持基础审计配置
+ *
+ * @example
+ * ```typescript
+ * @EntityAudit({
+ *   enabled: true,
+ *   excludeFields: ['password'],
+ *   maskFields: ['email', 'phone'],
+ *   templateKey: 'user',
+ * })
+ * ```
+ */
 export interface EntityAuditConfig {
     enabled?: boolean;
     strategy?: RecordStrategy;
     includeFields?: string[];
     excludeFields?: string[];
     maskFields?: string[];
+    /**
+     * 操作模板键前缀
+     * @example 'user' -> 生成 'user.create', 'user.update', 'user.delete'
+     */
+    templateKey?: string;
+    /**
+     * @deprecated 使用 maskFields 代替
+     * 敏感字段列表（别名，用于兼容旧版本）
+     */
+    sensitiveFields?: string[];
 }
+/**
+ * 操作级别审计配置
+ */
 export interface OperationAuditConfig {
     enabled?: boolean;
     strategy?: RecordStrategy;
 }
+/**
+ * 字段显示选项
+ */
 export interface FieldDisplayOptions {
-    displayName?: string;
+    /**
+     * 字段标签（支持多语言）
+     * @example
+     * // 单语言
+     * label: '姓名'
+     *
+     * // 多语言
+     * label: { zh: '姓名', en: 'Name' }
+     */
+    label?: string | Record<string, string>;
+    /**
+     * 字段值的多语言标签映射
+     * @example
+     * valueLabels: {
+     *   active: { zh: '激活', en: 'Active' },
+     *   inactive: { zh: '未激活', en: 'Inactive' }
+     * }
+     */
+    valueLabels?: Record<string, Record<string, string>>;
     sensitive?: boolean;
     formatter?: (value: any) => string;
 }
+/**
+ * 控制器审计选项
+ */
 export interface ControllerAuditOptions {
     enabled?: boolean;
     operations?: AuditOperation[];
 }
+/**
+ * 方法审计选项
+ */
 export interface MethodAuditOptions {
     enabled?: boolean;
 }
+/**
+ * 变更详情
+ */
+export interface ChangeDetail {
+    fieldName: string;
+    fieldLabels?: Record<string, string>;
+    oldValue: any;
+    newValue: any;
+    displayOldValue?: Record<string, string>;
+    displayNewValue?: Record<string, string>;
+    changeType: ChangeType;
+}
+/**
+ * 回滚操作
+ */
+export interface RollbackAction {
+    type: RollbackActionType;
+    action: string;
+    params: Record<string, any>;
+    order: number;
+    handler?: string;
+}
+/**
+ * 操作模板配置（用于数据库存储）
+ */
+export interface OperationTemplateData {
+    key: string;
+    entityName: string;
+    operation: AuditOperation;
+    nameTemplates: Record<string, string>;
+    descriptionTemplates: Record<string, string>;
+    fieldLabels?: Record<string, Record<string, string>>;
+    valueDisplays?: Record<string, Record<string, Record<string, string>>>;
+}
+/**
+ * 手动操作日志数据
+ */
+export interface ManualOperationData {
+    transactionId: string;
+    operationTemplateKey: string;
+    descriptionParams: Record<string, any>;
+    userId?: string;
+    username?: string;
+    requestIp?: string;
+    rollbackActions?: RollbackAction[];
+}
+/**
+ * 手动日志记录选项（支持三种模式）
+ */
+export interface ManualLogOptions {
+    templateKey?: string;
+    descriptionParams?: Record<string, any>;
+    description?: string | Record<string, string>;
+    descriptionTemplate?: Record<string, string>;
+    userId?: string;
+    username?: string;
+    requestIp?: string;
+    rollbackActions?: RollbackAction[];
+    transactionId?: string;
+    autoCreateTransaction?: boolean;
+}
+/**
+ * 方法审计选项（支持模板和回滚）
+ */
+export interface AuditOperationOptions {
+    templateKey: string;
+    descriptionParams?: (args: any[], result: any, context: any) => Record<string, any>;
+    rollbackActions?: (args: any[], result: any, context: any) => RollbackAction[];
+    autoTransaction?: boolean;
+}
+/**
+ * 增强的实体审计配置（支持多语言）
+ */
+export interface EnhancedEntityAuditConfig extends EntityAuditConfig {
+    templateKey?: string;
+    fieldLabels?: Record<string, Record<string, string>>;
+    valueDisplays?: Record<string, Record<string, Record<string, string>>>;
+}
+/**
+ * 事务描述结果
+ */
+export interface TransactionDescription {
+    operationName: string;
+    description: string;
+    changes: Array<{
+        entityName?: string;
+        entityId?: string;
+        operation?: AuditOperation;
+        type?: string;
+        description: string;
+        details: any;
+        createdAt: Date;
+    }>;
+}

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

@@ -1,10 +1,25 @@
 import { ClsService } from 'nestjs-cls';
 import { AuditContext } from '../interfaces';
+/**
+ * 审计上下文服务
+ */
 export declare class AuditContextService {
     private readonly cls;
     constructor(cls: ClsService);
+    /**
+     * 获取当前上下文
+     */
     getCurrentContext(): Promise<AuditContext>;
+    /**
+     * 设置上下文
+     */
     setContext(context: Partial<AuditContext>): void;
+    /**
+     * 清除上下文
+     */
     clearContext(): void;
+    /**
+     * 获取默认上下文
+     */
     private getDefaultContext;
 }

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

@@ -21,22 +21,37 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AuditContextService = void 0;
 const common_1 = require("@nestjs/common");
 const nestjs_cls_1 = require("nestjs-cls");
+/**
+ * 审计上下文服务
+ */
 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',

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,163 @@
 import { Repository, EntityManager } from 'typeorm';
-import { EntityAuditLogEntity, EntityTransactionEntity } from '../entities';
+import { EntityAuditLogEntity, EntityTransactionEntity, ManualOperationLogEntity } 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 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);
+    /**
+     * 记录实体变更
+     */
     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;
+    /**
+     * 生成描述
+     */
     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>;
 }