BackOffice.BFF/docs/cms-integration.md

# BackOffice.BFF - CMS Integration Documentation

**Date**: 2025-11-30  
**Status**: ✅ Integrated  
**CMS Package Version**: 0.0.140  

---

## 📋 Overview

BackOffice.BFF به CMS Microservice متصل شد و حالا می‌تواند به سرویس‌های Network-Club-Commission دسترسی داشته باشد.

این Integration به BackOffice امکان می‌دهد:
- مدیریت کامیسیون‌های کاربران
- مشاهده ساختار شبکه Binary Tree
- فعال/غیرفعال کردن عضویت باشگاه
- مشاهده گزارشات هفتگی کمیسیون

---

## 🏗️ Architecture

```
┌─────────────────────────────────────────────────────────┐
│              BackOffice.BFF (API Gateway)                │
│                                                           │
│  ┌──────────────────────────────────────────────────┐   │
│  │      IApplicationContractContext                 │   │
│  │  - Users (existing)                              │   │
│  │  - Products (existing)                           │   │
│  │  - Orders (existing)                             │   │
│  │  ✨ Commissions (NEW)                            │   │
│  │  ✨ NetworkMemberships (NEW)                     │   │
│  │  ✨ ClubMemberships (NEW)                        │   │
│  └──────────────────────────────────────────────────┘   │
│                          ↓ gRPC                          │
└─────────────────────────────────────────────────────────┘
                          ↓
┌─────────────────────────────────────────────────────────┐
│                  CMS Microservice                        │
│             https://cms.kbs1.ir                          │
│                                                           │
│  ┌─────────────────────┐  ┌─────────────────────────┐  │
│  │ CommissionContract  │  │ NetworkMembershipContract│  │
│  │ - GetWeeklyPool     │  │ - GetUserNetworkInfo    │  │
│  │ - GetUserPayouts    │  │ - GetNetworkTree        │  │
│  │ - ProcessWithdrawal │  │ - CalculateLegBalances  │  │
│  └─────────────────────┘  └─────────────────────────┘  │
│                                                           │
│  ┌─────────────────────┐                                 │
│  │ ClubMembershipContract│                               │
│  │ - ActivateClub      │                                 │
│  │ - DeactivateClub    │                                 │
│  │ - GetClubStatus     │                                 │
│  └─────────────────────┘                                 │
└─────────────────────────────────────────────────────────┘
```

---

## 📦 Integration Details

### 1️⃣ NuGet Package

**Package**: `Foursat.CMSMicroservice.Protobuf`  
**Version**: `0.0.140` (Updated from 0.0.137)

**File**: `/BackOffice.BFF/src/BackOffice.BFF.Domain/BackOffice.BFF.Domain.csproj`

```xml
<PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.140" />
```

**What's New in 0.0.140**:
- ✨ `commission.proto` - Commission system contracts
- ✨ `networkmembership.proto` - Binary tree network contracts
- ✨ `clubmembership.proto` - Club membership contracts
- ✨ `configuration.proto` - System configuration contracts

---

### 2️⃣ Interface Definition

**File**: `/BackOffice.BFF/src/BackOffice.BFF.Application/Common/Interfaces/IApplicationContractContext.cs`

```csharp
public interface IApplicationContractContext
{
    // ... existing services ...
    
    // Network & Commission System (NEW)
    CommissionContract.CommissionContractClient Commissions { get; }
    NetworkMembershipContract.NetworkMembershipContractClient NetworkMemberships { get; }
    ClubMembershipContract.ClubMembershipContractClient ClubMemberships { get; }
}
```

---

### 3️⃣ Implementation

**File**: `/BackOffice.BFF/src/BackOffice.BFF.Infrastructure/Services/ApplicationContractContext.cs`

```csharp
public class ApplicationContractContext : IApplicationContractContext
{
    // ... existing implementations ...
    
    // Network & Commission System
    public CommissionContract.CommissionContractClient Commissions 
        => GetService<CommissionContract.CommissionContractClient>();
    
    public NetworkMembershipContract.NetworkMembershipContractClient NetworkMemberships 
        => GetService<NetworkMembershipContract.NetworkMembershipContractClient>();
    
    public ClubMembershipContract.ClubMembershipContractClient ClubMemberships 
        => GetService<ClubMembershipContract.ClubMembershipContractClient>();
}
```

---

### 4️⃣ gRPC Configuration

**File**: `/BackOffice.BFF/src/BackOffice.BFF.WebApi/appsettings.json`

```json
{
  "GrpcChannelOptions": {
    "FMSMSAddress": "https://dl.afrino.co",
    "CMSMSAddress": "https://cms.kbs1.ir"
  }
}
```

