docs/05-TASKS/CURRENT-SPRINT.md

🎯 اسپرینت جاری (Current Sprint)

تاریخ شروع: ۱۴ آذر ۱۴۰۴
آخرین بروزرسانی: ۲۸ آذر ۱۴۰۴
مدت: 2 هفته
هدف: تکمیل BackOffice UI و رفع Anti-Patterns معماری

---

🔧 تغییرات اخیر (۲۸ آذر) - Session 2

✅ سیستم مدیریت موجودی محصولات

CMS Handler: چک موجودی در SubmitShopBuyOrderCommandHandler

• چک موجودی قبل از تأیید سفارش
• کاهش RemainingCount و افزایش SaleCount بعد از پرداخت
• پیام خطای فارسی با جزئیات محصول و تعداد

FrontOffice ProductDetail:

• MaxQty داینامیک بر اساس موجودی واقعی
• نمایش Chip موجودی (سبز/قرمز) با تعداد
• غیرفعال کردن دکمه افزودن وقتی ناموجود

✅ ویژگی‌های باشگاه (ClubFeatures) - اصلاح معماری

حذف فیلدها از UserClubFeature:

• DetailedDescriptionHtml, Icon, Color فقط در ClubFeature (جدول قالب)
• UserClubFeature فقط: IsActive, GrantedAt, Notes

فایل‌های اصلاح‌شده:

• CMS: UserClubFeatureDto, clubmembership.proto, ClubFeatureProfile
• BFF: GetClubFeaturesQueryHandler, GetClubFeaturesResponseDto, configuration.proto, ConfigurationProfile
• FrontOffice: ClubConfigurationService, FeaturesPage

MembershipPage - مزایای عضویت:

1. شارژ ۵۶ میلیون تومان کیف پول فروشگاه تخفیفی
2. عضویت در شبکه بازاریابی و دریافت پورسانت
3. امکان جذب زیرمجموعه

✅ رفع باگ مدال آدرس‌ها

• Snackbar تکراری: حذف inject از code-behind (global در _Imports.razor)
• NullReferenceException: null check برای dialog.Result

✅ VAT و Cart Services

• VATService: نرخ پیش‌فرض 9.99% برای debug
• CartService: EnsureInitializedAsync + IsAuthenticatedAsync برای لود فقط برای کاربران لاگین‌شده

---

🔧 تغییرات قبلی (۲۸ آذر) - Session 1

✅ نمودار درختی شبکه در FrontOffice با d3-org-chart

کتابخانه‌ها: d3-org-chart v3 + d3.js v7 + d3-flextree v2.1.2 ویژگی‌ها:

• نمایش درختی باینری شبکه
• کلیک روی نود → نمایش درخت زیرمجموعه
• دکمه بازگشت به نود قبلی
• دکمه "درخت من" برای بازگشت به درخت کاربر
• انتخاب عمق درخت با MudSelect (2-10 سطح)
• FitToScreen برای تناسب با صفحه
• Responsive با MudBlazor components

✅ API جدید GetSubordinateTree

Proto: GetSubordinateTreeRequest با target_user_id و max_depth BFF Handler: GetSubordinateTreeQueryHandler.cs Frontend Service: GetSubordinateTreeAsync(targetUserId, maxDepth) امنیت: JWT Authentication (بدون check سنگین subordinate)

✅ رفع مشکل Encoding فارسی در Geography

Entity های تغییر یافته: Country, State, City تغییرات Configuration: NVARCHAR با Persian_100_CI_AI collation Migration: FixPersianCollation_Geography

---

🔧 تغییرات قبلی (۱۷ آذر)

✅ رفع Anti-Pattern معماری در BackOffice.BFF

مشکل: BackOffice.BFF.WebApi از پکیج‌های Protobuf مربوط به CMS استفاده می‌کرد راه‌حل:

• ساخت Protobuf های اختصاصی BackOffice.BFF (ClubMembership, Commission, Configuration, NetworkMembership)
• تغییر namespace از CMSMicroservice به Foursat.BackOffice.BFF.*
• تغییر GrpcServices از "Client" به "Both" (برای پشتیبانی هم از Server و هم Client)
• نسخه‌های منتشر شده: 0.0.6 (ClubMembership, Commission, NetworkMembership), 1.0.6 (Configuration)

✅ اضافه شدن HTTP Annotations به Protobuf

• افزودن google/api/annotations.proto به 4 پروژه Protobuf
• پیاده‌سازی HTTP endpoints برای Swagger: 33 endpoint
  • ClubMembership: 7 endpoints
  • Commission: 14 endpoints
  • Configuration: 5 endpoints
  • NetworkMembership: 7 endpoints
• نصب Google.Api.CommonProtos v2.10.0

✅ رفع مشکل Mapster با Immutable Types

• ساخت NetworkMembershipProfile.cs با استفاده از MapWith()
• مپینگ دستی برای RepeatedField و Timestamp
• رفع خطای "Cannot convert immutable type"

✅ پشتیبانی از Multi-Role Authorization

• تغییر AuthorizationService برای خواندن چندین رول از JWT
• اضافه شدن متد GetUserRolesAsync()
• استفاده از user.FindAll(ClaimTypes.Role) بجای FindFirst
• پشتیبانی از رول‌های آرایه‌ای در ApiAuthenticationStateProvider

✅ نمایش درختی شبکه (Network Tree Visualization)

• پیاده‌سازی درخت تعاملی با D3.js v7
• ویژگی‌های درخت:
  • Zoom & Pan با mouse/touch
  • دکمه Reset برای بازگشت به حالت اولیه
  • رنگ‌بندی: سبز (فعال), قرمز (غیرفعال), سبز (چپ), نارنجی (راست)
  • کلیک روی node برای بارگذاری درخت آن کاربر
  • Responsive با viewBox و preserveAspectRatio
• اضافه شدن UserAutoComplete برای جستجوی کاربر
  • جستجوی همزمان در Mobile, FirstName, LastName, NationalCode
  • نمایش نام + موبایل در لیست

✅ رفع مشکلات UI

• رفع NullReferenceException در NetworkTreeViewer (JoinedAt null check)
• رفع timing issue در render درخت (StateHasChanged + Task.Delay)
• رفع خطای JSInterop با استفاده از setDotNetReference

---

⚠️ یادآوری مهم: Proto Package Workflow

قبل از هر کاری این را بخوانید!

قانون اجباری برای تغییر Proto (ALL Services):

┌─────────────────────────────────────────┐
│  تغییر Proto File                       │
│         ↓                                │
│  افزایش Version در csproj              │
│         ↓                                │
│  dotnet pack -c Release                 │
│         ↓                                │
│  Update Version در لایه بالاتر          │
└─────────────────────────────────────────┘

این برای همه سرویس‌ها اجباری است:

• ✅ CMS Proto changes → Update BFF
• ✅ BackOffice.BFF Proto changes → Update BackOffice UI
• ✅ FrontOffice.BFF Proto changes → Update FrontOffice UI

عدم رعایت = ساعت‌ها Debug و سردرگمی بیهوده!

GitLab Registry: https://git.afrino.co/api/packages/FourSat/nuget/index.json

---

📋 وضعیت کلی پروژه

Backend:

• ✅ CMS Microservice: ~98% Complete
  • ✅ Daya Loan Integration: 100% Complete (Real API implemented - Dec 6, 2025)
• ✅ BackOffice.BFF: 100% Complete (35+ Handlers)
  • ✅ Architecture Fixed: Anti-pattern با CMS Protobuf رفع شد
  • ✅ HTTP Annotations: 33 endpoint با Swagger support
  • ✅ Mapster Profiles: NetworkMembership, Products با MapWith()
• ✅ FrontOffice.BFF: 98% Complete (همه سرویس‌های مورد نیاز مشتری پیاده‌سازی شده)

Frontend:

• ✅ BackOffice UI: ~97% Complete (65+ صفحه)
  • ✅ Multi-Role Authorization: پشتیبانی از چندین نقش همزمان
  • ✅ Network Tree Visualization: نمایش درختی تعاملی با D3.js
  • ✅ User AutoComplete: جستجوی پیشرفته کاربران
• ✅ FrontOffice UI: 98% Complete (تمام صفحات مورد نیاز مشتری پیاده‌سازی شده)

---

🎉 جمع‌بندی نهایی FrontOffice (سمت مشتری)

✅ صفحات پیاده‌سازی شده و متصل به API:

🔐 احراز هویت:

صفحه	Route	وضعیت
ثبت‌نام (OTP)	/register	✅ متصل به gRPC
ورود (OTP)	Dialog	✅ متصل به gRPC
تایید قرارداد	/register Step 3	✅ متصل به gRPC

👤 پروفایل:

صفحه	Route	وضعیت
داشبورد پروفایل	/profile	✅ متصل به gRPC
ویرایش اطلاعات شخصی	/profile/personal	✅ متصل به gRPC
مدیریت آدرس‌ها	/profile/addresses	✅ متصل به gRPC
تنظیمات	/profile/settings	✅ متصل به gRPC
کیف پول	/profile/wallet	✅ متصل به gRPC
درخت شبکه	/profile/tree	✅ متصل به gRPC

🛒 فروشگاه:

صفحه	Route	وضعیت
لیست محصولات	/products	✅ متصل به gRPC
جزئیات محصول	/products/{id}	✅ متصل به gRPC
دسته‌بندی‌ها	/categories	✅ متصل به gRPC
سبد خرید	/cart	✅ متصل به gRPC
تایید خرید (VAT)	/checkout	✅ متصل به gRPC

📦 سفارشات:

صفحه	Route	وضعیت
لیست سفارشات	/orders	✅ متصل به gRPC
جزئیات سفارش (VAT)	/orders/{id}	✅ متصل به gRPC
پیگیری سفارش	/order-tracking/{id}	✅ متصل به gRPC

💰 کمیسیون:

صفحه	Route	وضعیت
داشبورد کمیسیون	/commission	✅ متصل به gRPC
تاریخچه پرداخت‌ها	/commission/history	✅ متصل به gRPC
تعادل هفتگی	/commission/weekly-balance	✅ متصل به gRPC

🌐 شبکه:

صفحه	Route	وضعیت
آمار شبکه	/network/statistics	✅ متصل به gRPC
درخت شبکه	/profile/tree	✅ متصل به gRPC

🏆 باشگاه:

صفحه	Route	وضعیت
عضویت باشگاه	/club/membership	✅ متصل به gRPC
امکانات باشگاه	/club/features	✅ Static

📦 پکیج‌ها:

صفحه	Route	وضعیت
لیست پکیج‌ها	/packages	✅ متصل به gRPC
پکیج‌های من	/my-packages	✅ متصل به gRPC
جزئیات پکیج	/packages/{id}	✅ متصل به gRPC

📄 سایر صفحات:

صفحه	Route	وضعیت
صفحه اصلی	/	✅ Complete
درباره ما	/about	✅ Static
سوالات متداول	/faq	✅ Static
تماس با ما	/contact	⚠️ UI آماده، Mock

---

⚠️ موارد Mock (نیاز به CMS):

قابلیت	وضعیت UI	نیاز CMS
فرم تماس با ما	✅ UI کامل	Entity ContactMessage
نظرات محصول	❌	Entity Review
کد تخفیف	❌	RPC ValidateDiscountCode

---

❌ موارد حذف شده (نیاز نیست):

قابلیت	دلیل
ChangePassword	سیستم فقط OTP دارد، رمز عبور نداریم
ForgotPassword	سیستم فقط OTP دارد

نکته: صفحه ChangePassword.razor ساخته شده ولی فعلاً کاربردی ندارد چون لاگین فقط با OTP است.

---

📊 مقایسه CMS vs FrontOffice.BFF

سرویس‌های CMS که در FrontOffice.BFF پیاده‌سازی شده:

CMS Service	FrontOffice.BFF	وضعیت
UserService	✅ UserService	کامل
OtpTokenService	✅ (در UserService)	کامل
UserAddressService	✅ UserAddressService	کامل
ProductsService	✅ ProductsService	کامل
CategoryService	✅ CategoriesService	کامل
UserCartsService	✅ ShopingCartService	کامل
UserOrderService	✅ UserOrderService	کامل
UserWalletService	✅ UserWalletService	کامل
TransactionsService	✅ TransactionService	کامل
CommissionService	✅ CommissionService	کامل
ClubMembershipService	✅ ClubMembershipService	کامل
NetworkMembershipService	✅ NetworkMembershipService	کامل
PackageService	✅ PackageService	کامل
DiscountShopServices	✅ DiscountShopService	کامل
UserContractService	✅ (در UserService - AcceptContract)	کامل

سرویس‌های CMS که فقط برای Admin هستند (نیاز مشتری نیست):

CMS Service	توضیح
ConfigurationService	تنظیمات سیستم (Admin)
ContractService	مدیریت قراردادها (Admin)
ManualPaymentService	پرداخت دستی (Admin)
RoleService	مدیریت نقش‌ها (Admin)
UserRoleService	اختصاص نقش (Admin)
TagService	مدیریت تگ‌ها (Admin)
ProductTagService	اختصاص تگ به محصول (Admin)
PublicMessageService	پیام‌های عمومی (Admin)
ProductImagesService	مدیریت تصاویر (Admin)
ProductGalleriesService	گالری محصول (Admin)
ProductCategoryService	دسته‌بندی محصول (Admin)
FactorDetailsService	جزئیات فاکتور (Admin)
UserWalletChangeLogService	لاگ تغییرات کیف پول (Admin)

---

2. ✅ Package Purchase System - UI Implementation

Status: ✅ تکمیل شد
Owner: FrontOffice Team
تاریخ تکمیل: ۱۵ آذر ۱۴۰۴

CMS Status:

• ✅ Entities (5) - PackagePurchase, PackagePurchaseItem, etc.
• ✅ Commands (6) - CreatePackagePurchaseCommand, etc.
• ✅ Queries (3) - GetPackagePurchaseByIdQuery, etc.
• ✅ Protobuf (4 RPCs) - 264 lines

تغییرات انجام شده:

• ✅ PackageService.cs: سرویس gRPC برای دریافت پکیج‌ها
• ✅ RouteConstants.cs: اضافه شدن مسیرهای /packages و /my-packages
• ✅ ConfigureServices.cs: ثبت PackageService در DI
• ✅ Packages.razor: صفحه لیست پکیج‌ها با Grid View، جستجو، و Loading States
• ✅ MyPackages.razor: صفحه پکیج‌های کاربر با نمایش وضعیت خرید

Build Status: ✅ FrontOffice Build Succeeded - 0 Errors

Reference: 01-BUSINESS/package-purchase-system.md

---

3. ✅ اصلاح محاسبه کمیسیون هفتگی (بحرانی)

Status: ✅ تکمیل شد
Owner: CMS Team
تاریخ شروع: ۱۴ آذر ۱۴۰۴
تاریخ تکمیل: ۱۴ آذر ۱۴۰۴

شرح مشکلات رفع شده:

#	مشکل	وضعیت
1	محدودیت لول (15) پیاده‌سازی نشده	✅ Fixed
2	فقط تعادل شخصی حساب می‌شود (نه زیرمجموعه)	✅ Fixed

فرمول پیاده‌سازی شده:

کمیسیون = (تعادل_شخص + SUM(تعادل_زیرمجموعه تا 15 لول)) × ارزش_هر_تعادل

تسک‌های تکمیل شده:

فاز	شرح	وضعیت
1	اضافه کردن Commission.MaxNetworkLevel به Config	✅
2	اصلاح CalculateWeeklyBalancesCommandHandler - محدودیت لول	✅
3	اصلاح ProcessUserPayoutsCommandHandler - تعادل زیرمجموعه	✅
4	تست و Build	✅ (0 Errors)

