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

package/audit/audit.module.d.ts

@@ -1,7 +1,17 @@
 import { DynamicModule } from '@nestjs/common';
 import { AuditConfig } from './interfaces';
+/**
+ * 审计模块
+ */
 export declare class AuditModule {
+    /**
+     * 注册审计模块
+     * @param config 审计配置
+     */
     static forRoot(config?: AuditConfig): DynamicModule;
+    /**
+     * 注册审计模块（异步）
+     */
     static forRootAsync(options: {
         imports?: any[];
         inject?: any[];

package/audit/audit.module.js

@@ -25,11 +25,22 @@ const services_1 = require("./services");
 const subscribers_1 = require("./subscribers");
 const interceptors_1 = require("./interceptors");
 const controllers_1 = require("./controllers");
+/**
+ * 审计模块
+ */
 let AuditModule = AuditModule_1 = class AuditModule {
+    /**
+     * 注册审计模块
+     * @param config 审计配置
+     */
     static forRoot(config) {
         var _a, _b;
         const auditConnectionName = ((_a = config === null || config === void 0 ? void 0 : config.connections) === null || _a === void 0 ? void 0 : _a.audit) || 'default';
         const monitoredConnections = ((_b = config === null || config === void 0 ? void 0 : config.connections) === null || _b === void 0 ? void 0 : _b.monitored) || ['default'];
+        console.log('[AuditModule] auditConnectionName:', auditConnectionName);
+        console.log('[AuditModule] monitoredConnections:', monitoredConnections);
+        console.log('[AuditModule] config:', JSON.stringify(config === null || config === void 0 ? void 0 : config.connections));
+        // 创建多个订阅者提供者，每个监听的数据库连接一个
         const subscriberProviders = monitoredConnections.map((connectionName) => ({
             provide: `AUDIT_SUBSCRIBER_${connectionName}`,
             useFactory: (auditService, contextService, auditStrategy, dataSource) => {
@@ -43,6 +54,7 @@ let AuditModule = AuditModule_1 = class AuditModule {
                 (0, typeorm_1.getDataSourceToken)(connectionName),
             ],
         }));
+        // 创建repository别名提供者，使service能够注入正确连接的repository
         const repositoryProviders = [
             {
                 provide: (0, typeorm_1.getRepositoryToken)(entities_1.EntityAuditLogEntity),
@@ -58,6 +70,27 @@ let AuditModule = AuditModule_1 = class AuditModule {
                 },
                 inject: [(0, typeorm_1.getDataSourceToken)(auditConnectionName)],
             },
+            {
+                provide: (0, typeorm_1.getRepositoryToken)(entities_1.OperationTemplateEntity),
+                useFactory: (dataSource) => {
+                    return dataSource.getRepository(entities_1.OperationTemplateEntity);
+                },
+                inject: [(0, typeorm_1.getDataSourceToken)(auditConnectionName)],
+            },
+            {
+                provide: (0, typeorm_1.getRepositoryToken)(entities_1.ManualOperationLogEntity),
+                useFactory: (dataSource) => {
+                    return dataSource.getRepository(entities_1.ManualOperationLogEntity);
+                },
+                inject: [(0, typeorm_1.getDataSourceToken)(auditConnectionName)],
+            },
+            {
+                provide: (0, typeorm_1.getRepositoryToken)(entities_1.AuditActionSummaryEntity),
+                useFactory: (dataSource) => {
+                    return dataSource.getRepository(entities_1.AuditActionSummaryEntity);
+                },
+                inject: [(0, typeorm_1.getDataSourceToken)(auditConnectionName)],
+            },
             {
                 provide: 'AUDIT_ENTITY_MANAGER',
                 useFactory: (dataSource) => {
@@ -69,7 +102,14 @@ let AuditModule = AuditModule_1 = class AuditModule {
         return {
             module: AuditModule_1,
             imports: [
-                typeorm_1.TypeOrmModule.forFeature([entities_1.EntityAuditLogEntity, entities_1.EntityTransactionEntity], auditConnectionName),
+                // ��计日志存储到指定的数据库连接
+                typeorm_1.TypeOrmModule.forFeature([
+                    entities_1.EntityAuditLogEntity,
+                    entities_1.EntityTransactionEntity,
+                    entities_1.OperationTemplateEntity,
+                    entities_1.ManualOperationLogEntity,
+                    entities_1.AuditActionSummaryEntity,
+                ], auditConnectionName),
                 nestjs_cls_1.ClsModule.forRoot({
                     global: true,
                     middleware: { mount: true },
@@ -95,7 +135,11 @@ let AuditModule = AuditModule_1 = class AuditModule {
                 ...repositoryProviders,
                 services_1.EntityAuditService,
                 services_1.TransactionAuditService,
+                services_1.OperationDescriptionService,
+                services_1.AuditActionService,
+                services_1.ManualAuditLogService,
                 interceptors_1.AuditInterceptor,
+                interceptors_1.AuditActionInterceptor,
                 ...subscriberProviders,
             ],
             exports: [
@@ -104,11 +148,20 @@ let AuditModule = AuditModule_1 = class AuditModule {
                 services_1.MultiDatabaseService,
                 services_1.EntityAuditService,
                 services_1.TransactionAuditService,
+                services_1.OperationDescriptionService,
+                services_1.AuditActionService,
+                services_1.ManualAuditLogService,
                 interceptors_1.AuditInterceptor,
+                interceptors_1.AuditActionInterceptor,
+                (0, typeorm_1.getRepositoryToken)(entities_1.AuditActionSummaryEntity),
             ],
         };
     }
+    /**
+     * 注册审计模块（异步）
+     */
     static forRootAsync(options) {
+        // 创建repository别名提供者，使service能够注入正确连接的repository
         const repositoryProviders = [
             {
                 provide: (0, typeorm_1.getRepositoryToken)(entities_1.EntityAuditLogEntity),
@@ -195,6 +248,7 @@ let AuditModule = AuditModule_1 = class AuditModule {
                         const config = yield options.useFactory(...args);
                         const monitoredConnections = ((_a = config === null || config === void 0 ? void 0 : config.connections) === null || _a === void 0 ? void 0 : _a.monitored) || ['default'];
                         const auditConnectionName = ((_b = config === null || config === void 0 ? void 0 : config.connections) === null || _b === void 0 ? void 0 : _b.audit) || 'default';
+                        // 动态注册 TypeORM 实体
                         const typeOrmModule = typeorm_1.TypeOrmModule.forFeature([entities_1.EntityAuditLogEntity, entities_1.EntityTransactionEntity], auditConnectionName);
                         return monitoredConnections;
                     }),
@@ -211,7 +265,11 @@ let AuditModule = AuditModule_1 = class AuditModule {
                 ...repositoryProviders,
                 services_1.EntityAuditService,
                 services_1.TransactionAuditService,
+                services_1.OperationDescriptionService,
+                services_1.AuditActionService,
+                services_1.ManualAuditLogService,
                 interceptors_1.AuditInterceptor,
+                interceptors_1.AuditActionInterceptor,
             ],
             exports: [
                 services_1.AuditContextService,
@@ -219,7 +277,11 @@ let AuditModule = AuditModule_1 = class AuditModule {
                 services_1.MultiDatabaseService,
                 services_1.EntityAuditService,
                 services_1.TransactionAuditService,
+                services_1.OperationDescriptionService,
+                services_1.AuditActionService,
+                services_1.ManualAuditLogService,
                 interceptors_1.AuditInterceptor,
+                interceptors_1.AuditActionInterceptor,
             ],
         };
     }

package/audit/controllers/audit.controller.d.ts

@@ -4,17 +4,105 @@ import { AuditLogQueryDto, CompareEntitiesDto, RestoreEntityDto, PreCheckRestore
 import { EntityAuditLogEntity } from '../entities';
 import { EntityDifference, PreCheckResult, RestoreResult } from '../interfaces';
 import { PageDto } from '../../common/dto';
+/**
+ * 审计控制器
+ */
 export declare class AuditController {
     private readonly entityAuditService;
     private readonly transactionAuditService;
     constructor(entityAuditService: EntityAuditService, transactionAuditService: TransactionAuditService);
+    /**
+     * 查询实体审计日志
+     */
     getAuditLogs(query: AuditLogQueryDto): Promise<PageDto<EntityAuditLogEntity>>;
+    /**
+     * 比较实体版本
+     */
     compareEntities(query: CompareEntitiesDto): Promise<EntityDifference>;
+    /**
+     * 预检查恢复操作
+     */
     preCheckRestore(preCheckDto: PreCheckRestoreDto): Promise<PreCheckResult>;
+    /**
+     * 恢复实体到指定版本
+     */
     restoreEntity(restoreDto: RestoreEntityDto): Promise<RestoreResult>;
+    /**
+     * 开始审计事务
+     */
     beginTransaction(beginTransactionDto: BeginTransactionDto): Promise<{
         transactionId: string;
     }>;
+    /**
+     * 提交审计事务
+     */
     commitTransaction(transactionId: string): Promise<void>;
+    /**
+     * 回滚审计事务
+     */
     rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * 查询审计动作汇总记录
+     */
+    getAuditActions(userId?: string, username?: string, actionName?: string, success?: string, startTime?: string, endTime?: string, page?: number, limit?: number): Promise<PageDto<import("../entities").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: import("..").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: import("..").AuditOperation;
+            }[];
+        };
+    }>;
 }

package/audit/controllers/audit.controller.js

@@ -27,48 +27,97 @@ const swagger_1 = require("@nestjs/swagger");
 const entity_audit_service_1 = require("../services/entity-audit.service");
 const transaction_audit_service_1 = require("../services/transaction-audit.service");
 const dto_1 = require("../dto");
+/**
+ * 审计控制器
+ */
 let AuditController = class AuditController {
     constructor(entityAuditService, transactionAuditService) {
         this.entityAuditService = entityAuditService;
         this.transactionAuditService = transactionAuditService;
     }
+    /**
+     * 查询实体审计日志
+     */
     getAuditLogs(query) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.entityAuditService.getAuditLogs(query);
         });
     }
+    /**
+     * 比较实体版本
+     */
     compareEntities(query) {
         return __awaiter(this, void 0, void 0, function* () {
             var _a, _b;
             return this.entityAuditService.compareEntities(query.entityType, query.entityId, (_a = query.fromVersion) === null || _a === void 0 ? void 0 : _a.toString(), (_b = query.toVersion) === null || _b === void 0 ? void 0 : _b.toString());
         });
     }
+    /**
+     * 预检查恢复操作
+     */
     preCheckRestore(preCheckDto) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.entityAuditService.preCheckRestore(preCheckDto.entityType, preCheckDto.entityId, preCheckDto.auditLogId);
         });
     }
+    /**
+     * 恢复实体到指定版本
+     */
     restoreEntity(restoreDto) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.entityAuditService.restoreEntity(restoreDto.entityType, restoreDto.entityId, restoreDto.auditLogId, restoreDto.options);
         });
     }
+    /**
+     * 开始审计事务
+     */
     beginTransaction(beginTransactionDto) {
         return __awaiter(this, void 0, void 0, function* () {
             const transactionId = yield this.transactionAuditService.beginTransaction(beginTransactionDto.description);
             return { transactionId };
         });
     }
+    /**
+     * 提交审计事务
+     */
     commitTransaction(transactionId) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.transactionAuditService.commitTransaction(transactionId);
         });
     }
+    /**
+     * 回滚审计事务
+     */
     rollbackTransaction(transactionId) {
         return __awaiter(this, void 0, void 0, function* () {
             return this.transactionAuditService.rollbackTransaction(transactionId);
         });
     }
+    /**
+     * 查询审计动作汇总记录
+     */
+    getAuditActions(userId_1, username_1, actionName_1, success_1, startTime_1, endTime_1) {
+        return __awaiter(this, arguments, void 0, function* (userId, username, actionName, success, startTime, endTime, page = 1, limit = 20) {
+            return this.entityAuditService.getAuditActions({
+                userId,
+                username,
+                actionName,
+                success: success ? success === 'true' : undefined,
+                startTime: startTime ? new Date(startTime) : undefined,
+                endTime: endTime ? new Date(endTime) : undefined,
+                page,
+                limit,
+            });
+        });
+    }
+    /**
+     * 查询单个审计动作的详细信息
+     */
+    getAuditActionDetail(actionId) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return this.entityAuditService.getAuditActionDetail(actionId);
+        });
+    }
 };
 exports.AuditController = AuditController;
 __decorate([
@@ -134,6 +183,31 @@ __decorate([
     __metadata("design:paramtypes", [String]),
     __metadata("design:returntype", Promise)
 ], AuditController.prototype, "rollbackTransaction", null);
+__decorate([
+    (0, common_1.Get)('actions'),
+    (0, swagger_1.ApiOperation)({ summary: '查询审计动作汇总记录' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: '返回审计动作汇总列表' }),
+    __param(0, (0, common_1.Query)('userId')),
+    __param(1, (0, common_1.Query)('username')),
+    __param(2, (0, common_1.Query)('actionName')),
+    __param(3, (0, common_1.Query)('success')),
+    __param(4, (0, common_1.Query)('startTime')),
+    __param(5, (0, common_1.Query)('endTime')),
+    __param(6, (0, common_1.Query)('page')),
+    __param(7, (0, common_1.Query)('limit')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, String, String, String, String, String, Number, Number]),
+    __metadata("design:returntype", Promise)
+], AuditController.prototype, "getAuditActions", null);
+__decorate([
+    (0, common_1.Get)('actions/:actionId'),
+    (0, swagger_1.ApiOperation)({ summary: '查询审计动作详细信息' }),
+    (0, swagger_1.ApiResponse)({ status: 200, description: '返回审计动作详细信息' }),
+    __param(0, (0, common_1.Param)('actionId')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], AuditController.prototype, "getAuditActionDetail", null);
 exports.AuditController = AuditController = __decorate([
     (0, common_1.Controller)('audit'),
     (0, swagger_1.ApiTags)('audit'),

package/audit/decorators/audit-action.decorator.d.ts

@@ -0,0 +1,74 @@
+import { AuditParamsContext } from '../services/audit-context.service';
+export declare const AUDIT_ACTION_METADATA = "AUDIT_ACTION_METADATA";
+/**
+ * 审计动作选项
+ */
+export interface AuditActionOptions {
+    /**
+     * 操作模板键（可选）
+     * @example 'order.create'
+     */
+    templateKey?: string;
+    /**
+     * 参数构建器，用于从请求和实体变更中提取描述参数
+     * @param context - 包含 req, result, error, entityChanges 的上下文
+     * @returns 描述参数对象
+     *
+     * @example
+     * paramsBuilder: (context) => {
+     *   const order = context.findEntity('Order', 'CREATE');
+     *   const items = context.findEntities('OrderItem', 'CREATE');
+     *   return {
+     *     'order.sn': order?.newValue.orderSn,
+     *     'product.count': items.length,
+     *     'receiver': order?.newValue.receiverName,
+     *   };
+     * }
+     */
+    paramsBuilder?: (context: AuditParamsContext) => Record<string, any>;
+    /**
+     * 是否启用审计（默认 true）
+     */
+    enabled?: boolean;
+    /**
+     * 扩展元数据
+     */
+    metadata?: Record<string, any>;
+}
+/**
+ * 审计动作装饰器元数据
+ */
+export interface AuditActionMetadata {
+    actionName: string;
+    options: AuditActionOptions;
+}
+/**
+ * 审计动作装饰器
+ * 用于在控制器方法上标记审计动作，自动收集该请求中的所有实体变更
+ *
+ * @param actionName - 操作名称，如 'createOrder', 'cancelOrder'
+ * @param options - 审计动作选项
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * @AuditAction('createOrder', {
+ *   templateKey: 'order.create',
+ *   paramsBuilder: (context) => {
+ *     const order = context.findEntity('Order', 'CREATE');
+ *     const items = context.findEntities('OrderItem', 'CREATE');
+ *     return {
+ *       'order.sn': order?.newValue.orderSn,
+ *       'product.count': items.length,
+ *       'product.names': items.map(i => i.metadata?.productName).join('、'),
+ *       'receiver': order?.newValue.receiverName,
+ *       'totalAmount': order?.newValue.totalAmount,
+ *     };
+ *   }
+ * })
+ * async createOrder(@Body() dto: CreateOrderDto) {
+ *   return await this.orderService.create(dto);
+ * }
+ * ```
+ */
+export declare function AuditAction(actionName: string, options?: AuditActionOptions): MethodDecorator;

package/audit/decorators/audit-action.decorator.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUDIT_ACTION_METADATA = void 0;
+exports.AuditAction = AuditAction;
+const common_1 = require("@nestjs/common");
+exports.AUDIT_ACTION_METADATA = 'AUDIT_ACTION_METADATA';
+/**
+ * 审计动作装饰器
+ * 用于在控制器方法上标记审计动作，自动收集该请求中的所有实体变更
+ *
+ * @param actionName - 操作名称，如 'createOrder', 'cancelOrder'
+ * @param options - 审计动作选项
+ *
+ * @example
+ * ```typescript
+ * @Post()
+ * @AuditAction('createOrder', {
+ *   templateKey: 'order.create',
+ *   paramsBuilder: (context) => {
+ *     const order = context.findEntity('Order', 'CREATE');
+ *     const items = context.findEntities('OrderItem', 'CREATE');
+ *     return {
+ *       'order.sn': order?.newValue.orderSn,
+ *       'product.count': items.length,
+ *       'product.names': items.map(i => i.metadata?.productName).join('、'),
+ *       'receiver': order?.newValue.receiverName,
+ *       'totalAmount': order?.newValue.totalAmount,
+ *     };
+ *   }
+ * })
+ * async createOrder(@Body() dto: CreateOrderDto) {
+ *   return await this.orderService.create(dto);
+ * }
+ * ```
+ */
+function AuditAction(actionName, options = {}) {
+    const metadata = {
+        actionName,
+        options: Object.assign({ enabled: true }, options),
+    };
+    return (0, common_1.SetMetadata)(exports.AUDIT_ACTION_METADATA, metadata);
+}

package/audit/decorators/audit-controller.decorator.d.ts

@@ -1,5 +1,13 @@
 import { ControllerAuditOptions, MethodAuditOptions } from '../interfaces';
 export declare const CONTROLLER_AUDIT_OPTIONS: unique symbol;
 export declare const METHOD_AUDIT_OPTIONS: unique symbol;
-export declare function EntityAuditController(options?: ControllerAuditOptions): ClassDecorator;
+/**
+ * 控制器审计装饰器
+ * @param options 控制器审计选项
+ */
+export declare function AuditController(options?: ControllerAuditOptions): ClassDecorator;
+/**
+ * 方法审计装饰器
+ * @param options 方法审计选项
+ */
 export declare function AuditMethod(options?: MethodAuditOptions): MethodDecorator;

package/audit/decorators/audit-controller.decorator.js

@@ -1,15 +1,24 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.METHOD_AUDIT_OPTIONS = exports.CONTROLLER_AUDIT_OPTIONS = void 0;
-exports.EntityAuditController = EntityAuditController;
+exports.AuditController = AuditController;
 exports.AuditMethod = AuditMethod;
+// 元数据键
 exports.CONTROLLER_AUDIT_OPTIONS = Symbol('CONTROLLER_AUDIT_OPTIONS');
 exports.METHOD_AUDIT_OPTIONS = Symbol('METHOD_AUDIT_OPTIONS');
-function EntityAuditController(options) {
+/**
+ * 控制器审计装饰器
+ * @param options 控制器审计选项
+ */
+function AuditController(options) {
     return (target) => {
         Reflect.defineMetadata(exports.CONTROLLER_AUDIT_OPTIONS, options || {}, target);
     };
 }
+/**
+ * 方法审计装饰器
+ * @param options 方法审计选项
+ */
 function AuditMethod(options) {
     return (target, propertyKey, descriptor) => {
         Reflect.defineMetadata(exports.METHOD_AUDIT_OPTIONS, options || {}, descriptor.value);

package/audit/decorators/audit-operation.decorator.d.ts

@@ -1,5 +1,50 @@
 import { AuditOperationOptions } from '../interfaces';
 export declare const AUDIT_OPERATION_OPTIONS: unique symbol;
+/**
+ * 方法审计装饰器
+ *
+ * @description
+ * 用于手动记录业务操作的审计日志，支持：
+ * - 自定义操作模板
+ * - 动态描述参数
+ * - 回滚操作定义
+ * - 自动事务管理
+ *
+ * @param options 审计操作选项
+ *
+ * @example
+ * ```typescript
+ * @AuditLog({
+ *   templateKey: 'user.approve',
+ *   descriptionParams: (args, result) => ({
+ *     username: args[0].username,
+ *     approver: result.approver
+ *   }),
+ *   rollbackActions: (args, result) => [{
+ *     type: RollbackActionType.UPDATE,
+ *     action: 'reject',
+ *     params: { userId: args[0].id },
+ *     order: 1
+ *   }],
+ *   autoTransaction: true
+ * })
+ * async approveUser(user: User): Promise<ApprovalResult> {
+ *   // 业务逻辑
+ * }
+ * ```
+ */
 export declare function AuditLog(options: AuditOperationOptions): MethodDecorator;
+/**
+ * 获取方法的审计配置
+ * @param target 目标类或实例
+ * @param propertyKey 方法名
+ * @returns 审计操作选项
+ */
 export declare function getAuditOperationConfig(target: any, propertyKey: string | symbol): AuditOperationOptions | undefined;
+/**
+ * 检查方法是否配置了审计
+ * @param target 目标类或实例
+ * @param propertyKey 方法名
+ * @returns 是否配置了审计
+ */
 export declare function hasAuditOperation(target: any, propertyKey: string | symbol): boolean;

package/audit/decorators/audit-operation.decorator.js

@@ -4,20 +4,69 @@ exports.AUDIT_OPERATION_OPTIONS = void 0;
 exports.AuditLog = AuditLog;
 exports.getAuditOperationConfig = getAuditOperationConfig;
 exports.hasAuditOperation = hasAuditOperation;
+// 元数据键
 exports.AUDIT_OPERATION_OPTIONS = Symbol('AUDIT_OPERATION_OPTIONS');
+/**
+ * 方法审计装饰器
+ *
+ * @description
+ * 用于手动记录业务操作的审计日志，支持：
+ * - 自定义操作模板
+ * - 动态描述参数
+ * - 回滚操作定义
+ * - 自动事务管理
+ *
+ * @param options 审计操作选项
+ *
+ * @example
+ * ```typescript
+ * @AuditLog({
+ *   templateKey: 'user.approve',
+ *   descriptionParams: (args, result) => ({
+ *     username: args[0].username,
+ *     approver: result.approver
+ *   }),
+ *   rollbackActions: (args, result) => [{
+ *     type: RollbackActionType.UPDATE,
+ *     action: 'reject',
+ *     params: { userId: args[0].id },
+ *     order: 1
+ *   }],
+ *   autoTransaction: true
+ * })
+ * async approveUser(user: User): Promise<ApprovalResult> {
+ *   // 业务逻辑
+ * }
+ * ```
+ */
 function AuditLog(options) {
     return (target, propertyKey, descriptor) => {
+        // 验证必需参数
         if (!options.templateKey) {
             throw new Error(`@AuditLog requires templateKey for method ${String(propertyKey)}`);
         }
+        // 存储元数据
         const methodMetadata = Object.assign(Object.assign({}, options), { methodName: String(propertyKey) });
         Reflect.defineMetadata(exports.AUDIT_OPERATION_OPTIONS, methodMetadata, target, propertyKey);
+        // 返回原始描述符，实际的拦截逻辑由 AuditInterceptor 处理
         return descriptor;
     };
 }
+/**
+ * 获取方法的审计配置
+ * @param target 目标类或实例
+ * @param propertyKey 方法名
+ * @returns 审计操作选项
+ */
 function getAuditOperationConfig(target, propertyKey) {
     return Reflect.getMetadata(exports.AUDIT_OPERATION_OPTIONS, target, propertyKey);
 }
+/**
+ * 检查方法是否配置了审计
+ * @param target 目标类或实例
+ * @param propertyKey 方法名
+ * @returns 是否配置了审计
+ */
 function hasAuditOperation(target, propertyKey) {
     return Reflect.hasMetadata(exports.AUDIT_OPERATION_OPTIONS, target, propertyKey);
 }