**Auto-Registration**: 
- gRPC clients به صورت خودکار توسط `ConfigureGrpcServices.BatchRegisterGrpcClients()` ثبت می‌شوند
- بر اساس نام Assembly (`CMSMicroservice.Protobuf`)
- با Address مشخص شده در `appsettings.json`

---

## 🔌 Available Services

### 1️⃣ CommissionContract

**Namespace**: `CMSMicroservice.Protobuf.Protos.Commission`

#### Commands:
```csharp
// محاسبه بالانس های هفتگی
await _context.Commissions.CalculateWeeklyBalancesAsync(
    new CalculateWeeklyBalancesRequest { WeekNumber = "2025-W48" });

// محاسبه Pool هفتگی
await _context.Commissions.CalculateWeeklyCommissionPoolAsync(
    new CalculateWeeklyCommissionPoolRequest { WeekNumber = "2025-W48" });

// پردازش Payout های کاربران
await _context.Commissions.ProcessUserPayoutsAsync(
    new ProcessUserPayoutsRequest { WeekNumber = "2025-W48" });

// درخواست برداشت توسط کاربر
await _context.Commissions.RequestWithdrawalAsync(
    new RequestWithdrawalRequest 
    { 
        UserId = 123, 
        Amount = 500000 
    });

// پردازش برداشت (توسط Admin)
await _context.Commissions.ProcessWithdrawalAsync(
    new ProcessWithdrawalRequest 
    { 
        PayoutId = 456, 
        Status = WithdrawalStatus.Approved 
    });
```

#### Queries:
```csharp
// دریافت Pool هفتگی
var pool = await _context.Commissions.GetWeeklyCommissionPoolAsync(
    new GetWeeklyCommissionPoolRequest { WeekNumber = "2025-W48" });

// دریافت Payout های یک کاربر
var payouts = await _context.Commissions.GetUserPayoutsAsync(
    new GetUserPayoutsRequest 
    { 
        UserId = 123,
        PageNumber = 1,
        PageSize = 10 
    });

// دریافت تاریخچه Withdrawal ها
var withdrawals = await _context.Commissions.GetWithdrawalHistoryAsync(
    new GetWithdrawalHistoryRequest 
    { 
        UserId = 123,
        Status = WithdrawalStatus.Pending 
    });
```

---

### 2️⃣ NetworkMembershipContract

**Namespace**: `CMSMicroservice.Protobuf.Protos.NetworkMembership`

#### Queries:
```csharp
// دریافت اطلاعات شبکه یک کاربر
var networkInfo = await _context.NetworkMemberships.GetUserNetworkInfoAsync(
    new GetUserNetworkInfoRequest { UserId = 123 });

// دریافت درخت شبکه (Binary Tree)
var tree = await _context.NetworkMemberships.GetNetworkTreeAsync(
    new GetNetworkTreeRequest 
    { 
        RootUserId = 123,
        MaxDepth = 5 
    });

// دریافت بالانس های هفتگی
var balances = await _context.NetworkMemberships.GetUserWeeklyBalancesAsync(
    new GetUserWeeklyBalancesRequest 
    { 
        UserId = 123,
        WeekNumber = "2025-W48" 
    });

// محاسبه بالانس Leg های یک کاربر
var legBalances = await _context.NetworkMemberships.CalculateLegBalancesAsync(
    new CalculateLegBalancesRequest { UserId = 123 });
```

---

### 3️⃣ ClubMembershipContract

**Namespace**: `CMSMicroservice.Protobuf.Protos.ClubMembership`

#### Commands:
```csharp
// فعال کردن عضویت باشگاه
await _context.ClubMemberships.ActivateClubMembershipAsync(
    new ActivateClubMembershipRequest 
    { 
        UserId = 123,
        ActivationDate = Timestamp.FromDateTime(DateTime.UtcNow) 
    });

// غیرفعال کردن عضویت باشگاه
await _context.ClubMemberships.DeactivateClubMembershipAsync(
    new DeactivateClubMembershipRequest 
    { 
        UserId = 123,
        Reason = "User request" 
    });
```

#### Queries:
```csharp
// دریافت وضعیت عضویت باشگاه
var status = await _context.ClubMemberships.GetClubMembershipStatusAsync(
    new GetClubMembershipStatusRequest { UserId = 123 });

// لیست تمام اعضای باشگاه
var members = await _context.ClubMemberships.GetAllClubMembersAsync(
    new GetAllClubMembersRequest 
    { 
        IsActive = true,
        PageNumber = 1,
        PageSize = 20 
    });
```

---

## 📝 Usage Example in BFF

### Example 1: Create Commission Query Handler

**File**: `/BackOffice.BFF/src/BackOffice.BFF.Application/CommissionCQ/Queries/GetUserPayouts/GetUserPayoutsQuery.cs`

