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

package/audit/services/manual-audit-log.service.d.ts

@@ -2,6 +2,11 @@ import { Repository, DataSource } from 'typeorm';
 import { ManualOperationLogEntity, EntityTransactionEntity } from '../entities';
 import { AuditContextService } from './audit-context.service';
 import { ManualLogOptions } from '../interfaces';
+/**
+ * 手动审计日志服务
+ *
+ * 提供全局静态方法，在任意地方手动记录操作日志
+ */
 export declare class ManualAuditLogService {
     private readonly manualLogRepository;
     private readonly transactionRepository;
@@ -9,15 +14,134 @@ export declare class ManualAuditLogService {
     private readonly dataSource;
     private static instance;
     constructor(manualLogRepository: Repository<ManualOperationLogEntity>, transactionRepository: Repository<EntityTransactionEntity>, contextService: AuditContextService, dataSource: DataSource);
+    /**
+     * 全局静态方法：记录操作日志
+     *
+     * @description
+     * 支持三种记录模式：
+     * 1. 模板键模式：从数据库查找模板
+     * 2. 直接描述模式：直接传入字符串或多语言描述
+     * 3. 内联模板模式：传入多语言模板 + 参数
+     *
+     * @example
+     * // 模式1：模板键模式
+     * await ManualAuditLogService.log({
+     *   templateKey: 'user.login',
+     *   descriptionParams: {
+     *     username: 'john.doe',
+     *     loginTime: new Date().toISOString(),
+     *   },
+     * });
+     *
+     * @example
+     * // 模式2：直接描述模式（字符串）
+     * await ManualAuditLogService.log({
+     *   description: '用户登录系统',
+     * });
+     *
+     * @example
+     * // 模式2：直接描述模式（多语言）
+     * await ManualAuditLogService.log({
+     *   description: {
+     *     zh: '用户登录系统',
+     *     en: 'User logged in',
+     *   },
+     * });
+     *
+     * @example
+     * // 模式3：内联模板模式
+     * await ManualAuditLogService.log({
+     *   descriptionTemplate: {
+     *     zh: '用户 {username} 在 {time} 登录了系统',
+     *     en: 'User {username} logged in at {time}',
+     *   },
+     *   descriptionParams: {
+     *     username: 'john.doe',
+     *     time: new Date().toISOString(),
+     *   },
+     * });
+     */
     static log(options: ManualLogOptions): Promise<ManualOperationLogEntity>;
+    /**
+     * 实例方法：记录操作日志
+     */
     logOperation(options: ManualLogOptions): Promise<ManualOperationLogEntity>;
+    /**
+     * 静态方法：带事务记录
+     *
+     * @example
+     * ```typescript
+     * const txId = await ManualAuditLogService.beginTransaction('user-123', 'John Doe');
+     *
+     * await ManualAuditLogService.log({
+     *   templateKey: 'order.create',
+     *   descriptionParams: { orderId: 'order-1' },
+     *   transactionId: txId,
+     *   autoCreateTransaction: false,
+     * });
+     *
+     * await ManualAuditLogService.log({
+     *   templateKey: 'payment.process',
+     *   descriptionParams: { paymentId: 'pay-1' },
+     *   transactionId: txId,
+     *   autoCreateTransaction: false,
+     * });
+     *
+     * await ManualAuditLogService.commitTransaction(txId);
+     * ```
+     */
     static beginTransaction(userId?: string, username?: string): Promise<string>;
+    /**
+     * 静态方法：提交事务
+     */
     static commitTransaction(transactionId: string): Promise<void>;
+    /**
+     * 静态方法：回滚事务
+     */
     static rollbackTransaction(transactionId: string): Promise<void>;
+    /**
+     * 创建事务
+     */
     private createTransaction;
+    /**
+     * 更新事务状态
+     */
     private updateTransactionStatus;
+    /**
+     * 生成事务ID
+     */
     private generateTransactionId;
+    /**
+     * 批量记录操作日志
+     *
+     * @description
+     * 批量记录多个操作，支持所有三种记录模式
+     *
+     * @example
+     * ```typescript
+     * // 混合使用多种模式
+     * await ManualAuditLogService.logBatch([
+     *   {
+     *     templateKey: 'product.update',
+     *     descriptionParams: { productId: 'p1', field: 'price' },
+     *   },
+     *   {
+     *     description: '批量更新库存',
+     *   },
+     *   {
+     *     descriptionTemplate: {
+     *       zh: '更新产品 {productId} 的 {field}',
+     *       en: 'Update {field} of product {productId}',
+     *     },
+     *     descriptionParams: { productId: 'p3', field: 'stock' },
+     *   },
+     * ]);
+     * ```
+     */
     static logBatch(operations: ManualLogOptions[], sharedTransactionId?: string): Promise<ManualOperationLogEntity[]>;
+    /**
+     * 查询操作日志
+     */
     static findLogs(options: {
         templateKey?: string;
         userId?: string;

package/audit/services/manual-audit-log.service.js

@@ -30,14 +30,67 @@ const entities_1 = require("../entities");
 const audit_context_service_1 = require("./audit-context.service");
 const enums_1 = require("../enums");
 const crypto_1 = require("crypto");
+/**
+ * 手动审计日志服务
+ *
+ * 提供全局静态方法，在任意地方手动记录操作日志
+ */
 let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogService {
     constructor(manualLogRepository, transactionRepository, contextService, dataSource) {
         this.manualLogRepository = manualLogRepository;
         this.transactionRepository = transactionRepository;
         this.contextService = contextService;
         this.dataSource = dataSource;
+        // 设置静态实例
         ManualAuditLogService_1.instance = this;
     }
+    /**
+     * 全局静态方法：记录操作日志
+     *
+     * @description
+     * 支持三种记录模式：
+     * 1. 模板键模式：从数据库查找模板
+     * 2. 直接描述模式：直接传入字符串或多语言描述
+     * 3. 内联模板模式：传入多语言模板 + 参数
+     *
+     * @example
+     * // 模式1：模板键模式
+     * await ManualAuditLogService.log({
+     *   templateKey: 'user.login',
+     *   descriptionParams: {
+     *     username: 'john.doe',
+     *     loginTime: new Date().toISOString(),
+     *   },
+     * });
+     *
+     * @example
+     * // 模式2：直接描述模式（字符串）
+     * await ManualAuditLogService.log({
+     *   description: '用户登录系统',
+     * });
+     *
+     * @example
+     * // 模式2：直接描述模式（多语言）
+     * await ManualAuditLogService.log({
+     *   description: {
+     *     zh: '用户登录系统',
+     *     en: 'User logged in',
+     *   },
+     * });
+     *
+     * @example
+     * // 模式3：内联模板模式
+     * await ManualAuditLogService.log({
+     *   descriptionTemplate: {
+     *     zh: '用户 {username} 在 {time} 登录了系统',
+     *     en: 'User {username} logged in at {time}',
+     *   },
+     *   descriptionParams: {
+     *     username: 'john.doe',
+     *     time: new Date().toISOString(),
+     *   },
+     * });
+     */
     static log(options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
@@ -46,30 +99,44 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             return ManualAuditLogService_1.instance.logOperation(options);
         });
     }
+    /**
+     * 实例方法：记录操作日志
+     */
     logOperation(options) {
         return __awaiter(this, void 0, void 0, function* () {
             const { templateKey, description, descriptionTemplate, descriptionParams, userId, username, requestIp, rollbackActions, transactionId, autoCreateTransaction = true, } = options;
+            // 验证参数：至少提供一种模式
             if (!templateKey && !description && !descriptionTemplate) {
                 throw new Error('ManualAuditLogService.log() requires one of: templateKey, description, or descriptionTemplate');
             }
+            // 验证参数冲突
             const modeCount = [templateKey, description, descriptionTemplate].filter(Boolean).length;
             if (modeCount > 1) {
                 throw new Error('ManualAuditLogService.log() accepts only one mode: use either templateKey, description, or descriptionTemplate');
             }
+            // 获取当前上下文（如果有）
             const context = yield this.contextService.getCurrentContext();
+            // 合并用户信息（优先使用传入的参数）
             const finalUserId = userId || context.userId || 'system';
             const finalUsername = username || context.username || 'system';
             const finalRequestIp = requestIp || context.requestIp || 'unknown';
+            // 生成或使用事务ID
             let finalTransactionId = transactionId || context.transactionId;
             if (!finalTransactionId && autoCreateTransaction) {
+                // 自动创建事务
                 finalTransactionId = yield this.createTransaction(finalUserId, finalUsername);
             }
+            // 创建手动操作日志
             const manualLog = this.manualLogRepository.create({
                 transactionId: finalTransactionId,
+                // 模式1: 模板键模式
                 operationTemplateKey: templateKey || null,
                 descriptionParams: descriptionParams || null,
+                // 模式2: 直接描���模式
                 directDescription: description || null,
+                // 模式3: 内联模板模式
                 inlineTemplate: descriptionTemplate || null,
+                // 通用字段
                 userId: finalUserId,
                 username: finalUsername,
                 requestIp: finalRequestIp,
@@ -78,6 +145,30 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             return this.manualLogRepository.save(manualLog);
         });
     }
+    /**
+     * 静态方法：带事务记录
+     *
+     * @example
+     * ```typescript
+     * const txId = await ManualAuditLogService.beginTransaction('user-123', 'John Doe');
+     *
+     * await ManualAuditLogService.log({
+     *   templateKey: 'order.create',
+     *   descriptionParams: { orderId: 'order-1' },
+     *   transactionId: txId,
+     *   autoCreateTransaction: false,
+     * });
+     *
+     * await ManualAuditLogService.log({
+     *   templateKey: 'payment.process',
+     *   descriptionParams: { paymentId: 'pay-1' },
+     *   transactionId: txId,
+     *   autoCreateTransaction: false,
+     * });
+     *
+     * await ManualAuditLogService.commitTransaction(txId);
+     * ```
+     */
     static beginTransaction(userId, username) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
@@ -86,6 +177,9 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             return ManualAuditLogService_1.instance.createTransaction(userId, username);
         });
     }
+    /**
+     * 静态方法：提交事务
+     */
     static commitTransaction(transactionId) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
@@ -94,6 +188,9 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             yield ManualAuditLogService_1.instance.updateTransactionStatus(transactionId, enums_1.TransactionStatus.COMMITTED);
         });
     }
