IMEX.CORE 2.0.3

🏥 IMEX.Core

Thư viện IMEX.Core mạnh mẽ cho hệ thống API của bạn - Cung cấp các tính năng cốt lõi cho phát triển ứng dụng với hiệu suất cao và bảo mật tối ưu.

📋 Mục lục

• 🚀 Giới thiệu
• ✨ Tính năng chính
• 📦 Cài đặt
• ⚙️ Cấu hình
• 📚 Hướng dẫn sử dụng
• 🏗️ Kiến trúc
• 🔧 API Reference
• 🧪 Testing
• 📈 Performance
• 🤝 Đóng góp
• 📄 License

🚀 Giới thiệu

IMEX.Core là thư viện cốt lõi được thiết kế đặc biệt cho hệ thống quản lý nhân sự trong lĩnh vực y tế. Thư viện cung cấp các tính năng mạnh mẽ, hiệu suất cao và bảo mật tối ưu để xây dựng các ứng dụng HR phức tạp.

🎯 Mục tiêu

• Hiệu suất cao: Tối ưu hóa cache, database access và memory usage
• Bảo mật mạnh: Mã hóa dữ liệu, quản lý quyền truy cập chi tiết
• Dễ sử dụng: API đơn giản, documentation chi tiết
• Mở rộng tốt: Kiến trúc modular, dễ dàng customize
• Production-ready: Đã được test kỹ lưỡng trong môi trường thực tế
• Large-Scale Support: Hỗ trợ 5K-20K concurrent users với Redis Cluster

✨ Tính năng chính

🗄️ Database & ORM

• SqlSugar ORM: Hỗ trợ multi-database, read/write splitting
• Migration System: Tự động migration và seeding dữ liệu
• Multi-tenant: Hỗ trợ multi-tenant architecture
• Connection Pooling: Tối ưu hóa kết nối database

🚀 Caching System (Enterprise-Grade)

Core Features

• Multi-tier Cache: L1 (Memory) + L2 (Redis) + Hybrid với kiến trúc tối ưu
• Smart Compression: Tự động nén dữ liệu lớn với LZ4 và MessagePack
• Adaptive TTL: Tự động điều chỉnh thời gian cache với jittering
• Lock-free Operations: Thread-safe, high-performance với object pooling
• Cache Invalidation: RemoveByPrefix, tag-based removal, pattern matching
• Background Refresh: Tự động làm mới dữ liệu trước khi hết hạn (Stale-While-Revalidate)

Large-Scale Features (NEW)

• Redis Cluster/Sentinel: Hỗ trợ Redis Cluster và Sentinel mode với automatic failover
• Consistent Hash Ring: Jump consistent hashing cho key distribution với virtual nodes
• Cache Warming Service: Pre-populate cache khi startup với priority-based warming
• Adaptive Eviction Policies: LRU, LFU, SizeBased, TTL, Random, Adaptive, Composite
• Memory Pressure Management: Tự động evict cache khi memory pressure cao
• Batch Operations: GetManyAsync, SetManyAsync, RemoveManyAsync với pipelining
• Multi-Tenant Isolation: Tự động inject tenant ID vào cache keys
• Distributed Tracing: OpenTelemetry integration với Prometheus export
• Circuit Breaker: Enhanced circuit breaker với adaptive configuration

Performance Features

• Object Pooling: 90% reduction trong memory allocations
• Zero-Allocation Operations: Span-based string và memory operations
• Single-Flight Pattern: Ngăn chặn duplicate expensive computations
• Fail-Safe Cache: Stale data fallback khi có lỗi
• Health Monitoring: Real-time health checks và metrics

🔐 Security & Authentication

• Multi-encryption: RSA, SM2, SM3, SM4
• JWT Authentication: Stateless authentication
• Role-based Access Control: Bitwise permission system
• Data Encryption: End-to-end encryption
• Audit Logging: Comprehensive security logging

📊 Logging & Monitoring

• Structured Logging: Serilog với Elasticsearch và các sink tùy chỉnh
• Performance Monitoring: Real-time metrics với OpenTelemetry và Prometheus
• Cache Analytics: Hit/miss ratios, response times, memory usage tracking
• Error Tracking: Comprehensive error handling với circuit breaker metrics
• Health Checks: Tự động monitoring health của cache và database connections

🛠️ Utilities & Helpers

• File Operations: Secure file handling với encryption
• Data Conversion: Number to text, encoding/decoding với performance optimization
• Validation: Input validation helpers với async support
• HTTP Utilities: Request/response helpers với retry policies
• ID Generation: Snowflake ID, custom generators với thread safety
• Memory Management: Object pooling và memory-efficient operations