```csharp
public record GetUserPayoutsQuery : IRequest<GetUserPayoutsResponseDto>
{
    public long UserId { get; init; }
    public int PageNumber { get; init; } = 1;
    public int PageSize { get; init; } = 10;
}

public class GetUserPayoutsQueryHandler 
    : IRequestHandler<GetUserPayoutsQuery, GetUserPayoutsResponseDto>
{
    private readonly IApplicationContractContext _context;

    public GetUserPayoutsQueryHandler(IApplicationContractContext context)
    {
        _context = context;
    }

    public async Task<GetUserPayoutsResponseDto> Handle(
        GetUserPayoutsQuery request, 
        CancellationToken cancellationToken)
    {
        var response = await _context.Commissions.GetUserPayoutsAsync(
            request.Adapt<GetUserPayoutsRequest>(), 
            cancellationToken: cancellationToken);

        return response.Adapt<GetUserPayoutsResponseDto>();
    }
}
```

---

### Example 2: Create Network Tree Query Handler

**File**: `/BackOffice.BFF/src/BackOffice.BFF.Application/NetworkCQ/Queries/GetNetworkTree/GetNetworkTreeQuery.cs`

```csharp
public record GetNetworkTreeQuery : IRequest<GetNetworkTreeResponseDto>
{
    public long RootUserId { get; init; }
    public int MaxDepth { get; init; } = 5;
}

public class GetNetworkTreeQueryHandler 
    : IRequestHandler<GetNetworkTreeQuery, GetNetworkTreeResponseDto>
{
    private readonly IApplicationContractContext _context;

    public GetNetworkTreeQueryHandler(IApplicationContractContext context)
    {
        _context = context;
    }

    public async Task<GetNetworkTreeResponseDto> Handle(
        GetNetworkTreeQuery request, 
        CancellationToken cancellationToken)
    {
        var response = await _context.NetworkMemberships.GetNetworkTreeAsync(
            request.Adapt<GetNetworkTreeRequest>(), 
            cancellationToken: cancellationToken);

        return response.Adapt<GetNetworkTreeResponseDto>();
    }
}
```

---

### Example 3: Create Club Activation Command Handler

**File**: `/BackOffice.BFF/src/BackOffice.BFF.Application/ClubCQ/Commands/ActivateClub/ActivateClubCommand.cs`

```csharp
public record ActivateClubCommand : IRequest<Unit>
{
    public long UserId { get; init; }
    public DateTimeOffset? ActivationDate { get; init; }
}

public class ActivateClubCommandHandler 
    : IRequestHandler<ActivateClubCommand, Unit>
{
    private readonly IApplicationContractContext _context;

    public ActivateClubCommandHandler(IApplicationContractContext context)
    {
        _context = context;
    }

    public async Task<Unit> Handle(
        ActivateClubCommand request, 
        CancellationToken cancellationToken)
    {
        await _context.ClubMemberships.ActivateClubMembershipAsync(
            request.Adapt<ActivateClubMembershipRequest>(), 
            cancellationToken: cancellationToken);

        return Unit.Value;
    }
}
```

---

## 🔐 Authentication & Authorization

**JWT Token**:
- BackOffice.BFF به CMS با JWT Token متصل می‌شود
- Token از `ITokenProvider` گرفته می‌شود
- در Header با کلید `Authorization: Bearer {token}` ارسال می‌شود

**Implementation در `ConfigureGrpcServices.cs`**:
```csharp
private static async Task CallCredentials(
    AuthInterceptorContext context, 
    Metadata metadata,
    IServiceProvider serviceProvider)
{
    var provider = serviceProvider.GetRequiredService<ITokenProvider>();
    var token = await provider.GetTokenAsync();
    metadata.Add("Authorization", $"Bearer {token}");
}
```

---

## 🧪 Testing

### Test Connection:

```csharp
// در یک Controller یا Handler:
var pool = await _context.Commissions.GetWeeklyCommissionPoolAsync(
    new GetWeeklyCommissionPoolRequest { WeekNumber = "2025-W48" });

Console.WriteLine($"Total Pool Value: {pool.TotalPoolValue}");
Console.WriteLine($"Active Members: {pool.ActiveMembersCount}");
```

**Expected Output**:
```
Total Pool Value: 50000000
Active Members: 120
```

---

### Test with Postman/Swagger:

1. Start BackOffice.BFF:
   ```bash
   cd /home/masoud/Apps/project/FourSat/BackOffice.BFF/src
   dotnet run --project BackOffice.BFF.WebApi
   ```

2. Call API endpoint (example):
   ```http
   GET /api/commission/weekly-pool?weekNumber=2025-W48
   Authorization: Bearer {your-token}
   ```

