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

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;
+}

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

@@ -0,0 +1,244 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AuditActionService = void 0;
+const common_1 = require("@nestjs/common");
+const audit_context_service_1 = require("./audit-context.service");
+const entity_audit_service_1 = require("./entity-audit.service");
+const enums_1 = require("../enums");
+/**
+ * 审计动作服务
+ * 提供声明式的审计动作管理，自动关联同一业务操作的所有实体变化
+ */
+let AuditActionService = class AuditActionService {
+    constructor(contextService, auditService) {
+        this.contextService = contextService;
+        this.auditService = auditService;
+    }
+    /**
+     * 在审计动作上下文中执行操作
+     * 自动关联该动作内的所有实体变化
+     *
+     * @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(options, operation) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const actionId = this.contextService.generateActionId();
+            const startTime = new Date();
+            // 创建审计动作上下文
+            const actionContext = {
+                actionId,
+                actionName: options.actionName,
+                operationTemplateKey: options.operationTemplateKey,
+                descriptionParams: options.descriptionParams,
+                startTime,
+                entityChanges: [],
+                detailedChanges: [],
+            };
+            // 设置到 CLS
+            this.contextService.setActionContext(actionContext);
+            let success = false;
+            let error;
+            let result;
+            try {
+                // 执行业务操作
+                result = yield operation();
+                success = true;
+                // 记录审计动作汇总日志（可选）
+                yield this.recordActionSummary(actionContext, options);
+                return {
+                    actionId,
+                    actionName: options.actionName,
+                    entityChanges: actionContext.entityChanges,
+                    duration: Date.now() - startTime.getTime(),
+                    success: true,
+                };
+            }
+            catch (err) {
+                error = err;
+                success = false;
+                // 记录失败的审计动作
+                yield this.recordActionSummary(actionContext, options, error);
+                throw err;
+            }
+            finally {
+                // 清除审计动作上下文
+                this.contextService.clearActionContext();
+            }
+        });
+    }
+    /**
+     * 记录审计动作汇总日志
+     */
+    recordActionSummary(actionContext, options, error) {
+        return __awaiter(this, void 0, void 0, function* () {
+            try {
+                const context = yield this.contextService.getCurrentContext();
+                // 使用 logEntityChangeWithTemplate 记录汇总信息
+                yield this.auditService.logEntityChangeWithTemplate({
+                    entityType: 'AuditAction',
+                    entityId: actionContext.actionId,
+                    operation: error ? enums_1.AuditOperation.DELETE : enums_1.AuditOperation.CREATE, // 失败用 DELETE 表示回滚
+                    oldValue: {},
+                    newValue: {
+                        actionName: actionContext.actionName,
+                        entityChangesCount: actionContext.entityChanges.length,
+                        duration: Date.now() - actionContext.startTime.getTime(),
+                        success: !error,
+                        error: error === null || error === void 0 ? void 0 : error.message,
+                    },
+                    operationTemplateKey: options.operationTemplateKey,
+                    descriptionParams: options.descriptionParams,
+                    metadata: Object.assign(Object.assign({}, options.metadata), { auditActionId: actionContext.actionId, entityChanges: actionContext.entityChanges }),
+                });
+            }
+            catch (err) {
+                console.error('Failed to record audit action summary:', err);
+            }
+        });
+    }
+    /**
+     * 获取审计动作的所有实体变化
+     */
+    getActionAuditLogs(actionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const logs = yield this.auditService['auditLogRepository'].find({
+                where: { auditActionId: actionId },
+                order: { sequenceInAction: 'ASC', createdAt: 'ASC' },
+            });
+            return {
+                actionId,
+                logs,
+                summary: {
+                    totalChanges: logs.length,
+                    operations: this.groupByOperation(logs),
+                    entities: this.groupByEntity(logs),
+                },
+            };
+        });
+    }
+    /**
+     * 获取请求内的所有审计动作
+     */
+    getRequestActions(requestId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const logs = yield this.auditService['auditLogRepository'].find({
+                where: { requestId },
+                order: { createdAt: 'ASC' },
+            });
+            // 按 auditActionId 分组
+            const actionMap = new Map();
+            const noActionLogs = [];
+            logs.forEach(log => {
+                if (log.auditActionId) {
+                    if (!actionMap.has(log.auditActionId)) {
+                        actionMap.set(log.auditActionId, []);
+                    }
+                    actionMap.get(log.auditActionId).push(log);
+                }
+                else {
+                    noActionLogs.push(log);
+                }
+            });
+            const actions = Array.from(actionMap.entries()).map(([actionId, logs]) => {
+                var _a;
+                return ({
+                    actionId,
+                    actionName: ((_a = logs[0]) === null || _a === void 0 ? void 0 : _a.auditActionName) || 'Unknown',
+                    entityChanges: logs.map(log => ({
+                        entityType: log.entityType,
+                        entityId: log.entityId,
+                        operation: log.operation,
+                        sequence: log.sequenceInAction,
+                        timestamp: log.createdAt,
+                    })),
+                    logs,
+                });
+            });
+            return {
+                requestId,
+                actions,
+                noActionLogs, // 未关联到任何动作的日志
+                summary: {
+                    totalActions: actions.length,
+                    totalChanges: logs.length,
+                },
+            };
+        });
+    }
+    groupByOperation(logs) {
+        const result = new Map();
+        logs.forEach(log => {
+            result.set(log.operation, (result.get(log.operation) || 0) + 1);
+        });
+        return Object.fromEntries(result);
+    }
+    groupByEntity(logs) {
+        const result = new Map();
+        logs.forEach(log => {
+            result.set(log.entityType, (result.get(log.entityType) || 0) + 1);
+        });
+        return Object.fromEntries(result);
+    }
+};
+exports.AuditActionService = AuditActionService;
+exports.AuditActionService = AuditActionService = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [audit_context_service_1.AuditContextService,
+        entity_audit_service_1.EntityAuditService])
+], AuditActionService);

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