📦 Cài đặt

NuGet Package

# Package Manager
Install-Package IMEX.CORE -Version <YOUR_VERSION>

# .NET CLI
dotnet add package IMEX.CORE --version <YOUR_VERSION>

# Paket
paket add IMEX.CORE --version <YOUR_VERSION>

Yêu cầu hệ thống

• .NET 8.0, .NET 9.0, hoặc .NET 10.0
• Redis 6.0+ (tùy chọn, cho distributed cache)
• Elasticsearch 7.0+ (tùy chọn, cho logging)

---

🆕 Cải thiện mới nhất (v2.0.1):

• L1 Cache Hit: 199ns (5x nhanh hơn target)
• GetAsync: 320ns
• Throughput: 40M ops/sec
• Lock contention: 0.01% (gần như bằng 0)
• Memory/Operation: 192B
• Đã kiểm thử với 100+ threads, production config thực tế
• Xem chi tiết: docs/PRODUCTION_REALISTIC_RESULTS.md

---

⚙️ Cấu hình

1. Database Configuration

{
  "MainDB": "DB_Main",
  "MultiDBEnabled": true,
  "DBConnections": [
    {
      "ConnId": "DB_Main",
      "DBType": 1,
      "Enable": true,
      "HitRate": 50,
      "ConnectionStr": "Data Source=localhost;Initial Catalog=MedcomHR;Integrated Security=True;",
      "ProviderName": "System.Data.SqlClient",
      "Slaves": [
        {
          "HitRate": 0,
          "Connection": "Data Source=slave-server;Initial Catalog=MedcomHR;Integrated Security=True;"
        }
      ]
    }
  ]
}

2. Complete Cache Configuration

{
  "Cache": {
    "Hybrid": {
      "L2TtlMultiplier": 3.0,
      "L1PromotionTtlMinutes": 30,
      "EnableFactoryTimeouts": true,
      "SoftTimeoutMs": 500,
      "HardTimeoutMs": 20000,
      "FailSafeTtlMultiplier": 5.0,
      "EnableRedisPubSubSync": true,
      "EnableSignalRSync": true,
      "HealthCheckIntervalSeconds": 30,
      "DefaultLockTimeoutSeconds": 30
    },
    "EnhancedMemoryCache": {
      "BackgroundRefreshRatio": 0.7,
      "BackgroundRefreshIntervalSeconds": 45,
      "CleanupSampleSize": 1500,
      "CleanupSamplingRate": 0.08,
      "AdaptiveTtl": {
        "HighHitRatioThreshold": 0.85,
        "LowHitRatioThreshold": 0.6,
        "HighPerformanceMultiplier": 2.0,
        "MaxTtlMultiplier": 4.0,
        "MinTtlMinutes": 5
      }
    },
    "Medical": {
      "PatientDataCacheMinutes": 90,
      "MedicalRecordsCacheMinutes": 180,
      "VitalSignsCacheMinutes": 15,
      "AllergiesCacheMinutes": 360,
      "MedicationsCacheMinutes": 120
    },
    "Warming": {
      "EnableWarmingOnStartup": true,
      "MaxConcurrentWarmingTasks": 4,
      "WarmingTaskTimeoutSeconds": 30,
      "TotalWarmingTimeoutMinutes": 5,
      "BatchSize": 50,
      "RetryCount": 3
    },
    "Tracing": {
      "EnableTracing": true,
      "SamplingRate": 0.1,
      "ServiceName": "EMR-Cache",
      "EnableMetrics": true,
      "EnableDetailedAttributes": false
    },
    "Eviction": {
      "PolicyType": "Adaptive",
      "MemoryPressureThreshold": 80,
      "MaxEntriesPerEviction": 1000
    },
    "LargeScale": {
      "ExpectedConcurrentUsers": 10000,
      "EnableCacheWarming": true,
      "EnableTracing": true,
      "TracingSamplingRate": 0.1
    },
    "BatchOperations": {
      "MaxBatchSize": 500,
      "MaxConcurrentBatches": 10,
      "BatchTimeoutSeconds": 30,
      "EnablePipelining": true
    },
    "RedisCluster": {
      "EnableCluster": false,
      "EnableSentinel": false,
      "InstanceName": "EMR-Cache",
      "VirtualNodesPerPhysical": 150,
      "ClusterEndpoints": [],
      "SentinelEndpoints": [],
      "SentinelServiceName": "mymaster"
    },
    "MultiTenant": {
      "Enabled": false,
      "AllowEmptyTenant": true,
      "TrackKeysPerTenant": true,
      "TenantHeaderName": "X-Tenant-Id"
    },
    "Decorators": {
      "EnableTracingDecorator": true,
      "EnableTenantDecorator": false
    }
  },
  "Redis": {
    "Enable": true,
    "ConnectionString": "localhost:6379",
    "Database": 0,
    "KeyPrefix": "emr:"
  }
}

