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

package/audit/subscribers/entity-audit.subscriber.js

@@ -26,6 +26,9 @@ const audit_context_service_1 = require("../services/audit-context.service");
 const audit_strategy_service_1 = require("../services/audit-strategy.service");
 const enums_1 = require("../enums");
 const decorators_1 = require("../decorators");
+/**
+ * 实体审计订阅者
+ */
 let EntityAuditSubscriber = class EntityAuditSubscriber {
     constructor(entityAuditService, contextService, auditStrategy, dataSource) {
         this.entityAuditService = entityAuditService;
@@ -33,6 +36,9 @@ let EntityAuditSubscriber = class EntityAuditSubscriber {
         this.auditStrategy = auditStrategy;
         dataSource.subscribers.push(this);
     }
+    /**
+     * 在实体插入后记录审计日志
+     */
     afterInsert(event) {
         return __awaiter(this, void 0, void 0, function* () {
             const entity = event.entity;
@@ -40,18 +46,32 @@ let EntityAuditSubscriber = class EntityAuditSubscriber {
                 return;
             const entityType = entity.constructor.name;
             const entityId = entity.id;
+            // 检查是否启用了审计
             if (!this.isAuditEnabled(entity)) {
                 return;
             }
+            // 检查策略
             if (!this.auditStrategy.shouldRecord(entityType, enums_1.AuditOperation.CREATE)) {
                 return;
             }
             try {
+                // 获取上下文信息
                 const context = yield this.contextService.getCurrentContext();
+                const actionContext = this.contextService.getCurrentActionContext();
+                // 记录到审计动作上下文
+                if (actionContext) {
+                    this.contextService.recordEntityChangeInAction(entityType, entityId, enums_1.AuditOperation.CREATE);
+                    // 记录详细的实体变更数据
+                    this.contextService.recordDetailedEntityChange(entityType, entityId, enums_1.AuditOperation.CREATE, {}, entity, Object.keys(entity));
+                }
+                // 记录审计日志
                 yield this.entityAuditService.logEntityChange(entityType, entityId, enums_1.AuditOperation.CREATE, {}, entity, {
                     requestId: context.requestId,
                     requestIp: context.requestIp,
                     userAgent: context.userAgent,
+                    auditActionId: actionContext === null || actionContext === void 0 ? void 0 : actionContext.actionId,
+                    auditActionName: actionContext === null || actionContext === void 0 ? void 0 : actionContext.actionName,
+                    sequenceInAction: (actionContext === null || actionContext === void 0 ? void 0 : actionContext.entityChanges.length) || 0,
                 });
             }
             catch (error) {
@@ -59,6 +79,9 @@ let EntityAuditSubscriber = class EntityAuditSubscriber {
             }
         });
     }
+    /**
+     * 在实体更新后记录审计日志
+     */
     afterUpdate(event) {
         return __awaiter(this, void 0, void 0, function* () {
             const entity = event.entity;
@@ -67,18 +90,33 @@ let EntityAuditSubscriber = class EntityAuditSubscriber {
                 return;
             const entityType = entity.constructor.name;
             const entityId = entity.id;
+            // 检查是否启用了审计
             if (!this.isAuditEnabled(entity)) {
                 return;
             }
+            // 检查策略
             if (!this.auditStrategy.shouldRecord(entityType, enums_1.AuditOperation.UPDATE)) {
                 return;
             }
             try {
+                // 获取上下文信息
                 const context = yield this.contextService.getCurrentContext();
+                const actionContext = this.contextService.getCurrentActionContext();
+                // 记录到审计动作上下文
+                if (actionContext) {
+                    this.contextService.recordEntityChangeInAction(entityType, entityId, enums_1.AuditOperation.UPDATE);
+                    // 记录详细的实体变更数据
+                    const changedFields = this.calculateChangedFields(databaseEntity || {}, entity);
+                    this.contextService.recordDetailedEntityChange(entityType, entityId, enums_1.AuditOperation.UPDATE, databaseEntity || {}, entity, changedFields);
+                }
+                // 记录审计日志
                 yield this.entityAuditService.logEntityChange(entityType, entityId, enums_1.AuditOperation.UPDATE, databaseEntity || {}, entity, {
                     requestId: context.requestId,
                     requestIp: context.requestIp,
                     userAgent: context.userAgent,
+                    auditActionId: actionContext === null || actionContext === void 0 ? void 0 : actionContext.actionId,
+                    auditActionName: actionContext === null || actionContext === void 0 ? void 0 : actionContext.actionName,
+                    sequenceInAction: (actionContext === null || actionContext === void 0 ? void 0 : actionContext.entityChanges.length) || 0,
                 });
             }
             catch (error) {
@@ -86,6 +124,9 @@ let EntityAuditSubscriber = class EntityAuditSubscriber {
             }
         });
     }
+    /**
+     * 在实体删除前记录审计日志
+     */
     beforeRemove(event) {
         return __awaiter(this, void 0, void 0, function* () {
             const entity = event.entity;
@@ -93,18 +134,32 @@ let EntityAuditSubscriber = class EntityAuditSubscriber {
                 return;
             const entityType = entity.constructor.name;
             const entityId = entity.id;
+            // 检查是否启用了审计
             if (!this.isAuditEnabled(entity)) {
                 return;
             }
+            // 检查策略
             if (!this.auditStrategy.shouldRecord(entityType, enums_1.AuditOperation.DELETE)) {
                 return;
             }
             try {
+                // 获取上下文信息
                 const context = yield this.contextService.getCurrentContext();
+                const actionContext = this.contextService.getCurrentActionContext();
+                // 记录到审计动作上下文
+                if (actionContext) {
+                    this.contextService.recordEntityChangeInAction(entityType, entityId, enums_1.AuditOperation.DELETE);
+                    // 记录详细的实体变更数据
+                    this.contextService.recordDetailedEntityChange(entityType, entityId, enums_1.AuditOperation.DELETE, entity, {}, Object.keys(entity));
+                }
+                // 记录审计日志
                 yield this.entityAuditService.logEntityChange(entityType, entityId, enums_1.AuditOperation.DELETE, entity, {}, {
                     requestId: context.requestId,
                     requestIp: context.requestIp,
                     userAgent: context.userAgent,
+                    auditActionId: actionContext === null || actionContext === void 0 ? void 0 : actionContext.actionId,
+                    auditActionName: actionContext === null || actionContext === void 0 ? void 0 : actionContext.actionName,
+                    sequenceInAction: (actionContext === null || actionContext === void 0 ? void 0 : actionContext.entityChanges.length) || 0,
                 });
             }
             catch (error) {
@@ -112,8 +167,28 @@ let EntityAuditSubscriber = class EntityAuditSubscriber {
             }
         });
     }
+    /**
+     * 计算变更字段
+     */
+    calculateChangedFields(oldValue, newValue) {
+        const changedFields = [];
+        const allKeys = new Set([
+            ...Object.keys(oldValue || {}),
+            ...Object.keys(newValue || {}),
+        ]);
+        for (const key of allKeys) {
+            if (JSON.stringify(oldValue[key]) !== JSON.stringify(newValue[key])) {
+                changedFields.push(key);
+            }
+        }
+        return changedFields;
+    }
+    /**
+     * 检查是否启用了审计
+     */
     isAuditEnabled(entity) {
         try {
+            // 检查装饰器
             const auditOptions = Reflect.getMetadata(decorators_1.ENTITY_AUDIT_OPTIONS, entity.constructor);
             if (auditOptions && auditOptions.enabled === false) {
                 return false;
@@ -121,7 +196,7 @@ let EntityAuditSubscriber = class EntityAuditSubscriber {
             return true;
         }
         catch (error) {
-            return true;
+            return true; // 默认启用
         }
     }
 };

package/cache/cache-metrics.service.d.ts

@@ -1,4 +1,7 @@
 import { EventEmitter } from 'events';
+/**
+ * Individual cache operation record
+ */
 export interface CacheOperationRecord {
     type: 'get' | 'set' | 'delete' | 'clear';
     layer: string;
@@ -8,24 +11,34 @@ export interface CacheOperationRecord {
     key?: string;
     timestamp: Date;
 }
+/**
+ * Cache operation metrics
+ */
 export interface CacheMetrics {
+    /** Total number of operations */
     totalOperations: number;
+    /** Hit/miss statistics */
     hits: number;
     misses: number;
     hitRate: number;
+    /** Latency metrics (ms) */
     avgLatency: number;
     minLatency: number;
     maxLatency: number;
     p95Latency: number;
     p99Latency: number;
+    /** Operation counts by type */
     gets: number;
     sets: number;
     deletes: number;
     clears: number;
+    /** Size metrics */
     totalKeys: number;
     totalSize: number;
+    /** Error metrics */
     errors: number;
     errorRate: number;
+    /** Layer-specific metrics */
     layerMetrics: {
         cls: {
             hits: number;
@@ -44,40 +57,94 @@ export interface CacheMetrics {
             avgLatency: number;
         };
     };
+    /** Time window for these metrics */
     timeWindow: {
         start: Date;
         end: Date;
         duration: number;
     };
 }
+/**
+ * Cache metrics service
+ *
+ * Collects and analyzes cache performance metrics
+ */
 export declare class CacheMetricsService extends EventEmitter {
     private readonly logger;
     private readonly operations;
     private readonly maxOperations;
     private readonly maxAge;
     constructor();
+    /**
+     * Record a cache operation
+     */
     recordOperation(type: 'get' | 'set' | 'delete' | 'clear', layer: string, hit: boolean, latency: number, error?: string, key?: string): void;
+    /**
+     * Get metrics for a time window
+     */
     getMetrics(timeWindowMs?: number): CacheMetrics;
+    /**
+     * Get real-time metrics snapshot
+     */
     getSnapshot(): Partial<CacheMetrics>;
+    /**
+     * Get top slow operations
+     */
     getSlowOperations(limit?: number): CacheOperationRecord[];
+    /**
+     * Get most accessed keys
+     */
     getMostAccessedKeys(limit?: number): {
         key: string;
         count: number;
         avgLatency: number;
     }[];
+    /**
+     * Get error breakdown
+     */
     getErrorBreakdown(): {
         error: string;
         count: number;
         lastOccurrence: Date;
     }[];
+    /**
+     * Reset all metrics
+     */
     resetMetrics(): void;
+    /**
+     * Export metrics for external monitoring systems
+     */
     exportMetrics(format?: 'prometheus' | 'json'): string;
+    /**
+     * Clean up old operation records
+     */
     private cleanupOldRecords;
+    /**
+     * Create empty metrics object
+     */
     private createEmptyMetrics;
+    /**
+     * Calculate layer-specific metrics
+     */
     private calculateLayerMetrics;
+    /**
+     * Calculate average of array
+     */
     private average;
+    /**
+     * Calculate percentile
+     */
     private percentile;
+    /**
+     * Get unique key count
+     */
     private getUniqueKeyCount;
+    /**
+     * Estimate total cache size
+     */
     private estimateTotalSize;
+    /**
+     * Convert metrics to Prometheus format
+     */
     private toPrometheusFormat;
 }

package/cache/cache-metrics.service.js

@@ -13,15 +13,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.CacheMetricsService = void 0;
 const common_1 = require("@nestjs/common");
 const events_1 = require("events");
+/**
+ * Cache metrics service
+ *
+ * Collects and analyzes cache performance metrics
+ */
 let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService extends events_1.EventEmitter {
     constructor() {
         super();
         this.logger = new common_1.Logger(CacheMetricsService_1.name);
         this.operations = [];
-        this.maxOperations = 10000;
-        this.maxAge = 3600000;
-        setInterval(() => this.cleanupOldRecords(), 60000);
+        this.maxOperations = 10000; // Keep last 10k operations
+        this.maxAge = 3600000; // 1 hour
+        // Clean up old records periodically
+        setInterval(() => this.cleanupOldRecords(), 60000); // Every minute
     }
+    /**
+     * Record a cache operation
+     */
     recordOperation(type, layer, hit, latency, error, key) {
         const record = {
             type,
@@ -33,14 +42,20 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
             timestamp: new Date(),
         };
         this.operations.push(record);
+        // Maintain maximum operations limit
         if (this.operations.length > this.maxOperations) {
             this.operations.splice(0, this.operations.length - this.maxOperations);
         }
+        // Emit event for real-time monitoring
         this.emit('operation', record);
+        // Log errors
         if (error) {
             this.logger.warn(`Cache operation error: ${type} on ${layer} - ${error}`);
         }
     }
+    /**
+     * Get metrics for a time window
+     */
     getMetrics(timeWindowMs = 300000) {
         const endTime = new Date();
         const startTime = new Date(endTime.getTime() - timeWindowMs);
@@ -58,6 +73,7 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
         const sets = recentOperations.filter((op) => op.type === 'set').length;
         const deletes = recentOperations.filter((op) => op.type === 'delete').length;
         const clears = recentOperations.filter((op) => op.type === 'clear').length;
+        // Calculate layer-specific metrics
         const layerOperations = {
             cls: recentOperations.filter((op) => op.layer === 'cls'),
             memory: recentOperations.filter((op) => op.layer === 'memory'),
@@ -94,6 +110,9 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
             },
         };
     }
+    /**
+     * Get real-time metrics snapshot
+     */
     getSnapshot() {
         const now = new Date();
         const oneMinuteAgo = new Date(now.getTime() - 60000);
@@ -124,12 +143,18 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
             errorRate: errors / recentOperations.length,
         };
     }
+    /**
+     * Get top slow operations
+     */
     getSlowOperations(limit = 10) {
         return this.operations
             .filter((op) => op.error === undefined)
             .sort((a, b) => b.latency - a.latency)
             .slice(0, limit);
     }
+    /**
+     * Get most accessed keys
+     */
     getMostAccessedKeys(limit = 10) {
         const keyStats = new Map();
         this.operations.forEach((op) => {
@@ -149,6 +174,9 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
             .sort((a, b) => b.count - a.count)
             .slice(0, limit);
     }
+    /**
+     * Get error breakdown
+     */
     getErrorBreakdown() {
         const errorStats = new Map();
         this.operations.forEach((op) => {
@@ -173,11 +201,17 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
         }))
             .sort((a, b) => b.count - a.count);
     }
+    /**
+     * Reset all metrics
+     */
     resetMetrics() {
         this.operations.length = 0;
         this.logger.log('Cache metrics reset');
         this.emit('reset');
     }
+    /**
+     * Export metrics for external monitoring systems
+     */
     exportMetrics(format = 'json') {
         const metrics = this.getMetrics();
         if (format === 'prometheus') {
@@ -185,9 +219,13 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
         }
         return JSON.stringify(metrics, null, 2);
     }
+    /**
+     * Clean up old operation records
+     */
     cleanupOldRecords() {
         const cutoff = new Date(Date.now() - this.maxAge);
         const initialLength = this.operations.length;
+        // Remove old records
         for (let i = this.operations.length - 1; i >= 0; i--) {
             if (this.operations[i].timestamp < cutoff) {
                 this.operations.splice(0, i + 1);
@@ -199,6 +237,9 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
             this.logger.debug(`Cleaned up ${removed} old cache operation records`);
         }
     }
+    /**
+     * Create empty metrics object
+     */
     createEmptyMetrics(start, end) {
         return {
             totalOperations: 0,
@@ -230,6 +271,9 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
             },
         };
     }
+    /**
+     * Calculate layer-specific metrics
+     */
     calculateLayerMetrics(operations) {
         const hits = operations.filter((op) => op.hit).length;
         const misses = operations.filter((op) => !op.hit).length;
@@ -238,20 +282,29 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
             hits,
             misses,
             avgLatency: latencies.length > 0 ? this.average(latencies) : 0,
-            size: operations.length,
+            size: operations.length, // Approximation
         };
     }
+    /**
+     * Calculate average of array
+     */
     average(numbers) {
         return numbers.length > 0
             ? numbers.reduce((sum, num) => sum + num, 0) / numbers.length
             : 0;
     }
+    /**
+     * Calculate percentile
+     */
     percentile(sortedNumbers, p) {
         if (sortedNumbers.length === 0)
             return 0;
         const index = Math.ceil(sortedNumbers.length * p) - 1;
         return sortedNumbers[Math.max(0, Math.min(index, sortedNumbers.length - 1))];
     }
+    /**
+     * Get unique key count
+     */
     getUniqueKeyCount(operations) {
         const keys = new Set();
         operations.forEach((op) => {
@@ -260,29 +313,40 @@ let CacheMetricsService = CacheMetricsService_1 = class CacheMetricsService exte
         });
         return keys.size;
     }
+    /**
+     * Estimate total cache size
+     */
     estimateTotalSize(operations) {
+        // Rough estimation: average key size (20 bytes) + average value size (100 bytes)
         const avgValueSize = 120;
         return this.getUniqueKeyCount(operations) * avgValueSize;
     }
+    /**
+     * Convert metrics to Prometheus format
+     */
     toPrometheusFormat(metrics) {
         const labels = {
             layer: 'cls|memory|redis',
         };
         let output = '';
+        // Hit rate
         output += `# HELP cache_hit_rate Cache hit rate\n`;
         output += `# TYPE cache_hit_rate gauge\n`;
         output += `cache_hit_rate ${metrics.hitRate}\n`;
+        // Operations
         output += `# HELP cache_operations_total Total cache operations\n`;
         output += `# TYPE cache_operations_total counter\n`;
         output += `cache_operations_total{type="get"} ${metrics.gets}\n`;
         output += `cache_operations_total{type="set"} ${metrics.sets}\n`;
         output += `cache_operations_total{type="delete"} ${metrics.deletes}\n`;
         output += `cache_operations_total{type="clear"} ${metrics.clears}\n`;
+        // Latency
         output += `# HELP cache_latency_ms Cache operation latency\n`;
         output += `# TYPE cache_latency_ms histogram\n`;
         output += `cache_latency_ms{quantile="0.5"} ${metrics.avgLatency}\n`;
         output += `cache_latency_ms{quantile="0.95"} ${metrics.p95Latency}\n`;
         output += `cache_latency_ms{quantile="0.99"} ${metrics.p99Latency}\n`;
+        // Layer metrics
         Object.entries(metrics.layerMetrics).forEach(([layer, layerMetrics]) => {
             output += `cache_layer_hits_total{layer="${layer}"} ${layerMetrics.hits}\n`;
             output += `cache_layer_misses_total{layer="${layer}"} ${layerMetrics.misses}\n`;

package/cache/cache-serialization.service.d.ts

@@ -1,22 +1,53 @@
+/**
+ * Cache serialization options
+ */
 export interface CacheSerializationOptions {
+    /** Whether to compress large values */
     compress?: boolean;
+    /** Compression threshold (bytes) */
     compressThreshold?: number;
 }
+/**
+ * Serialization result
+ */
 export interface SerializationResult {
     data: Buffer;
     compressed: boolean;
     originalSize: number;
     serializedSize: number;
 }
+/**
+ * Deserialization result
+ */
 export interface DeserializationResult<T> {
     data: T;
     wasCompressed: boolean;
 }
+/**
+ * Simple cache serialization service
+ *
+ * Handles basic data compression for cache values
+ */
 export declare class CacheSerializationService {
     private readonly logger;
+    /**
+     * Serialize and optionally compress cache value
+     */
     serialize<T>(value: T, options?: CacheSerializationOptions): Promise<SerializationResult>;
+    /**
+     * Deserialize and decompress cache value
+     */
     deserialize<T>(buffer: Buffer): Promise<DeserializationResult<T>>;
+    /**
+     * Serialize value with proper Date handling
+     */
     private serializeWithDates;
+    /**
+     * Pre-process object to convert Date objects to serializable format
+     */
     private preProcessDates;
+    /**
+     * Deserialize value with proper Date restoration
+     */
     private deserializeWithDates;
 }

package/cache/cache-serialization.service.js

@@ -22,18 +22,28 @@ const zlib_1 = require("zlib");
 const util_1 = require("util");
 const gzipAsync = (0, util_1.promisify)(zlib_1.gzip);
 const gunzipAsync = (0, util_1.promisify)(zlib_1.gunzip);
+/**
+ * Simple cache serialization service
+ *
+ * Handles basic data compression for cache values
+ */
 let CacheSerializationService = CacheSerializationService_1 = class CacheSerializationService {
     constructor() {
         this.logger = new common_1.Logger(CacheSerializationService_1.name);
     }
+    /**
+     * Serialize and optionally compress cache value
+     */
     serialize(value_1) {
         return __awaiter(this, arguments, void 0, function* (value, options = {}) {
             const { compress = false, compressThreshold = 1024 } = options;
             try {
+                // Serialize the value with date handling
                 const serialized = this.serializeWithDates(value);
                 const originalSize = Buffer.byteLength(serialized, 'utf8');
                 let data;
                 let wasCompressed = false;
+                // Compress if enabled and data is large enough
                 if (compress && originalSize >= compressThreshold) {
                     try {
                         data = yield gzipAsync(Buffer.from(serialized, 'utf8'));
@@ -60,12 +70,17 @@ let CacheSerializationService = CacheSerializationService_1 = class CacheSeriali
             }
         });
     }
+    /**
+     * Deserialize and decompress cache value
+     */
     deserialize(buffer) {
         return __awaiter(this, void 0, void 0, function* () {
             try {
                 let dataString;
                 let wasCompressed = false;
+                // Try to detect if data is compressed
                 if (buffer.length >= 2 && buffer[0] === 0x1f && buffer[1] === 0x8b) {
+                    // Gzip magic numbers
                     dataString = (yield gunzipAsync(buffer)).toString('utf8');
                     wasCompressed = true;
                 }
@@ -84,10 +99,17 @@ let CacheSerializationService = CacheSerializationService_1 = class CacheSeriali
             }
         });
     }
+    /**
+     * Serialize value with proper Date handling
+     */
     serializeWithDates(value) {
+        // Pre-process the value to handle Date objects
         const processed = this.preProcessDates(value);
         return JSON.stringify(processed);
     }
+    /**
+     * Pre-process object to convert Date objects to serializable format
+     */
     preProcessDates(obj) {
         if (obj === null || obj === undefined) {
             return obj;
@@ -107,6 +129,9 @@ let CacheSerializationService = CacheSerializationService_1 = class CacheSeriali
         }
         return obj;
     }
+    /**
+     * Deserialize value with proper Date restoration
+     */
     deserializeWithDates(dataString) {
         return JSON.parse(dataString, (key, val) => {
             if (val && typeof val === 'object' && val.__type === 'Date') {

package/cache/cache.constants.d.ts

@@ -1,2 +1,11 @@
+/**
+ * Cache constants and injection tokens
+ */
+/**
+ * Injection token for cache compression enabled flag
+ */
 export declare const CACHE_COMPRESSION_ENABLED: unique symbol;
+/**
+ * Injection token for cache compression threshold
+ */
 export declare const CACHE_COMPRESSION_THRESHOLD: unique symbol;

package/cache/cache.constants.js

@@ -1,5 +1,14 @@
 "use strict";
+/**
+ * Cache constants and injection tokens
+ */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CACHE_COMPRESSION_THRESHOLD = exports.CACHE_COMPRESSION_ENABLED = void 0;
+/**
+ * Injection token for cache compression enabled flag
+ */
 exports.CACHE_COMPRESSION_ENABLED = Symbol('CACHE_COMPRESSION_ENABLED');
+/**
+ * Injection token for cache compression threshold
+ */
 exports.CACHE_COMPRESSION_THRESHOLD = Symbol('CACHE_COMPRESSION_THRESHOLD');