3. Expected Response:
   ```json
   {
     "weekNumber": "2025-W48",
     "totalPoolValue": 50000000,
     "activeMembersCount": 120,
     "isCalculated": true
   }
   ```

---

## 📊 Status & Metrics

| Component | Status | Version | Notes |
|-----------|--------|---------|-------|
| **CMS Protobuf Package** | ✅ Active | 0.0.140 | With Network-Club-Commission |
| **gRPC Connection** | ✅ Configured | - | https://cms.kbs1.ir |
| **Auto-Registration** | ✅ Active | - | Via BatchRegisterGrpcClients |
| **Commission Client** | ✅ Ready | - | All commands & queries available |
| **Network Client** | ✅ Ready | - | Binary tree queries available |
| **Club Client** | ✅ Ready | - | Activation/Deactivation available |
| **Authentication** | ✅ Configured | JWT | Via ITokenProvider |

---

## 🔗 Related Documentation

### CMS Side:
- **Implementation Progress**: `/CMS/docs/implementation-progress.md`
- **Network System Design**: `/CMS/docs/network-club-commission-system.md`
- **Monitoring Setup**: `/CMS/docs/monitoring-alerts-consolidated-report.md`
- **Migration Guide**: `/CMS/docs/migration-network-parent-guide.md`
- **Binary Tree Registration**: `/CMS/docs/binary-tree-registration-guide.md`

### BFF Side:
- **This Document**: `/BackOffice.BFF/docs/cms-integration.md`
- **README**: `/BackOffice.BFF/README.md`

---

## 🚀 Next Steps

### Immediate:
1. ✅ Integration completed
2. ⏳ Create Commission/Network/Club CQRS handlers in BFF
3. ⏳ Add API endpoints in BackOffice.BFF.WebApi
4. ⏳ Test integration with real data

### Short-term:
5. ⏳ Add Swagger documentation for new endpoints
6. ⏳ Implement error handling for gRPC calls
7. ⏳ Add logging for commission operations
8. ⏳ Create admin dashboard for network visualization

### Long-term:
9. ⏳ Add real-time notifications (SignalR) for commission updates
10. ⏳ Implement caching for frequently accessed data
11. ⏳ Add reporting/analytics endpoints
12. ⏳ Performance optimization for large network trees

---

## 📞 Troubleshooting

### Issue 1: gRPC Connection Failed

**Error**: `Status(StatusCode="Unavailable", Detail="...")`

**Solutions**:
1. Check CMS service is running: `https://cms.kbs1.ir`
2. Verify network connectivity
3. Check firewall settings
4. Verify SSL certificate is valid

---

### Issue 2: Authentication Failed

**Error**: `Status(StatusCode="Unauthenticated", Detail="...")`

**Solutions**:
1. Verify `ITokenProvider` is registered in DI
2. Check JWT token is valid and not expired
3. Verify token has correct claims/permissions
4. Check Authorization header is being sent

---

### Issue 3: Package Version Mismatch

**Error**: `The type or namespace 'CommissionContract' could not be found`

**Solutions**:
1. Update package version in `.csproj`:
   ```xml
   <PackageReference Include="Foursat.CMSMicroservice.Protobuf" Version="0.0.140" />
   ```
2. Run `dotnet restore`
3. Clean and rebuild solution

---

### Issue 4: Method Not Found

**Error**: `Method 'GetWeeklyPool' not found on service 'CommissionContract'`

**Solutions**:
1. Verify CMS service has the latest code deployed
2. Check Protobuf contract matches between CMS and BFF
3. Update both CMS and BFF to latest versions
4. Restart both services

---

## 🎯 Summary

### ✅ Completed:
- CMS Protobuf package updated to 0.0.140
- 3 new gRPC clients added to BFF:
  * CommissionContract (8+ methods)
  * NetworkMembershipContract (6+ methods)
  * ClubMembershipContract (4+ methods)
- Auto-registration configured
- Authentication via JWT configured
- Build successful (0 errors)

### ⏳ Pending:
- Create CQRS handlers for Commission operations
- Create CQRS handlers for Network operations
- Create CQRS handlers for Club operations
- Add API Controllers/Endpoints
- Add Swagger documentation
- Integration testing

### 🔑 Key Points:
- **No manual registration needed**: gRPC clients auto-register via `BatchRegisterGrpcClients()`
- **Authentication handled**: JWT token automatically added to all requests
- **Type-safe**: All Protobuf contracts are strongly typed
- **Easy to use**: Simple interface via `IApplicationContractContext`

---

**Last Updated**: 2025-11-30  
**Build Status**: ✅ Success  
**Ready for**: Handler implementation & API endpoint creation