3. Logging Configuration

{
  "Serilog": {
    "MinimumLevel": "Information",
    "WriteTo": [
      {
        "Name": "Console",
        "Args": {
          "outputTemplate": "[{Timestamp:HH:mm:ss} {Level:u3}] {Message:lj} {Properties:j}{NewLine}{Exception}"
        }
      },
      {
        "Name": "Elasticsearch",
        "Args": {
          "nodeUris": "http://localhost:9200",
          "indexFormat": "medcom-hr-logs-{0:yyyy.MM.dd}"
        }
      }
    ]
  }
}

📚 Hướng dẫn sử dụng

🚀 Quick Start - Unified Setup (Recommended)

using IMEX.CORE.Extensions;

// Program.cs (.NET 6+)
var builder = WebApplication.CreateBuilder(args);

// ✅ Cách 1: Minimal setup (Memory Cache + SqlSugar)
builder.Services.AddImexCore();

// ✅ Cách 2: Full configuration
builder.Services.AddImexCore(options =>
{
    options.UseCache(CacheMode.Hybrid, "localhost:6379");
    options.UseCachePreset(CachePreset.HighPerformance);
    options.UseSqlSugar();
    options.UseMonitoring();
    options.UseCacheWarming();
});

// ✅ Cách 3: Từ appsettings.json
builder.Services.AddImexCore(builder.Configuration);

var app = builder.Build();
app.UseImexCore(); // Configure middleware
app.Run();

appsettings.json Configuration

{
  "ImexCore": {
    "CacheMode": "Hybrid",
    "RedisConnection": "localhost:6379",
    "EnableMonitoring": true,
    "EnableCacheWarming": true,
    "UseSqlSugar": true
  }
}

---

🗃️ Chi tiết cấu hình Cache (Fluent API)

Cache Strategies

Strategy	Mô tả	Use Case
UseMemoryCache()	Chỉ L1 in-memory	Single server, development
UseHybridCache(redis)	L1 Memory + L2 Redis	Multi-server, production
UseRedisCache(redis)	Chỉ Redis	Stateless containers
UseAutoStrategy()	Tự động detect	Auto-scaling environments

Cache Presets

Preset	MaxEntries	MaxMemory	BackgroundRefresh	Use Case
HighPerformance	5000	1GB	90%	High-traffic APIs
MemoryOptimized	1000	256MB	70%	Limited RAM
HighReliability	3000	512MB	80%	Critical apps
HybridProduction	2000	512MB	85%	Multi-server

Fluent API - Full Example

using IMEX.CORE.Core.Caching.Configuration;

// 🎯 Cách 1: Fluent Builder (Recommended)
services.AddCache()
    // Chọn strategy
    .UseHybridCache("localhost:6379", instanceName: "MyApp")
    
    // Chọn preset
    .WithPreset(CachePreset.HighPerformance)
    
    // Optional features
    .WithMonitoring()           // Health dashboard
    .WithMetrics()              // Prometheus metrics
    .WithRateLimiting(config => // Rate limiting
    {
        config.TokensPerSecond = 100;
        config.MaxConcurrentOperations = 50;
    })
    .WithMemoryPressureManagement() // Auto-eviction khi thiếu RAM
    
    // Custom L1 configuration
    .ConfigureL1(config =>
    {
        config.FailSafe.MaxEntries = 10000;
        config.FailSafe.MaxTotalBytes = 2L * 1024 * 1024 * 1024; // 2GB
        config.BackgroundRefreshRatio = 0.85;
        config.AdaptiveTtl.HighHitRatioThreshold = 0.9;
        config.AdaptiveTtl.HighPerformanceMultiplier = 2.5;
    })
    
    // Custom Hybrid configuration
    .ConfigureHybrid(config =>
    {
        config.EnableL2Cache = true;
        config.L2TtlMultiplier = 3.0;
        config.EnableBackgroundRefresh = true;
        config.SoftTimeout = TimeSpan.FromSeconds(3);
        config.HardTimeout = TimeSpan.FromSeconds(20);
    })
    .Build();

Quick Setup Methods

// 🚀 High Performance (Memory hoặc Hybrid)
services.AddHighPerformanceCache();                        // Memory only
services.AddHighPerformanceCache("localhost:6379");        // Hybrid với Redis

// 💾 Memory Optimized (tiết kiệm RAM)
services.AddMemoryOptimizedCache();

