docs/MIGRATION-PROGRESS.md

# Migration Progress: FrontOffice.BFF → CMS Direct Integration

## Date: 2026-02-01

## Overview
Migration of FrontOffice from BFF layer to direct CMS microservice integration to eliminate unnecessary abstraction layer and improve architecture.

---

## Migration Strategy

### Discovery Phase
- **Key Finding**: BFF was acting as a DTO transformation layer
- **Insight**: BFF proto files serve as specification for frontend requirements
- **Approach**: Systematically compare BFF proto structures with CMS and add missing fields

### Field Aliasing Strategy
Proto3 doesn't support field number reuse, so we use unique field numbers for alias fields:
- Original fields keep their numbers (e.g., `name = 2`, `image_url = 8`)
- Alias fields get new numbers (e.g., `title = 12`, `image_path = 13`)
- Both fields must be populated in service implementations

---

## Completed Work

### ✅ Phase 1: Infrastructure Setup
- Changed URL from `localhost:32845` (BFF) to `localhost:32846` (CMS)
- Consolidated multiple BFF proto packages into single `Foursat.CMSMicroservice.Protobuf`
- Implemented Customer-prefixed API methods for frontend access

### ✅ Phase 2: Proto Package Updates

#### Version 0.0.171 (Successful)
- Added `models` field aliases in response types:
  - `GetAllCategoriesForCustomerResponse`: `categories` → `models` (field 2)
  - `GetCustomerPackagesResponse`: `packages` → `models` (field 1)
  - `GetAllUserCartsResponse`: `items` → `models` (field 1)
- Added missing fields:
  - `GetUserForCustomerResponse.token` (field 16)
  - `GetClubMembershipResponse.status` (field 11)
  - `GetClubMembershipResponse.days_remaining` (field 12)
- Removed duplicate validators in `CMSMicroservice.Protobuf/Validator/UserCarts/`

#### Version 0.0.172 (Current)
**Proto Changes:**
- **package.proto**: Added `title` (field 12) and `image_path` (field 13) to `CustomerPackageModel`
- **usercarts.proto**: 
  - Added `user_cart_id` (field 11) alias to `UpdateUserCartRequest`
  - Added `product_short_infomation` (field 14) typo alias to `UserCartItem`
  - Added `created` timestamp (field 10) to `UserCartItem`
- **networkmembership.proto**: Added to `NetworkTreeNodeModel`:
  - `full_name` (field 20) - alias for user_name
  - `level` (field 21) - alias for network_level
  - `mobile` (field 14)
  - `avatar` (field 15)
  - `position` (field 16)
  - `left_child` (field 17)
  - `right_child` (field 18)

**Service Implementation Changes:**
- Updated `PackageService.GetCustomerPackageDetails` to populate:
  - `Title = "پکیج طلایی"` (duplicate of Name)
  - `ImagePath = "/images/packages/golden-detail.jpg"` (duplicate of ImageUrl)

**Build Status:**
```bash
✅ Proto build: Success
✅ Pack version 0.0.172: Success
✅ Package location: /home/masoud/Apps/project/FourSat/nupkg/Foursat.CMSMicroservice.Protobuf.0.0.172.nupkg
✅ FrontOffice.Main.csproj updated to version 0.0.172
```

### ✅ Phase 3: Error Reduction
- **Initial**: 250+ compilation errors
- **After 0.0.171**: 217 errors
- **After 0.0.172**: **170 errors** ⬇️ (32% reduction)

---

## Remaining Work

### ⚠️ Critical Issues (170 Errors)

#### 1. Missing Service Methods (8 methods)
Need to be added to CMS proto services:

**ConfigurationContract:**
- `GetClubConfigurationAsync`
- `GetClubFeaturesAsync`

**CommissionContract:**
- `GetMyCommissionPayoutsAsync`
- `GetMyWeeklyBalancesAsync`

**NetworkMembershipContract:**
- `GetMyNetworkTreeAsync`
- `GetSubordinateTreeAsync`
- `GetMyNetworkStatisticsAsync`

**UserOrderContract:**
- `GetVATRateAsync`

#### 2. Missing Proto Fields

**GetWeekDefinitionsRequest** (5 fields):
```protobuf
int32 page_number = ?;
int32 page_size = ?;
string search_text = ?;
google.protobuf.Int32Value persian_year = ?;
google.protobuf.Int32Value gregorian_year = ?;
google.protobuf.BoolValue is_active = ?;
```