+    /**
+     * 静态方法：回滚事务
+     */
     static rollbackTransaction(transactionId) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
@@ -102,6 +199,9 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             yield ManualAuditLogService_1.instance.updateTransactionStatus(transactionId, enums_1.TransactionStatus.ROLLED_BACK);
         });
     }
+    /**
+     * 创建事务
+     */
     createTransaction(userId, username) {
         return __awaiter(this, void 0, void 0, function* () {
             const context = yield this.contextService.getCurrentContext();
@@ -117,19 +217,53 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
             return saved.id;
         });
     }
+    /**
+     * 更新事务状态
+     */
     updateTransactionStatus(transactionId, status) {
         return __awaiter(this, void 0, void 0, function* () {
             yield this.transactionRepository.update({ id: transactionId }, { status });
         });
     }
+    /**
+     * 生成事务ID
+     */
     generateTransactionId() {
         return `txn-${Date.now()}-${(0, crypto_1.randomBytes)(8).toString('hex')}`;
     }
+    /**
+     * 批量记录操作日志
+     *
+     * @description
+     * 批量记录多个操作，支持所有三种记录模式
+     *
+     * @example
+     * ```typescript
+     * // 混合使用多种模式
+     * await ManualAuditLogService.logBatch([
+     *   {
+     *     templateKey: 'product.update',
+     *     descriptionParams: { productId: 'p1', field: 'price' },
+     *   },
+     *   {
+     *     description: '批量更新库存',
+     *   },
+     *   {
+     *     descriptionTemplate: {
+     *       zh: '更新产品 {productId} 的 {field}',
+     *       en: 'Update {field} of product {productId}',
+     *     },
+     *     descriptionParams: { productId: 'p3', field: 'stock' },
+     *   },
+     * ]);
+     * ```
+     */
     static logBatch(operations, sharedTransactionId) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {
                 throw new Error('ManualAuditLogService is not initialized');
             }