// 🏭 Production Hybrid (full features)
services.AddProductionHybridCache(
    redisConnectionString: "localhost:6379",
    enableRateLimiting: true,
    enableMemoryPressure: true
);

Cache Configuration in appsettings.json

{
  "Cache": {
    "EnhancedMemoryCache": {
      "BackgroundRefreshRatio": 0.85,
      "BackgroundRefreshIntervalSeconds": 30,
      "CleanupSampleSize": 2000,
      "CleanupSamplingRate": 0.15,
      "FailSafe": {
        "MaxEntries": 5000,
        "MaxTotalBytes": 536870912,
        "DefaultTtlMinutes": 45,
        "AlwaysCompressSnapshot": true
      },
      "AdaptiveTtl": {
        "HighHitRatioThreshold": 0.85,
        "LowHitRatioThreshold": 0.5,
        "HighPerformanceMultiplier": 1.8,
        "MaxTtlMultiplier": 2.5,
        "MinTtlMinutes": 2
      },
      "SingleFlight": {
        "HighConcurrencyThreshold": 256,
        "WaitForExistingHighMs": 1500,
        "FactoryHardTimeoutMs": 8000
      }
    },
    "Hybrid": {
      "EnableL2Cache": true,
      "L2TtlMultiplier": 2.5,
      "L1PromotionTtlMinutes": 25,
      "EnableFactoryTimeouts": true,
      "SoftTimeoutMs": 3000,
      "HardTimeoutMs": 20000,
      "FailSafeTtlMultiplier": 1.2
    }
  },
  "Redis": {
    "Enable": true,
    "ConnectionString": "localhost:6379",
    "InstanceName": "MyApp",
    "DefaultExpiration": "00:45:00",
    "EnableCircuitBreaker": true,
    "CbErrorRateThreshold": 0.08,
    "CbBreakSeconds": 20,
    "RetryCount": 3
  }
}

---

🗄️ Chi tiết cấu hình SqlSugar

Setup cơ bản

// Program.cs
builder.Services.AddSqlSugarSetup();

// Hoặc qua AddImexCore
builder.Services.AddImexCore(options =>
{
    options.UseSqlSugar();
});

Database Configuration (appsettings.json)

{
  "MainDB": "DB_Main",
  "DBConnections": [
    {
      "ConnId": "DB_Main",
      "DBType": 1,
      "Enable": true,
      "HitRate": 50,
      "ConnectionStr": "Server=localhost;Database=MyDB;User Id=sa;Password=xxx;",
      "Slaves": [
        {
          "HitRate": 30,
          "ConnectionStr": "Server=slave1;Database=MyDB;User Id=sa;Password=xxx;"
        },
        {
          "HitRate": 20,
          "ConnectionStr": "Server=slave2;Database=MyDB;User Id=sa;Password=xxx;"
        }
      ]
    },
    {
      "ConnId": "DB_Log",
      "DBType": 1,
      "Enable": true,
      "HitRate": 0,
      "ConnectionStr": "Server=localhost;Database=MyDB_Log;User Id=sa;Password=xxx;"
    }
  ]
}

Database Types (DBType)

DBType	Database	Mô tả
0	MySql	MySQL/MariaDB
1	SqlServer	Microsoft SQL Server
2	Sqlite	SQLite
3	Oracle	Oracle Database
4	PostgreSQL	PostgreSQL
5	Dm	DM Database
6	Kdbndp	Kingbase

SqlSugar AOP Configuration

{
  "AppSettings": {
    "SqlAOP": {
      "EnableSlowQueryDetection": true,
      "SlowQueryThresholdMs": 3000,
      "SlowQuerySamplingRate": 100,
      "EnableDiffLog": true
    },
    "LogToDb": true
  }
}

Sử dụng SqlSugar trong Service

public class UserService
{
    private readonly ISqlSugarClient _db;
    private readonly ISmartCache _cache;

    public UserService(ISqlSugarClient db, ISmartCache cache)
    {
        _db = db;
        _cache = cache;
    }

    // Query với cache
    public async Task<List<User>> GetActiveUsersAsync()
    {
        var key = _cache.CreateKey("users", "active");
        return await _cache.GetAsync(key, async () =>
        {
            return await _db.Queryable<User>()
                .Where(u => u.IsActive)
                .ToListAsync();
        }, ttlMinutes: 30);
    }

    // Transaction
    public async Task<bool> CreateUserAsync(User user)
    {
        try
        {
            _db.Ado.BeginTran();
            
            await _db.Insertable(user).ExecuteCommandAsync();
            await _db.Insertable(new UserProfile { UserId = user.Id })
                     .ExecuteCommandAsync();
            
            _db.Ado.CommitTran();
            
            // Invalidate cache
            await _cache.RemoveByPrefixAsync("users");
            return true;
        }
        catch
        {
            _db.Ado.RollbackTran();
            throw;
        }
    }

