docs/04-FRONTEND/FrontOffice/todo-commented-code.md

🔴 TODO: کدهای کامنت شده که باید تکمیل شوند

تاریخ: ۱۴ آذر ۱۴۰۴

این فایل لیست کامل کدهایی است که برای Build موفق، موقتا کامنت شده‌اند.

---

❌ مشکل اصلی: Protobuf ناقص در FrontOffice.BFF

تمام مشکلات زیر به دلیل عدم وجود Protobuf packages برای ماژول‌های جدید است.

---

1️⃣ WalletService.cs (4 متد کامنت شده)

📁 مسیر: /FrontOffice/src/FrontOffice.Main/Utilities/WalletService.cs

متد 1: GetBalancesAsync() - خط 27

// TODO: DiscountBalance will be added in BFF protobuf later
return new WalletBalances(response.Balance, 0 /* response.DiscountBalance */, response.NetworkBalance);

مشکل: GetUserWalletResponse در protobuf فعلی DiscountBalance ندارد

راه حل:

1. به FrontOffice.BFF.UserWallet.Protobuf بروید
2. فایل userwallet.proto را باز کنید
3. به message GetUserWalletResponse اضافه کنید:
   int64 discount_balance = 3;
4. Protobuf را rebuild و publish کنید
5. در WalletService uncomment کنید

---

متد 2: GetTransactionsAsync() - خط 42-75

// TODO: Implement when BFF protobuf has GetAllUserWalletChangeLog
await Task.CompletedTask;
return new List<WalletTransaction>();
/*
var request = new GetAllUserWalletChangeLogRequest();
// ... کد کامل کامنت شده
*/

مشکل: متد GetAllUserWalletChangeLog در UserWalletContract وجود ندارد

راه حل:

1. به FrontOffice.BFF.Application/UserWalletCQ بروید
2. Query جدید بسازید: GetAllUserWalletChangeLog
   - Request: ReferenceId?, IsIncrease?
   - Response: List<WalletChangeLogDto>
3. به userwallet.proto اضافه کنید:
   rpc GetAllUserWalletChangeLog(GetAllUserWalletChangeLogRequest) returns (GetAllUserWalletChangeLogResponse);
4. Handler را پیاده کنید با فراخوانی CMS
5. Protobuf را rebuild/publish کنید
6. در WalletService uncomment کنید

---

متد 3: RequestWithdrawalAsync() - خط 107-127

public async Task<bool> RequestWithdrawalAsync(long payoutId, WithdrawalMethodClient method, string? iban)
{
    // TODO: Implement when BFF protobuf has WithdrawBalance
    await Task.CompletedTask;
    return false;
    /*
    var request = new WithdrawBalanceRequest { ... };
    await _client.WithdrawBalanceAsync(request);
    */
}

مشکل: متد WithdrawBalance در UserWalletContract وجود ندارد

راه حل:

1. به FrontOffice.BFF.Application/UserWalletCQ بروید
2. Command جدید بسازید: WithdrawBalance
   - Request: PayoutId, WithdrawalMethod, IbanNumber?
   - Response: Success, Message
3. به userwallet.proto اضافه کنید:
   rpc WithdrawBalance(WithdrawBalanceRequest) returns (WithdrawBalanceResponse);
4. Handler را پیاده کنید با فراخوانی CMS.WithdrawCommissionBalance
5. Protobuf را rebuild/publish کنید
6. در WalletService uncomment کنید

---

متد 4: GetWithdrawalsAsync() - خط 136-160

// TODO: Implement when BFF protobuf has GetUserWithdrawals
await Task.CompletedTask;
return new List<WalletWithdrawal>();
/*
var request = new GetUserWithdrawalsRequest();
var response = await _client.GetUserWithdrawalsAsync(request);
*/

مشکل: متد GetUserWithdrawals در UserWalletContract وجود ندارد

راه حل:

1. به FrontOffice.BFF.Application/UserWalletCQ بروید
2. Query جدید بسازید: GetUserWithdrawals
   - Request: Status?
   - Response: List<WithdrawalDto>
3. به userwallet.proto اضافه کنید:
   rpc GetUserWithdrawals(GetUserWithdrawalsRequest) returns (GetUserWithdrawalsResponse);
4. Handler را پیاده کنید با فراخوانی CMS
5. Protobuf را rebuild/publish کنید
6. در WalletService uncomment کنید

---

متد 5: GetWithdrawalSettingsAsync() - خط 163-170

// TODO: Implement when BFF protobuf has GetWithdrawalSettings
await Task.CompletedTask;
return new WithdrawalSettings(1_000_000);
// var response = await _client.GetWithdrawalSettingsAsync(new Empty());

مشکل: متد GetWithdrawalSettings در UserWalletContract وجود ندارد

راه حل:

1. به FrontOffice.BFF.Application/UserWalletCQ بروید
2. Query جدید بسازید: GetWithdrawalSettings
   - Request: Empty
   - Response: MinWithdrawalAmount
3. به userwallet.proto اضافه کنید:
   rpc GetWithdrawalSettings(google.protobuf.Empty) returns (GetWithdrawalSettingsResponse);