**WeekDefinitionItem** (2 fields):
```protobuf
string start_date_persian = ?;
string end_date_persian = ?;
```

#### 3. Type Conversion Issues

**PaginationState conflict:**
```
Cannot implicitly convert type 'CMSMicroservice.Protobuf.Protos.PaginationState' 
to 'CMSMicroservice.Protobuf.Protos.City.PaginationState'
```
Location: `Pages/Profile/Components/EditAddressDialog.razor.cs(45,35)`

#### 4. Incomplete Alias Population

Fields with aliases need population in ALL service methods:
- `CustomerPackageModel.Title` / `ImagePath` (partially done)
- `NetworkTreeNodeModel.FullName` / `Level`
- Other alias fields across services

---

## Technical Decisions

### Proto Field Number Strategy
**Problem**: Proto3 doesn't allow field number reuse for aliases
```protobuf
// ❌ This doesn't work:
string name = 2;
string title = 2; // ERROR: Field number 2 already used

// ✅ Solution:
string name = 2;
string title = 12;  // New unique number
```

### Why Not Update Frontend?
**Preserving Business Logic**: User requirement is "چیزی کم نشه از بیزینس" (don't lose any business logic). Changing frontend field names risks:
- Breaking existing functionality
- Missing edge cases in BFF transformation logic
- Extensive testing burden

**Field Aliasing Benefits**:
- Zero frontend changes required
- Gradual migration path
- Easy rollback if needed
- Maintains backward compatibility

---

## Next Steps

### Priority 1: Add Missing Methods
1. Define proto service methods in CMS `.proto` files
2. Implement method stubs in CMS service classes
3. Return mock/default data initially

### Priority 2: Add Missing Fields
1. Add fields to `GetWeekDefinitionsRequest`
2. Add fields to `WeekDefinitionItem`
3. Rebuild proto package as version 0.0.173

### Priority 3: Fix Type Issues
1. Resolve `PaginationState` namespace conflict
2. Add missing `PaymentGatewayUrl` field
3. Fix `PaymentMethod` enum reference

### Priority 4: Complete Alias Population
1. Populate all alias fields in service responses
2. Ensure data consistency between original and alias fields

---

## Package Version History

| Version | Status | Changes | Errors |
|---------|--------|---------|--------|
| 0.0.170 | Baseline | Initial BFF → CMS migration | 250+ |
| 0.0.171 | ✅ Success | Models aliases, Token field | 217 |
| 0.0.172 | ✅ Success | Title/ImagePath aliases, Network fields | 170 |
| 0.0.173 | Planned | Missing methods and fields | TBD |

---

## Commands Reference

### Build Proto Package
```bash
cd /home/masoud/Apps/project/FourSat/CMS/src/CMSMicroservice.Protobuf
dotnet build
dotnet pack -c Release -p:PackageVersion=0.0.172 -o ../../../nupkg -p:RunPushTarget=false
```

### Update FrontOffice
```bash
cd /home/masoud/Apps/project/FourSat/FrontOffice/src/FrontOffice.Main
# Edit .csproj to update version number
dotnet build
```

### Check Errors
```bash
cd /home/masoud/Apps/project/FourSat/FrontOffice/src/FrontOffice.Main
dotnet build 2>&1 | grep "error CS" | wc -l
dotnet build 2>&1 | grep "error CS" | head -20
```

---

## Lessons Learned

1. **BFF Transformation Discovery**: BFF wasn't just routing - it was transforming DTOs. This is critical business logic.

2. **Proto Field Aliasing**: Proto3 requires unique field numbers. Can't reuse numbers for aliases.

3. **Systematic Approach**: Comparing BFF proto files as specification prevented missing fields.

4. **Incremental Progress**: Breaking work into small packages (0.0.171 → 0.0.172) made debugging easier.

5. **Package Naming**: Real package name is `Foursat.CMSMicroservice.Protobuf`, not `CMSMicroservice.Protobuf`.

---

## Notes

- Post-build push to Nexus disabled with `-p:RunPushTarget=false` due to `--allow-insecure-connections` flag incompatibility
- All changes preserve existing business logic per user requirement
- Field aliases provide backward compatibility during migration
- Final cleanup phase will update frontend to use CMS field names directly (optional future work)