    // Multi-database
    public async Task<List<AuditLog>> GetLogsAsync()
    {
        // Switch to Log database
        return await _db.GetConnection("DB_Log")
            .Queryable<AuditLog>()
            .OrderByDescending(l => l.CreatedAt)
            .Take(100)
            .ToListAsync();
    }
}

Read/Write Splitting (Master-Slave)

{
  "DBConnections": [
    {
      "ConnId": "DB_Main",
      "DBType": 1,
      "Enable": true,
      "HitRate": 50,
      "ConnectionStr": "Server=master;Database=MyDB;...",
      "Slaves": [
        {
          "HitRate": 30,
          "ConnectionStr": "Server=slave1;Database=MyDB;..."
        },
        {
          "HitRate": 20,
          "ConnectionStr": "Server=slave2;Database=MyDB;..."
        }
      ]
    }
  ]
}

Lưu ý: HitRate càng cao thì slave đó được sử dụng nhiều hơn. HitRate = 0 nghĩa là không sử dụng.

Encrypted Connection String

{
  "DBConnections": [
    {
      "ConnId": "DB_Main",
      "DBType": 1,
      "Enable": true,
      "ConnectionStr": "BASE64_ENCRYPTED_STRING.SIGNATURE"
    }
  ]
}

Thư viện tự động detect và decrypt connection string nếu đúng format base64.signature.

---

Large-Scale Cache Setup (5K-20K Users)

// Cách 1: Tất cả tính năng từ appsettings.json
services.AddLargeScaleCacheFeatures();

// Cách 2: Custom configuration
services.AddLargeScaleCacheFeatures(new LargeScaleCacheOptions
{
    ExpectedConcurrentUsers = 20000,
    EnableCacheWarming = true,
    EnableTracing = true,
    TracingSamplingRate = 0.05,
    ServiceName = "EMR-Production"
});

// Thêm tính năng riêng lẻ
services.AddCacheWarming();
services.AddCacheTracing();
services.AddAdaptiveEviction();
services.AddBatchOperationsConfig();

Redis Cluster Setup

// Từ appsettings.json
services.AddRedisClusterSupport();

// Hoặc custom configuration
services.AddRedisClusterSupport(options =>
{
    options.EnableCluster = true;
    options.ClusterEndpoints = new List<string>
    {
        "redis-node1:6379",
        "redis-node2:6379",
        "redis-node3:6379"
    };
    options.VirtualNodesPerPhysical = 150;
});

Multi-Tenant Cache Setup

// Thêm tenant context provider
services.AddDefaultTenantContextProvider();

// Thêm cache decorators với tenant isolation
services.AddCacheDecorators(
    enableTracing: true,
    enableTenantIsolation: true
);

Basic Cache Operations

using IMEX.Core.Caching.Interfaces;

public class MyService
{
    private readonly ISmartCache _cache;
    
    public MyService(ISmartCache cache)
    {
        _cache = cache;
    }
    
    // Get với factory pattern
    public async Task<Employee> GetEmployeeAsync(int id)
    {
        var key = _cache.CreateKey("employees", id.ToString());
        return await _cache.GetAsync<Employee>(key, async () =>
        {
            return await _dbContext.Employees.FindAsync(id);
        }, ttlMinutes: 30);
    }
    
    // Batch operations
    public async Task<Dictionary<string, Employee>> GetEmployeesAsync(IEnumerable<int> ids)
    {
        var keys = ids.Select(id => _cache.CreateKey("employees", id.ToString()));
        return await _cache.GetManyAsync<Employee>(keys);
    }
    
    // Remove by prefix
    public async Task InvalidateEmployeeCacheAsync()
    {
        await _cache.RemoveByPrefixAsync("employees");
    }
}

Cache Warming Registration

public class EmployeeCacheWarmer
{
    private readonly CacheWarmingService _warmingService;
    
    public EmployeeCacheWarmer(CacheWarmingService warmingService)
    {
        _warmingService = warmingService;
    }
    
    public void RegisterWarmingTasks()
    {
        // Đăng ký critical keys
        _warmingService.RegisterCriticalKey("employees:all", async () =>
        {
            return await _dbContext.Employees.ToListAsync();
        }, priority: 1, ttlMinutes: 60);
        
        _warmingService.RegisterCriticalKey("departments:all", async () =>
        {
            return await _dbContext.Departments.ToListAsync();
        }, priority: 2, ttlMinutes: 120);
    }
}

Performance Monitoring

using IMEX.CORE.Core.Caching.Monitoring;