4. Handler را پیاده کنید با فراخوانی CMS settings
5. Protobuf را rebuild/publish کنید
6. در WalletService uncomment کنید

---

2️⃣ ClubMembershipService.cs (Mock Data)

📁 مسیر: /FrontOffice/src/FrontOffice.Main/Utilities/ClubMembershipService.cs

تمام متدها Mock هستند - خط 14-68

// TODO: Replace with actual gRPC call to BFF
// var request = new GetMyClubMembershipRequest();
// var response = await _client.GetMyClubMembershipAsync(request);

مشکل: هیچ gRPC client وجود ندارد

راه حل:

1. FrontOffice.BFF.ClubMembership.Protobuf ساخته شود
2. به ConfigureServices.cs اضافه شود:
   services.AddScoped(CreateAuthenticatedClient<ClubMembershipContract.ClubMembershipContractClient>);
3. در ClubMembershipService inject شود:
   private readonly ClubMembershipContract.ClubMembershipContractClient _client;
4. متدهای Mock جایگزین شوند با gRPC calls

---

3️⃣ NetworkMembershipService.cs (Mock Data)

📁 مسیر: /FrontOffice/src/FrontOffice.Main/Utilities/NetworkMembershipService.cs

تمام متدها Mock هستند - خط 14-105

// TODO: Replace with actual gRPC call to BFF
// var request = new GetMyNetworkTreeRequest { MaxDepth = maxDepth };
// var response = await _client.GetMyNetworkTreeAsync(request);

مشکل: هیچ gRPC client وجود ندارد

راه حل:

1. FrontOffice.BFF.NetworkMembership.Protobuf ساخته شود
2. به ConfigureServices.cs اضافه شود:
   services.AddScoped(CreateAuthenticatedClient<NetworkMembershipContract.NetworkMembershipContractClient>);
3. در NetworkMembershipService inject شود
4. متدهای Mock جایگزین شوند با gRPC calls

---

4️⃣ CommissionService.cs (Mock Data)

📁 مسیر: /FrontOffice/src/FrontOffice.Main/Utilities/CommissionService.cs

تمام متدها Mock هستند - خط 14-119

// TODO: Replace with actual gRPC call to BFF
// var request = new GetMyCommissionPayoutsRequest { ... };
// var response = await _client.GetMyCommissionPayoutsAsync(request);

مشکل: هیچ gRPC client وجود ندارد

راه حل:

1. FrontOffice.BFF.Commission.Protobuf ساخته شود
2. به ConfigureServices.cs اضافه شود:
   services.AddScoped(CreateAuthenticatedClient<CommissionContract.CommissionContractClient>);
3. در CommissionService inject شود
4. متدهای Mock جایگزین شوند با gRPC calls

---

📋 اولویت‌بندی کارها

فاز 1: UserWalletCQ (بالاترین اولویت) ⚡

این ماژول قبلا شروع شده ولی ناقص است:

1. ✅ GetUserWallet موجود است
2. ❌ DiscountBalance در Response نیست → اضافه شود
3. ❌ GetAllUserWalletChangeLog وجود ندارد → بساز
4. ❌ WithdrawBalance وجود ندارد → بساز
5. ❌ GetUserWithdrawals وجود ندارد → بساز
6. ❌ GetWithdrawalSettings وجود ندارد → بساز

زمان تخمینی: 4-6 ساعت

---

فاز 2: Protobuf Packages برای ماژول‌های جدید

A. ClubMembershipCQ ✨

پوشه: FrontOffice.BFF/src/FrontOffice.BFF.ClubMembership.Protobuf/
فایل: clubmembership.proto

Messages:
- GetMyClubMembershipRequest (empty)
- GetMyClubMembershipResponse (UserId, IsActive, Status, DaysRemaining)
- ActivateMyClubMembershipRequest (PackageId, ActivationCode, DurationMonths)
- ActivateMyClubMembershipResponse (Success, Message, ActivationDate, AmountPaid)

Service:
service ClubMembershipContract {
  rpc GetMyClubMembership(GetMyClubMembershipRequest) returns (GetMyClubMembershipResponse);
  rpc ActivateMyClubMembership(ActivateMyClubMembershipRequest) returns (ActivateMyClubMembershipResponse);
}

Handler Location: FrontOffice.BFF.Application/ClubMembershipCQ/

• ✅ Queries/GetMyClubMembership (موجود است)
• ✅ Commands/ActivateMyClubMembership (موجود است)

زمان تخمینی: 2 ساعت (فقط Protobuf + publish)

---

B. NetworkMembershipCQ 🌳

پوشه: FrontOffice.BFF/src/FrontOffice.BFF.NetworkMembership.Protobuf/
فایل: networkmembership.proto

Messages:
- GetMyNetworkTreeRequest (MaxDepth)
- NetworkNodeDto (UserId, FullName, Mobile, Avatar, Position, LeftChild, RightChild, Level)
- GetMyNetworkTreeResponse (RootNode, TotalMembers, CurrentDepth)
- GetMyNetworkStatisticsRequest (empty)
- GetMyNetworkStatisticsResponse (LeftLegCount, RightLegCount, TotalMembers, TreeDepth, WeakerLeg, LastMember)

