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:

✅ 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):

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):

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

// ❌ 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

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

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

Check Errors

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)