# SmartPool System

Hệ thống quản lý proxy thông minh với nhiều chiến lược lựa chọn và phân tích hiệu suất.

## Tổng quan

SmartPool là hệ thống quản lý proxy mới được xây dựng từ đầu với các tính năng:

- **5 chiến lược lựa chọn proxy thông minh**
- **Dual protocol support**: gRPC (MagicOnion) và HTTP REST API
- **ClickHouse integration**: Logging và analytics hiệu suất cao
- **SDK client**: Dễ dàng tích hợp vào các service

## Kiến trúc

```
┌─────────────────┐
│ Client Services │
└────────┬────────┘
         │
         ↓
┌─────────────────────┐
│ SmartPool.Proxy SDK │ (gRPC hoặc HTTP)
└────────┬────────────┘
         │
         ↓
┌──────────────────────┐
│ API.SmartPool        │
│ - gRPC Service       │
│ - HTTP Controller    │
│ - Strategy Factory   │
└────────┬─────────────┘
         │
         ↓
┌─────────────────────────────┐
│ ClickHouse Databases        │
│                             │
│ smart_pool_meta:            │
│ - proxy_metadata            │
│ - proxy_access_mapping      │
│                             │
│ smart_pool_logs:            │
│ - proxy_usage_logs          │
│ - proxy_stats_hourly        │
└─────────────────────────────┘
```

## Các thành phần

### 1. Icomm.SmartPool.Abstractions
Thư viện shared chứa interfaces và models:
- `ISmartProxyService`: MagicOnion interface
- Request/Response models
- Enums (Strategy, Protocol, IpVersion)

### 2. Icomm.API.SmartPool
API Backend với:
- **Services**: SmartProxyGrpcService (MagicOnion)
- **Controllers**: SmartProxyController (HTTP REST)
- **Strategies**: 5 chiến lược pick proxy
- **Repositories**: ProxyMetadataRepository, ProxyLogRepository
- **Infrastructure**: ClickHouse context, DI extensions

### 3. Icomm.SmartPool.Proxy
Client SDK hỗ trợ:
- `ISmartPoolClient`: Interface chính
- `SmartPoolClient`: Implementation cho cả gRPC và HTTP
- Extension methods cho DI registration

### 4. Icomm.SmartPool.Tests
Unit tests cho:
- Strategies
- Client SDK
- Factory pattern

## Chiến lược Pick Proxy

### 1. Random Strategy
```csharp
strategy: "random"
```
- Pick ngẫu nhiên từ danh sách proxy được phân quyền
- Hỗ trợ filter: country, ip_version, protocol

### 2. Round Robin Strategy
```csharp
strategy: "round_robin"
```
- Xoay vòng tuần tự qua các proxy
- Sử dụng Redis để lưu index
- Đảm bảo phân phối đều workload

### 3. Least Delay Strategy
```csharp
strategy: "least_delay"
targetDomain: "facebook.com"  // Required
```
- Chọn proxy có response time thấp nhất
- Dựa trên dữ liệu 24h gần nhất
- Tối ưu cho từng target_domain cụ thể

### 4. Adaptive Ranking Strategy
```csharp
strategy: "adaptive_ranking"
targetDomain: "facebook.com"  // Required
```
- Chọn proxy có điểm số cao nhất
- Điểm số = success_rate_10 × 0.4 + success_rate_50 × 0.3 + success_rate_100 × 0.2 + success_rate_200 × 0.1
- Dựa trên dữ liệu 7 ngày gần nhất

### 5. Alternative Strategy
```csharp
strategy: "alternative"
refererProxy: { id: 123 }  // Required
```
- Tìm proxy thay thế tương tự với proxy hiện tại
- Cùng ip_version, country, protocol
- Hữu ích khi proxy hiện tại bị lỗi

## Cài đặt và Chạy

### Bước 1: Setup ClickHouse

```bash
# Chạy script khởi tạo database
clickhouse-client < src/Icomm.API.SmartPool/clickhouse_init.sql
```

### Bước 2: Cấu hình

Sửa `appsettings.json` trong `Icomm.API.SmartPool`:

```json
{
  "ClickHouse": {
    "Host": "localhost",
    "Port": 8123,
    "MetaDatabase": "smart_pool_meta",
    "LogsDatabase": "smart_pool_logs"
  },
  "Redis": {
    "Configuration": "localhost:6379"
  }
}
```

### Bước 3: Chạy API

```bash
cd src/Icomm.API.SmartPool
dotnet run
```

API sẽ chạy tại:
- HTTP: http://localhost:5000
- gRPC: http://localhost:5001
- Swagger: http://localhost:5000/swagger

### Bước 4: Sử dụng SDK trong Client Service

```csharp
// Trong Program.cs hoặc Startup.cs
services.AddSmartPoolClient(configuration);

// Trong service của bạn
public class MyService
{
    private readonly ISmartPoolClient _smartPoolClient;
    
    public MyService(ISmartPoolClient smartPoolClient)
    {
        _smartPoolClient = smartPoolClient;
    }
    
    public async Task DoWorkAsync()
    {
        // Lấy proxy
        var proxy = await _smartPoolClient.GetProxyAsync(
            strategy: "least_delay",
            targetDomain: "facebook.com"
        );
        
        // Sử dụng proxy
        var handler = new HttpClientHandler { Proxy = proxy };
        var httpClient = new HttpClient(handler);
        var response = await httpClient.GetAsync("https://facebook.com");
        
        // Ghi log
        await _smartPoolClient.LogProxyUsageAsync(
            accessToken: "your-token",
            proxyId: 123,
            targetDomain: "facebook.com",
            statusCode: (int)response.StatusCode,
            responseTimeMs: 450
        );
    }
}
```

## Data Flow

### Luồng Get Proxy

```
Client Service
    ↓
SmartPool SDK (GetProxyAsync)
    ↓
API Backend (gRPC/HTTP)
    ↓
Strategy Factory
    ↓
Strategy Implementation (Random/RoundRobin/LeastDelay/AdaptiveRanking/Alternative)
    ↓
Repository (Query ClickHouse)
    ↓
Return SmartProxyServer
```

### Luồng Log Usage

```
Client Service
    ↓
SmartPool SDK (LogProxyUsageAsync)
    ↓
API Backend (gRPC/HTTP)
    ↓
ProxyLogRepository
    ↓
INSERT INTO proxy_usage_logs
    ↓
Materialized View tự động aggregate vào proxy_stats_hourly
```

## ClickHouse Schema

### Database: smart_pool_meta (Metadata)

1. **proxy_metadata**: Thông tin proxy servers
2. **proxy_access_mapping**: Mapping access_token → cluster (flexible cluster-based access control)

### Database: smart_pool_logs (Logs & Analytics)

3. **proxy_usage_logs**: Log sử dụng proxy (TTL 90 ngày)
4. **proxy_stats_hourly**: Thống kê theo giờ (Materialized View)

### Queries mẫu

```sql
-- Xem proxy có response time thấp nhất
SELECT 
    proxy_id,
    avgMerge(avg_response_time_state) as avg_time
FROM smart_pool_logs.proxy_stats_hourly
WHERE access_token = 'your-token'
    AND hour >= now() - INTERVAL 24 HOUR
GROUP BY proxy_id
ORDER BY avg_time ASC
LIMIT 10;

-- Xem success rate của proxy
SELECT 
    proxy_id,
    sumIfMerge(success_count_state) / countMerge(request_count_state) as success_rate
FROM smart_pool_logs.proxy_stats_hourly
WHERE access_token = 'your-token'
GROUP BY proxy_id
ORDER BY success_rate DESC;
```

## Testing

```bash
# Chạy tất cả tests
dotnet test

# Chạy tests với output chi tiết
dotnet test --logger "console;verbosity=detailed"
```

## Dependencies

- .NET 8.0
- MagicOnion 5.1.11
- ClickHouse.Client 7.7.0
- EasyCaching.Redis 1.9.2
- Dapper 2.1.35
- Serilog 8.0.1

## Tài liệu tham khảo

- [API Backend README](./docs/src/Icomm.API.SmartPool/README.md)
- [SDK Client README](./docs/src/Icomm.SmartPool.Proxy/README.md)
- [Tests README](./docs/src/Icomm.SmartPool.Tests/README.md)

## License

Internal use only.