Service:
service NetworkMembershipContract {
  rpc GetMyNetworkTree(GetMyNetworkTreeRequest) returns (GetMyNetworkTreeResponse);
  rpc GetMyNetworkStatistics(GetMyNetworkStatisticsRequest) returns (GetMyNetworkStatisticsResponse);
}

Handler Location: FrontOffice.BFF.Application/NetworkMembershipCQ/

• ✅ Queries/GetMyNetworkTree (موجود است)
• ✅ Queries/GetMyNetworkStatistics (موجود است)

زمان تخمینی: 2-3 ساعت (Protobuf + publish)

---

C. CommissionCQ 💰

پوشه: FrontOffice.BFF/src/FrontOffice.BFF.Commission.Protobuf/
فایل: commission.proto

Messages:
- GetMyCommissionPayoutsRequest (WeekNumber?, Status?, PageNumber, PageSize)
- CommissionPayoutDto (Id, WeekNumber, WeekLabel, BalancesEarned, TotalAmount, AmountFormatted, Status, StatusBadgeColor, DatePersian)
- GetMyCommissionPayoutsResponse (Payouts[], TotalCount, PageNumber, PageSize)
- GetMyWeeklyBalancesRequest (WeekNumber?)
- GetMyWeeklyBalancesResponse (WeekNumber, WeekLabel, LeftBalance, RightBalance, MinBalance, BalanceCount, CalculatedCommission, LeftCarryover, RightCarryover, StartDate, EndDate)

Service:
service CommissionContract {
  rpc GetMyCommissionPayouts(GetMyCommissionPayoutsRequest) returns (GetMyCommissionPayoutsResponse);
  rpc GetMyWeeklyBalances(GetMyWeeklyBalancesRequest) returns (GetMyWeeklyBalancesResponse);
}

Handler Location: FrontOffice.BFF.Application/CommissionCQ/

• ✅ Queries/GetMyCommissionPayouts (موجود است)
• ✅ Queries/GetMyWeeklyBalances (موجود است)

زمان تخمینی: 3 ساعت (Protobuf + publish)

---

🔧 دستورات لازم برای هر Protobuf Package

ساخت Package:

cd FrontOffice.BFF/src/FrontOffice.BFF.ClubMembership.Protobuf
dotnet pack -c Release

Publish به NuGet/Local:

# اگر NuGet Server دارید:
dotnet nuget push bin/Release/Foursat.FrontOffice.BFF.ClubMembership.Protobuf.0.0.1.nupkg -s http://your-nuget-server

# یا اضافه به Local Source:
dotnet nuget add source /path/to/packages --name LocalPackages

استفاده در FrontOffice.Main:

<PackageReference Include="Foursat.FrontOffice.BFF.ClubMembership.Protobuf" Version="0.0.1" />
<PackageReference Include="Foursat.FrontOffice.BFF.NetworkMembership.Protobuf" Version="0.0.1" />
<PackageReference Include="Foursat.FrontOffice.BFF.Commission.Protobuf" Version="0.0.1" />

---

⏱️ تخمین زمان کلی

مرحله	زمان	اولویت
UserWalletCQ تکمیل	4-6 ساعت	🔴 بالا
ClubMembership Protobuf	2 ساعت	🟡 متوسط
NetworkMembership Protobuf	2-3 ساعت	🟡 متوسط
Commission Protobuf	3 ساعت	🟡 متوسط
FrontOffice integration	2 ساعت	🟢 پایین
جمع کل	13-16 ساعت

---

📝 نکات مهم

1. همه Handler ها در BFF آماده هستند - فقط Protobuf لازم است
2. WalletService اولویت دارد - زیرا صفحه Wallet قبلا موجود بود
3. Mock Data فعلا کافی است - برای Test UI
4. بعد از Protobuf Publish، فقط uncomment کافی است

---

✅ Checklist اجرایی

مرحله 1: UserWalletCQ

• DiscountBalance به GetUserWalletResponse اضافه شود
• Query: GetAllUserWalletChangeLog ساخته شود
• Command: WithdrawBalance ساخته شود
• Query: GetUserWithdrawals ساخته شود
• Query: GetWithdrawalSettings ساخته شود
• Protobuf rebuild/publish شود
• WalletService uncomment شود

مرحله 2: ClubMembership Protobuf

• پوشه Protobuf ساخته شود
• clubmembership.proto نوشته شود
• csproj تنظیم شود
• Build و publish شود
• به FrontOffice.Main اضافه شود
• ClubMembershipService uncomment شود

مرحله 3: NetworkMembership Protobuf

• پوشه Protobuf ساخته شود
• networkmembership.proto نوشته شود
• Build و publish شود
• NetworkMembershipService uncomment شود

مرحله 4: Commission Protobuf

• پوشه Protobuf ساخته شود
• commission.proto نوشته شود
• Build و publish شود
• CommissionService uncomment شود

---

📅 آخرین بروزرسانی: ۱۴ آذر ۱۴۰۴ 👤 توسط: GitHub Copilot (Claude Sonnet 4.5)