+            // 创建共享事务ID
             const transactionId = sharedTransactionId ||
                 (yield ManualAuditLogService_1.instance.createTransaction());
             const results = [];
@@ -137,12 +271,16 @@ let ManualAuditLogService = ManualAuditLogService_1 = class ManualAuditLogServic
                 const result = yield ManualAuditLogService_1.instance.logOperation(Object.assign(Object.assign({}, operation), { transactionId, autoCreateTransaction: false }));
                 results.push(result);
             }
+            // 自动提交事务（如果是自动创建的）
             if (!sharedTransactionId) {
                 yield ManualAuditLogService_1.instance.updateTransactionStatus(transactionId, enums_1.TransactionStatus.COMMITTED);
             }
             return results;
         });
     }
+    /**
+     * 查询操作日志
+     */
     static findLogs(options) {
         return __awaiter(this, void 0, void 0, function* () {
             if (!ManualAuditLogService_1.instance) {

package/audit/services/multi-database.service.d.ts

@@ -1,10 +1,22 @@
 import { DataSource } from 'typeorm';
 import { ModuleRef } from '@nestjs/core';
+/**
+ * 多数据库连接管理服务
+ */
 export declare class MultiDatabaseService {
     private readonly moduleRef;
     private readonly config?;
     constructor(moduleRef: ModuleRef, config?: any);
+    /**
+     * 获取指定连接的 DataSource
+     */
     getDataSource(connectionName?: string): Promise<DataSource>;
+    /**
+     * 获取所有监听的数据库连接
+     */
     getMonitoredConnections(): string[];
+    /**
+     * 获取审计日志存储的数据库连接
+     */
     getAuditConnection(): string;
 }

package/audit/services/multi-database.service.js

@@ -25,11 +25,17 @@ exports.MultiDatabaseService = void 0;
 const common_1 = require("@nestjs/common");
 const typeorm_1 = require("@nestjs/typeorm");
 const core_1 = require("@nestjs/core");
+/**
+ * 多数据库连接管理服务
+ */
 let MultiDatabaseService = class MultiDatabaseService {
     constructor(moduleRef, config) {
         this.moduleRef = moduleRef;
         this.config = config;
     }
+    /**
+     * 获取指定连接的 DataSource
+     */
     getDataSource() {
         return __awaiter(this, arguments, void 0, function* (connectionName = 'default') {
             try {
@@ -41,10 +47,16 @@ let MultiDatabaseService = class MultiDatabaseService {
             }
         });
     }
+    /**
+     * 获取所有监听的数据库连接
+     */
     getMonitoredConnections() {
         var _a, _b;
         return ((_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.connections) === null || _b === void 0 ? void 0 : _b.monitored) || ['default'];
     }
+    /**
+     * 获取审计日志存储的数据库连接
+     */
     getAuditConnection() {
         var _a, _b;
         return ((_b = (_a = this.config) === null || _a === void 0 ? void 0 : _a.connections) === null || _b === void 0 ? void 0 : _b.audit) || 'default';

package/audit/services/operation-description.service.d.ts

@@ -1,6 +1,10 @@
 import { Repository } from 'typeorm';
 import { OperationTemplateEntity, EntityTransactionEntity, EntityAuditLogEntity, ManualOperationLogEntity } from '../entities';
 import { ChangeDetail, TransactionDescription } from '../interfaces';
+/**
+ * 操作描述服务
+ * 负责根据模板和参数动态生成多语言描述
+ */
 export declare class OperationDescriptionService {
     private readonly templateRepository;
     private readonly transactionRepository;
@@ -8,14 +12,69 @@ export declare class OperationDescriptionService {
     private readonly manualOperationRepository;
     private templateCache;
     constructor(templateRepository: Repository<OperationTemplateEntity>, transactionRepository: Repository<EntityTransactionEntity>, auditLogRepository: Repository<EntityAuditLogEntity>, manualOperationRepository: Repository<ManualOperationLogEntity>);
+    /**
+     * 动态生成操作名称
+     * @param templateKey 模板键
+     * @param language 语言
+     * @returns 操作名称
+     */
     generateOperationName(templateKey: string, language?: string): Promise<string>;
+    /**
+     * 动态生成操作描述
+     * @param templateKey 模板键
+     * @param descriptionParams 描述参数
+     * @param language 语言
+     * @returns 描述文本
+     */
     generateDescription(templateKey: string, descriptionParams: Record<string, any>, language?: string): Promise<string>;
+    /**
+     * 动态生成变更详情
+     * @param changeDetails 变更详情列表
+     * @param language 语言
+     * @returns 格式化的变更详情
+     */
     generateChangeDetails(changeDetails: ChangeDetail[], language?: string): Promise<any[]>;
+    /**
+     * 获取事务描述（包含所有变更）
+     * @param transactionId 事务ID
+     * @param language 语言
+     * @returns 事务描述对象
+     */
     getTransactionDescription(transactionId: string, language?: string): Promise<TransactionDescription>;
+    /**
+     * 批量获取事务描述
+     * @param transactionIds 事务ID列表
+     * @param language 语言
+     * @returns 事务描述映射
+     */
     batchGetTransactionDescriptions(transactionIds: string[], language?: string): Promise<Record<string, TransactionDescription>>;
+    /**
+     * 填充模板
+     * @param template 模板字符串
+     * @param params 参数
+     * @returns 填充后的字符串
+     */
     private fillTemplate;
+    /**
+     * 格式化显示值
+     * @param value 原始值
+     * @param displayValue 显示值
+     * @returns 格式化后的值
+     */
     private formatDisplayValue;
+    /**
+     * 获取操作模板（带缓存）
+     * @param templateKey 模板键
+     * @returns 操作模板
+     */
     private getOperationTemplate;
+    /**
+     * 清除模板缓存
+     */
     clearTemplateCache(): void;
+    /**
+     * 预加载模板到缓存
+     * @param templateKeys 模板键列表
+     */
     preloadTemplates(templateKeys: string[]): Promise<void>;
 }