// Lấy metrics
var metrics = cache.GetCacheMetrics();

// Export Prometheus format
var prometheusData = CacheOpenTelemetryExporter.ExportPrometheusSnapshot(metrics);

// Metrics bao gồm:
// - cache_hit_ratio
// - cache_latency_ms
// - cache_memory_usage_bytes
// - cache_entries_count
// - cache_eviction_count

Database Operations với Caching

using IMEX.CORE.Core.DBAccess;

public class EmployeeRepository
{
    private readonly DbContextBase _dbContext;
    private readonly ISmartCache _cache;
    
    public async Task<List<Employee>> GetActiveEmployeesAsync(int departmentId)
    {
        var key = _cache.CreateKey("employees", $"dept:{departmentId}:active");
        
        return await _cache.GetAsync(key, async () =>
        {
            return await _dbContext.Queryable<Employee>()
                .Where(e => e.DepartmentId == departmentId && e.IsActive)
                .ToListAsync();
        }, ttlMinutes: 30);
    }
}

🏗️ Kiến trúc

System Architecture

┌───────────────────────────────────────────────────────────┐
│                    IMEX.Core                              │
├───────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Caching   │  │  Database   │  │  Security   │        │
│  │   System    │  │   Access    │  │   Layer     │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
├───────────────────────────────────────────────────────────┤
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐        │
│  │   Logging   │  │  Utilities  │  │   Models    │        │
│  │   System    │  │   & Helpers │  │   & DTOs    │        │
│  └─────────────┘  └─────────────┘  └─────────────┘        │
├───────────────────────────────────────────────────────────┤
│                 .NET 8.0/9.0/10.0 Runtime                 │
└───────────────────────────────────────────────────────────┘

Enhanced Cache Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                    Enterprise Cache System (Large-Scale)                    │
├─────────────────────────────────────────────────────────────────────────────┤
│                              DECORATORS LAYER                               │
│  ┌───────────────────┐  ┌───────────────────┐  ┌───────────────────┐        │
│  │ TracingDecorator  │  │ TenantDecorator   │  │ EventDrivenDeco.  │        │
│  │ • OpenTelemetry   │  │ • Multi-tenant    │  │ • Cache Events    │        │
│  │ • Prometheus      │  │ • Key isolation   │  │ • Notifications   │        │
│  └───────────────────┘  └───────────────────┘  └───────────────────┘        │
├─────────────────────────────────────────────────────────────────────────────┤
│                              HYBRID CACHE LAYER                             │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                  EnhancedHybridMemoryCache                          │    │
│  │  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐ │    │
│  │  │ L1 Memory   │  │ L2 Redis    │  │ Lock        │  │ Circuit     │ │    │
│  │  │ Cache       │→ │ Cache       │  │ Manager     │  │ Breaker     │ │    │
│  │  │ (Enhanced)  │  │ (MsgPack)   │  │ (Single-    │  │ (Enhanced)  │ │    │
│  │  └─────────────┘  └─────────────┘  │  Flight)    │  └─────────────┘ │    │
│  │                                    └─────────────┘                  │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
├─────────────────────────────────────────────────────────────────────────────┤
│                              L1 CACHE FEATURES                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ Fail-Safe   │  │ Background  │  │ Adaptive    │  │ Prefix/Tag  │         │
│  │ Cache       │  │ Refresh     │  │ TTL         │  │ Manager     │         │
│  │ • Stale     │  │ • SWR       │  │ • Hit-based │  │ • Trie DS   │         │
│  │   fallback  │  │ • Scheduled │  │ • Frequency │  │ • Pattern   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘         │
├─────────────────────────────────────────────────────────────────────────────┤
│                              L2 CACHE FEATURES                              │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐              │
│  │ MessagePack     │  │ Redis Cluster   │  │ Consistent Hash │              │
│  │ Provider        │  │ Provider        │  │ Ring            │              │
│  │ • LZ4 compress  │  │ • Cluster mode  │  │ • Virtual nodes │              │
│  │ • Pipeline      │  │ • Sentinel      │  │ • Auto balance  │              │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘              │
├─────────────────────────────────────────────────────────────────────────────┤
│                              MANAGEMENT SERVICES                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐         │
│  │ Warming     │  │ Eviction    │  │ Memory      │  │ Health      │         │
│  │ Service     │  │ Policy      │  │ Pressure    │  │ Monitor     │         │
│  │ • Startup   │  │ • LRU/LFU   │  │ • Auto GC   │  │ • Real-time │         │
│  │ • Priority  │  │ • Adaptive  │  │ • Auto GC   │  │ • Metrics   │         │
│  └─────────────┘  └─────────────┘  └─────────────┘  └─────────────┘         │
└─────────────────────────────────────────────────────────────────────────────┘