@@ -1,10 +1,116 @@
 import { ClsService } from 'nestjs-cls';
 import { AuditContext } from '../interfaces';
+import { AuditOperation } from '../enums';
+/**
+ * 实体变更详情
+ */
+export interface EntityChangeDetail {
+    entityType: string;
+    entityId: string;
+    operation: AuditOperation;
+    oldValue: Record<string, any>;
+    newValue: Record<string, any>;
+    changedFields: string[];
+    sequence: number;
+    changeDetails?: Array<{
+        fieldName: string;
+        fieldLabel?: Record<string, string>;
+        oldValue: any;
+        newValue: any;
+        displayOldValue?: Record<string, string>;
+        displayNewValue?: Record<string, string>;
+        changeType: string;
+    }>;
+    metadata?: Record<string, any>;
+}
+/**
+ * 审计参数上下文
+ */
+export interface AuditParamsContext {
+    req: any;
+    result?: any;
+    error?: Error;
+    entityChanges: EntityChangeDetail[];
+    findEntity(entityType: string, operation?: AuditOperation): EntityChangeDetail | null;
+    findEntities(entityType: string, operation?: AuditOperation): EntityChangeDetail[];
+    countEntities(entityType: string, operation?: AuditOperation): number;
+    extractParams(mapping: Record<string, any>): Record<string, any>;
+    extractByPath(path: string): any;
+    extractByConfig(config: any): any;
+}
+/**
+ * 审计动作上下文
+ */
+export interface AuditActionContext {
+    actionId: string;
+    actionName: string;
+    operationTemplateKey?: string;
+    descriptionParams?: Record<string, any>;
+    paramsBuilder?: (context: AuditParamsContext) => Record<string, any>;
+    startTime: Date;
+    entityChanges: Array<{
+        entityType: string;
+        entityId: string;
+        operation: string;
+        sequence: number;
+    }>;
+    detailedChanges: EntityChangeDetail[];
+    req?: any;
+    result?: any;
+    error?: Error;
+}
+/**
+ * 审计上下文服务
+ */
 export declare class AuditContextService {
     private readonly cls;
     constructor(cls: ClsService);
+    /**
+     * 获取当前上下文
+     */
     getCurrentContext(): Promise<AuditContext>;
+    /**
+     * 设置上下文
+     */
     setContext(context: Partial<AuditContext>): void;
+    /**
+     * 清除上下文
+     */
     clearContext(): void;
+    /**
+     * 获取默认上下文
+     */
     private getDefaultContext;
+    /**
+     * 获取当前审计动作上下文
+     */
+    getCurrentActionContext(): AuditActionContext | null;
+    /**
+     * 设置审计动作上下文
+     */
+    setActionContext(context: AuditActionContext): void;
+    /**
+     * 清除审计动作上下文
+     */
+    clearActionContext(): void;
+    /**
+     * 记录实体变化到当前动作（简单版本）
+     */
+    recordEntityChangeInAction(entityType: string, entityId: string, operation: string): void;
+    /**
+     * 记录详细的实体变化
+     */
+    recordDetailedEntityChange(entityType: string, entityId: string, operation: AuditOperation, oldValue: Record<string, any>, newValue: Record<string, any>, changedFields: string[], metadata?: Record<string, any>): void;
+    /**
+     * 获取当前动作内的序号
+     */
+    getSequenceInAction(): number;
+    /**
+     * 生成审计动作ID
+     */
+    generateActionId(): string;
+    /**
+     * 构建审计参数上下文
+     */
+    buildParamsContext(): AuditParamsContext | null;
 }