تغییرات انجام شده:

• Config: اضافه کردن Commission.MaxNetworkLevel = 15
• CalculateWeeklyBalances: پارامتر maxLevel به متدهای بازگشتی اضافه شد
• ProcessUserPayouts: متد SumSubordinateBalancesAsync برای جمع تعادل زیرمجموعه‌ها تا 15 لول

Reference: 01-BUSINESS/commission-calculation-fix.md

---

4. ✅ اصلاح سقف تعادل هفتگی (MaxWeeklyBalances)

Status: ✅ تکمیل شد
Owner: CMS Team
تاریخ تکمیل: ۱۴ آذر ۱۴۰۴

شرح مشکل:

سقف تعادل هفتگی در پیاده‌سازی فعلی 300 کل بود، اما باید 300 برای هر دست باشد.

توضیح	منطق قدیم	منطق جدید
سقف	300 کل	300 هر دست
Max Total	300	300+300=600

تغییرات انجام شده:

CMS Changes:

• ✅ SystemConfiguration: تغییر کلید از MaxWeeklyBalancesPerUser به MaxWeeklyBalancesPerLeg
• ✅ CalculateWeeklyBalancesCommandHandler: اصلاح منطق محاسبه سقف
  • اعمال سقف روی هر دست جداگانه قبل از محاسبه MIN
  • باقیمانده = مازاد سقف هر دست (نه نصف تعادل کل)
• ✅ ApplicationDbContextInitialiser: اصلاح Seed Data

منطق جدید:

// ✅ سقف روی هر دست جداگانه
var cappedLeftTotal = Math.Min(leftTotal, maxBalancesPerLeg);
var cappedRightTotal = Math.Min(rightTotal, maxBalancesPerLeg);
var totalBalances = Math.Min(cappedLeftTotal, cappedRightTotal);
var leftRemainder = leftTotal - cappedLeftTotal;  // مازاد سقف
var rightRemainder = rightTotal - cappedRightTotal;

Build Status: ✅ CMS Build Succeeded - 0 Errors

مستندات:

• ✅ 01-BUSINESS/balance-calculation-rules.md - آپدیت شد

---

🟢 Low Priority (هفته بعد)

5. ✅ VAT System Implementation

Status: ✅ تکمیل شد
Owner: CMS + BFF + FrontOffice UI
تاریخ تکمیل: ۱۵ آذر ۱۴۰۴

تغییرات انجام شده:

CMS:

• ✅ OrderVAT Entity: قبلاً موجود بود
• ✅ GetUserOrderResponseDto: اضافه شدن VatInfo با فیلدهای VatRate, BaseAmount, VatAmount, TotalAmount, IsPaid
• ✅ GetUserOrderQueryHandler: اضافه شدن .Include(i => i.OrderVAT) و mapping VAT
• ✅ CMS Proto: اضافه شدن OrderVATInfo message

FrontOffice.BFF:

• ✅ Proto: اضافه شدن OrderVATInfo و vat_info field
• ✅ GetUserOrderResponseDto: اضافه شدن OrderVATInfoDto

FrontOffice UI:

• ✅ CheckoutSummary.razor: نمایش جزئیات مالی شامل:
  • جمع کالاها
  • مالیات بر ارزش افزوده (۹%)
  • مبلغ قابل پرداخت
• ✅ OrderDetail.razor: نمایش جزئیات مالی مشابه

Build Status: ✅ All Projects - 0 Errors

---

6. Manual Payment System

Status: 🟡 In Progress (CMS + BackOffice.BFF)
Owner: CMS + BackOffice.BFF
Estimate: 2 روز (UI باقیمانده)

وضعیت فعلی:

• ✅ CMS Domain & Application: ManualPayment + CreateManualPayment/ApproveManualPayment/RejectManualPayment + GetAllManualPayments
• ✅ CMS gRPC: ManualPaymentContract (Create/Approve/Reject/GetAllManualPayments)
• ✅ BackOffice.BFF: 4 Handler (CreateManualPayment, ApproveManualPayment, RejectManualPayment, GetManualPayments)
• ⏳ BackOffice UI: صفحه لیست Manual Payments + Dialog جزئیات/Approve/Reject
• ⏳ FrontOffice Flow (CreateManualPaymentRequest از سمت کاربر)

---

7. RBAC System Implementation

Status: 🟡 In Progress (BackOffice.BFF Permission Layer پیاده‌سازی شده؛ CMS + BackOffice UI باقی مانده)
Owner: CMS + BFF Teams
Estimate: 1.5 هفته

Requirements:

• تعریف Roles و Permissions (CMS Domain/Application)
• Policy-based Authorization (CMS + BackOffice UI)
• Admin Panel برای مدیریت دسترسی‌ها
• ✅ BackOffice.BFF: IPermissionService + CheckUserPermissionHandler / GetUserRolesHandler + gRPC PermissionInterceptor

---

⚠️ Blockers & Dependencies

🟢 Resolved:

1. Protobuf Mismatch (FrontOffice.BFF ↔ CMS) ✅ Fixed
2. WalletService Mock Data ✅ Connected to gRPC
3. Tree Builder Missing (NetworkMembership) ✅ Implemented

🟡 Minor Issues:

1. MudBlazor Warnings - ~100 warnings (غیر critical)
2. Missing CMS Entities - Review, ContactMessage, DiscountValidation

---

📊 Progress Summary

✅ وضعیت نهایی FrontOffice (سمت مشتری):

FrontOffice UI: 98% Complete 🎉

• ✅ 28+ صفحه پیاده‌سازی شده
• ✅ همه سرویس‌ها به gRPC متصل
• ✅ Build موفق بدون Error
• ⚠️ فقط فرم تماس با ما Mock است (نیاز به CMS entity)

کارهای تمام شده این اسپرینت (۱۴-۱۵ آذر):

روز اول (۱۴ آذر):

• ✅ FrontOffice Proto Projects: 5 پروژه جدید
• ✅ FrontOffice UI Services: 4 سرویس به gRPC وصل شدند
• ✅ FrontOffice.BFF Handlers: 15+ handler
• ✅ Commission Calculation Fix
• ✅ Balance Cap Fix: 300 per leg

روز دوم (۱۵ آذر):

• ✅ Package Purchase UI: Packages.razor + MyPackages.razor
• ✅ VAT System: CheckoutSummary + OrderDetail
• ✅ OrderTracking: Timeline پیگیری سفارش
• ✅ ChangePassword: UI آماده (برای آینده)
• ✅ Documentation: جمع‌بندی نهایی

---

🗂️ Backlog (کارهای آینده)

Low Priority - FrontOffice:

تسک	توضیحات	اولویت
Password Authentication	اضافه کردن لاگین با رمز عبور علاوه بر OTP	🟡 Low
ForgotPassword	بازیابی رمز عبور (نیاز به CMS RPC)	🟡 Low
Contact Form Backend	اتصال فرم تماس به CMS	🟡 Low
Product Reviews	سیستم نظرات محصول	🟡 Low
Discount Code	اعتبارسنجی کد تخفیف	🟡 Low

High Priority - BackOffice (Admin):

تسک	توضیحات	اولویت
Manual Payment UI	صفحه مدیریت پرداخت‌های دستی	🔴 High
RBAC System	سیستم کنترل دسترسی	🔴 High

---

🎯 Definition of Done

برای هر Task:

• Code Review Complete
• Build با 0 error
• Manual Testing انجام شده
• Documentation بروز شده

---

📝 نتیجه‌گیری نهایی

سمت مشتری (FrontOffice):

✅ آماده Production - تمام قابلیت‌های اصلی پیاده‌سازی شده

سمت ادمین (BackOffice):

🟡 95% Complete - Manual Payment و RBAC باقیمانده

---

آخرین بروزرسانی: ۱۵ آذر ۱۴۰۴ 🚀