Cache Configuration Classes

CacheConfiguration (Root)
├── HybridCacheConfiguration
│   └── L2 TTL, Factory Timeouts, Sync settings
├── EnhancedMemoryCacheConfiguration
│   └── AdaptiveTtlConfiguration
├── MedicalCacheConfiguration
│   └── Domain-specific TTLs
├── WarmingConfiguration
├── TracingConfiguration
├── EvictionConfiguration
├── LargeScaleConfiguration
├── BatchOperationsConfiguration
├── RedisClusterConfiguration
├── MultiTenantConfiguration
└── DecoratorsConfiguration

🔧 API Reference

Core Interfaces

ISmartCache

public interface ISmartCache : IDisposable, IAsyncDisposable
{
    // Key management
    string CreateKey(string tableName, string key);
    
    // Sync operations
    T? Get<T>(string key);
    T? GetFast<T>(string key);  // Ultra-fast, skip complex features
    void Set<T>(string key, T value, int ttlMinutes);
    void SetFast<T>(string key, T value, int ttlMinutes);
    void SetSmart<T>(string key, T value, int ttlMinutes);
    
    // Async operations
    Task<T?> GetAsync<T>(string key, Func<Task<T>> factory, int ttlMinutes);
    Task<T?> GetOrCreateAsync<T>(string key, Func<Task<T>> factory, int ttlMinutes);
    Task SetAsync<T>(string key, T value, int ttlMinutes);
    
    // Batch operations
    Task<Dictionary<string, T?>> GetManyAsync<T>(IEnumerable<string> keys);
    Task SetManyAsync<T>(Dictionary<string, T> entries, int ttlMinutes);
    Task RemoveManyAsync(IEnumerable<string> keys);
    Task<Dictionary<string, T>> GetOrCreateManyAsync<T>(
        IEnumerable<string> keys, 
        Func<IEnumerable<string>, Task<Dictionary<string, T>>> factory, 
        int ttlMinutes);
    
    // Removal operations
    Task RemoveAsync(string key);
    Task RemoveByPrefixAsync(string prefix);
    
    // Metrics
    CacheDashboardMetrics GetCacheMetrics();
}

ICacheWarmer

public interface ICacheWarmer
{
    Task WarmCacheAsync(CancellationToken cancellationToken);
    Task WarmCriticalKeysAsync(IEnumerable<CacheWarmingEntry> entries);
    void RegisterCriticalKey<T>(string key, Func<Task<T>> factory, int priority, int ttlMinutes);
}

IEvictionPolicy

public interface IEvictionPolicy
{
    string PolicyName { get; }
    IEnumerable<string> SelectKeysForEviction(
        IEnumerable<CacheEntryInfo> entries, 
        int maxEntriesToEvict);
}

// Available policies:
// - LruEvictionPolicy
// - LfuEvictionPolicy
// - SizeBasedEvictionPolicy
// - TtlEvictionPolicy
// - RandomEvictionPolicy
// - AdaptiveEvictionPolicy
// - CompositeEvictionPolicy

IConsistentHashRing

public interface IConsistentHashRing
{
    void AddNode(string nodeId);
    void RemoveNode(string nodeId);
    string GetNode(string key);
    int NodeCount { get; }
    int VirtualNodeCount { get; }
}

Extension Methods

// CacheSetup extensions
public static class CacheSetup
{
    // Auto-detection
    void AddSmartCacheSetup(this IServiceCollection services, IConfiguration? config);
    
    // Strategy-based
    void AddCacheSetupWithStrategy(this IServiceCollection services, CacheStrategy strategy, IConfiguration? config);
    
    // Large-scale features
    void AddLargeScaleCacheFeatures(this IServiceCollection services, LargeScaleCacheOptions? options);
    void AddCacheWarming(this IServiceCollection services, Action<CacheWarmingConfig>? configure);
    void AddCacheTracing(this IServiceCollection services, Action<CacheTracingConfig>? configure);
    void AddRedisClusterSupport(this IServiceCollection services, Action<RedisClusterOptions>? configure);
    void AddAdaptiveEviction(this IServiceCollection services, Action<EvictionPolicyConfig>? configure);
    void AddBatchOperationsConfig(this IServiceCollection services, Action<BatchOperationsConfig>? configure);
    
    // Multi-tenant
    void AddDefaultTenantContextProvider(this IServiceCollection services);
    void AddCacheDecorators(this IServiceCollection services, bool? enableTracing, bool? enableTenantIsolation);
}

🧪 Testing

Chạy test

dotnet test .\tests\IMEX.CORE.Tests\IMEX.CORE.Tests.csproj -c Release

