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

package/audit/interceptors/audit.interceptor.js

@@ -24,6 +24,9 @@ const operators_1 = require("rxjs/operators");
 const crypto_1 = require("crypto");
 const audit_context_service_1 = require("../services/audit-context.service");
 const decorators_1 = require("../decorators");
+/**
+ * 审计拦截器
+ */
 let AuditInterceptor = class AuditInterceptor {
     constructor(contextService) {
         this.contextService = contextService;
@@ -32,16 +35,23 @@ let AuditInterceptor = class AuditInterceptor {
         const request = context.switchToHttp().getRequest();
         const handler = context.getHandler();
         const controller = context.getClass();
+        // 检查是否启用了审计
         if (!this.isAuditEnabled(controller, handler)) {
             return next.handle();
         }
+        // 设置请求上下文
         this.setRequestContext(request);
         return next.handle().pipe((0, operators_1.tap)(() => {
+            // 在响应后执行的操作
         }), (0, operators_1.catchError)((error) => __awaiter(this, void 0, void 0, function* () {
+            // 处理错误情况
             yield this.handleError(error, request);
             throw error;
         })));
     }
+    /**
+     * 设置请求上下文
+     */
     setRequestContext(request) {
         var _a, _b, _c;
         const user = request.user || {};
@@ -55,8 +65,12 @@ let AuditInterceptor = class AuditInterceptor {
         };
         this.contextService.setContext(auditContext);
     }
+    /**
+     * 处理错误
+     */
     handleError(error, request) {
         return __awaiter(this, void 0, void 0, function* () {
+            // 记录错误信息到上下文
             this.contextService.setContext({
                 metadata: {
                     error: {
@@ -68,12 +82,17 @@ let AuditInterceptor = class AuditInterceptor {
             });
         });
     }
+    /**
+     * 检查是否启用了审计
+     */
     isAuditEnabled(controller, handler) {
         try {
+            // 检查控制器级别设置
             const controllerMetadata = Reflect.getMetadata(decorators_1.CONTROLLER_AUDIT_OPTIONS, controller);
             if (controllerMetadata && controllerMetadata.enabled === false) {
                 return false;
             }
+            // 检查方法级别设置
             const handlerMetadata = Reflect.getMetadata(decorators_1.METHOD_AUDIT_OPTIONS, handler);
             if (handlerMetadata && handlerMetadata.enabled === false) {
                 return false;
@@ -81,9 +100,12 @@ let AuditInterceptor = class AuditInterceptor {
             return true;
         }
         catch (error) {
-            return true;
+            return true; // 默认启用
         }
     }
+    /**
+     * 生成请求ID
+     */
     generateRequestId() {
         return (0, crypto_1.randomBytes)(16).toString('hex');
     }

package/audit/interceptors/index.d.ts

@@ -1 +1,2 @@
 export * from './audit.interceptor';
+export * from './audit-action.interceptor';

package/audit/interceptors/index.js

@@ -15,3 +15,4 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./audit.interceptor"), exports);
+__exportStar(require("./audit-action.interceptor"), exports);

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,184 @@ 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
+     * // 单语言
+     * label: '订单'
+     *
+     * // 多语言
+     * label: { zh: '订单', en: 'Order', ja: '注文' }
+     */
+    label?: string | Record<string, string>;
+    /**
+     * 操作模板键前缀
+     * @example 'user' -> 生成 'user.create', 'user.update', 'user.delete'
+     */
+    templateKey?: 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-action.service.d.ts

@@ -0,0 +1,141 @@
+import { AuditContextService } from './audit-context.service';
+import { EntityAuditService } from './entity-audit.service';
+import { AuditOperation } from '../enums';
+/**
+ * 审计动作选项
+ */
+export interface AuditActionOptions {
+    /**
+     * 动作名称，如 'createOrder', 'updateUser'
+     */
+    actionName: string;
+    /**
+     * 操作模板键（可选）
+     * @example 'order.create'
+     */
+    operationTemplateKey?: string;
+    /**
+     * 描述参数，用于模板填充
+     * @example { productCount: 3, receiver: '张三', totalAmount: 299.99 }
+     */
+    descriptionParams?: Record<string, any>;
+    /**
+     * 自定义元数据
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * 审计动作结果
+ */
+export interface AuditActionResult {
+    actionId: string;
+    actionName: string;
+    entityChanges: Array<{
+        entityType: string;
+        entityId: string;
+        operation: string;
+        sequence: number;
+    }>;
+    duration: number;
+    success: boolean;
+    error?: Error;
+}
+/**
+ * 审计动作服务
+ * 提供声明式的审计动作管理，自动关联同一业务操作的所有实体变化
+ */
+export declare class AuditActionService {
+    private readonly contextService;
+    private readonly auditService;
+    constructor(contextService: AuditContextService, auditService: EntityAuditService);
+    /**
+     * 在审计动作上下文中执行操作
+     * 自动关联该动作内的所有实体变化
+     *
+     * @example
+     * ```typescript
+     * const result = await auditActionService.executeAction(
+     *   {
+     *     actionName: 'createOrder',
+     *     operationTemplateKey: 'order.create',
+     *     descriptionParams: {
+     *       productCount: orderItems.length,
+     *       receiver: order.receiverName,
+     *       totalAmount: order.totalAmount,
+     *       address: order.shippingAddress,
+     *     },
+     *   },
+     *   async () => {
+     *     // 1. 创建订单
+     *     const order = await this.orderRepository.save(newOrder);
+     *
+     *     // 2. 创建订单项
+     *     await this.orderItemRepository.save(orderItems);
+     *
+     *     // 3. 扣减库存
+     *     await this.inventoryService.deduct(orderItems);
+     *
+     *     // 4. 创建物流信息
+     *     await this.shippingService.create(order.id);
+     *
+     *     return order;
+     *   }
+     * );
+     *
+     * // 结果中包含所有实体变化：
+     * // result.entityChanges = [
+     * //   { entityType: 'Order', entityId: '1', operation: 'CREATE', sequence: 1 },
+     * //   { entityType: 'OrderItem', entityId: '1', operation: 'CREATE', sequence: 2 },
+     * //   { entityType: 'OrderItem', entityId: '2', operation: 'CREATE', sequence: 3 },
+     * //   { entityType: 'Inventory', entityId: '1', operation: 'UPDATE', sequence: 4 },
+     * //   { entityType: 'Shipping', entityId: '1', operation: 'CREATE', sequence: 5 },
+     * // ]
+     * ```
+     */
+    executeAction<T>(options: AuditActionOptions, operation: () => Promise<T>): Promise<AuditActionResult>;
+    /**
+     * 记录审计动作汇总日志
+     */
+    private recordActionSummary;
+    /**
+     * 获取审计动作的所有实体变化
+     */
+    getActionAuditLogs(actionId: string): Promise<{
+        actionId: string;
+        logs: import("..").EntityAuditLogEntity[];
+        summary: {
+            totalChanges: number;
+            operations: {
+                [k: string]: number;
+            };
+            entities: {
+                [k: string]: number;
+            };
+        };
+    }>;
+    /**
+     * 获取请求内的所有审计动作
+     */
+    getRequestActions(requestId: string): Promise<{
+        requestId: string;
+        actions: {
+            actionId: string;
+            actionName: string;
+            entityChanges: {
+                entityType: string;
+                entityId: string;
+                operation: AuditOperation;
+                sequence: number;
+                timestamp: Date;
+            }[];
+            logs: import("..").EntityAuditLogEntity[];
+        }[];
+        noActionLogs: import("..").EntityAuditLogEntity[];
+        summary: {
+            totalActions: number;
+            totalChanges: number;
+        };
+    }>;
+    private groupByOperation;
+    private groupByEntity;
+}