Ghi chú:

• Một số bài test thuộc nhóm Performance/Regression có thể phụ thuộc phần cứng/OS scheduler (đặc biệt Windows) nên có thể không ổn định như unit test logic.
• Một số bài test Integration (Redis/L2) có thể được Skip nếu môi trường không đáp ứng.

Chạy test logic (khuyến nghị cho CI release)

Nếu bạn muốn tách nhóm Performance ra khỏi pipeline đóng gói, hãy chạy filter theo namespace (tuỳ cách bạn tổ chức test):

dotnet test .\tests\IMEX.CORE.Tests\IMEX.CORE.Tests.csproj -c Release --filter FullyQualifiedName!~IMEX.CORE.Tests.Performance

Unit Tests

[Test]
public async Task Cache_Should_Store_And_Retrieve_Data()
{
    // Arrange
    var cache = new EnhancedMemoryCache(memoryCache, config);
    var testData = new { Id = 1, Name = "Test" };
    
    // Act
    await cache.SetAsync("test:key", testData, 10);
    var result = await cache.GetAsync<object>("test:key", () => Task.FromResult(testData));
    
    // Assert
    Assert.That(result, Is.Not.Null);
    Assert.That(result.Id, Is.EqualTo(1));
}

Batch Operations Tests

[Test]
public async Task BatchOperations_Should_Handle_Multiple_Keys()
{
    // Arrange
    var entries = new Dictionary<string, Employee>
    {
        ["emp:1"] = new Employee { Id = 1, Name = "John" },
        ["emp:2"] = new Employee { Id = 2, Name = "Jane" }
    };
    
    // Act
    await cache.SetManyAsync(entries, ttlMinutes: 30);
    var results = await cache.GetManyAsync<Employee>(entries.Keys);
    
    // Assert
    Assert.That(results.Count, Is.EqualTo(2));
}

Performance Tests

[Test]
public async Task Cache_Performance_Should_Be_Optimal()
{
    // Arrange
    var analyzer = new CachePerformanceAnalyzer();
    
    // Act
    var results = await analyzer.RunBenchmarkAsync(100_000);
    
    // Assert
    Assert.That(results.SetOperations.Improvement, Is.GreaterThan(2.0)); // 2x faster
    Assert.That(results.MemoryUsage.MemorySavings, Is.GreaterThan(40.0)); // 40% less memory
}

📈 Performance

Benchmark Results

Operation	Standard .NET	IMEX.Core	Improvement
Set Operations	100ns	25ns	4x faster
Get Operations	50ns	15ns	3.3x faster
Memory Usage	100%	30-50%	50-70% less
GC Pressure	100%	10-20%	80-90% less
Throughput	800K ops/sec	3.2M ops/sec	4x higher
Batch Operations	10K ops/sec	500K ops/sec	50x faster

Large-Scale Performance

• Concurrent Users: 5K-20K với Redis Cluster
• Hit Ratio: 90-98% với background refresh
• Response Time: < 500μs cho cache hits
• Memory Efficiency: 50-70% tiết kiệm memory
• Distributed Performance: Sub-millisecond với Redis pipelining

Advanced Optimizations

• Object Pooling: 90% reduction trong memory allocations
• Span-based Operations: Zero-allocation string operations
• Adaptive Circuit Breaker: Tự động điều chỉnh ngưỡng lỗi
• Memory Advisor: Tự động tối ưu hóa cache size
• Consistent Hashing: Even distribution across Redis nodes

🤝 Đóng góp

Chúng tôi hoan nghênh mọi đóng góp từ cộng đồng! Để đóng góp:

1. Fork repository
2. Tạo branch cho feature mới (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push lên branch (git push origin feature/amazing-feature)
5. Tạo Pull Request

Development Guidelines

• Tuân thủ coding standards của .NET
• Viết unit tests cho code mới
• Cập nhật documentation
• Đảm bảo backward compatibility

📄 License

Dự án này được phân phối dưới giấy phép MIT. Xem file LICENSE để biết thêm chi tiết.

📞 Liên hệ

• Tác giả: truongnv2412
• Công ty: IMEXsoft.,JSC
• Email: support@imexsoft.com
• Website: https://imexsoft.com

🙏 Acknowledgments

• SqlSugar ORM - Powerful ORM framework
• Serilog - Structured logging framework
• StackExchange.Redis - High-performance Redis client
• MessagePack - Fast serialization library
• OpenTelemetry - Observability framework
• Microsoft.Extensions - .NET extension libraries

---

⭐ Nếu thư viện này hữu ích, hãy cho chúng tôi một star! ⭐

Made with ❤️ by truongnv2412