docs/technical/TECH-04-MIGRATION.md

🔄 مهاجرت داده، BFF و Gateway

منابع ادغام‌شده: BACKOFFICE-BFF-MIGRATION.md, customer-facing-capabilities-codex.md, DATA-TABLE-MAPPINGS.md, DATAMIGRATION-README.md, FRONTOFFICE-TO-CMS-MIGRATION.md, GATEWAY-REMOVAL-MIGRATION-PLAN.md, MIGRATION-PROGRESS.md
آخرین بروزرسانی: اسفند ۱۴۰۴

---

۱. تاریخچه مهاجرت‌ها

Timeline:
    ▸ فاز ۱: FrontOffice REST → CMS gRPC (مستقیم)
    ▸ فاز ۲: BackOffice REST → CMS gRPC (مستقیم)
    ▸ فاز ۳: حذف BFF/Gateway
    ▸ فاز ۴: حذف API Gateway (Ocelot)
    ▸ فاز ۵: یکپارچه‌سازی Proto packages
    ▸ فاز ۶: Data migration از سیستم قدیم

---

۲. حذف BFF (Backend-for-Frontend)

۲.۱ قبل

FrontOffice ──HTTP/REST──→ BFF ──gRPC──→ CMS
BackOffice  ──HTTP/REST──→ BFF ──gRPC──→ CMS

BFF مسئولیت‌ها:
    • تبدیل REST↔gRPC
    • Aggregation
    • Auth proxy
    • Rate limiting

۲.۲ بعد (فعلی)

FrontOffice ──gRPC──→ CMS (مستقیم)
BackOffice  ──gRPC──→ CMS (مستقیم)

مزایا:
    ✅ حذف ۱ سرویس از deployment
    ✅ کاهش ~50ms latency per request
    ✅ Type-safety از proto تا UI
    ✅ ساده‌سازی debug و logging
    ✅ کاهش maintenance cost

۲.۳ مراحل مهاجرت

مرحله ۱: ایجاد gRPC client wrappers در FrontOffice
    ProductService.cs → _client.GetProductsAsync(request)
    OrderService.cs → _client.GetOrdersAsync(request)
    ...

مرحله ۲: جایگزینی HttpClient با GrpcChannel
    services.AddGrpcClient<ProductServiceClient>(o => {
        o.Address = new Uri(config["Grpc:CmsUrl"]);
    });

مرحله ۳: حذف BFF project
    - حذف BFF از solution
    - حذف BFF از docker-compose
    - حذف BFF از K8s manifests

مرحله ۴: تست end-to-end
    - تست هر صفحه FrontOffice
    - تست هر صفحه BackOffice
    - Performance benchmark

---

۳. حذف API Gateway (Ocelot)

۳.۱ قبل

Client → nginx → Ocelot Gateway → { CMS, BFF, FileService }
         ↑
    URL routing, rate limiting, auth

۳.۲ بعد

Client → nginx → Ingress → { CMS, BackOffice, FrontOffice }
         ↑
    Path-based routing in Ingress

۳.۳ دلایل حذف

✅ Ocelot maintenance burden → حذف
✅ K8s Ingress → routing بومی
✅ Let's Encrypt → TLS بومی
✅ gRPC → type-safe بدون نیاز به gateway

---

۴. FrontOffice to CMS Migration

۴.۱ Service Mapping

FrontOffice Service	BFF Endpoint (حذف‌شده)	CMS gRPC Service
ProductService	GET /api/products	ProductService.GetProducts
OrderService	POST /api/orders	OrderService.CreateOrder
UserService	POST /api/auth/login	UserService.Login
ClubService	GET /api/club/tree	ClubService.GetNetworkTree
BlogService	GET /api/blog/posts	BlogService.GetPosts
PaymentService	POST /api/payment/create	PaymentService.CreatePayment
FileService	POST /api/files/upload	FileService.Upload
SitePageService	GET /api/pages/{type}	SitePageService.GetPage

۴.۲ DTO Mapping

BFF DTOs (حذف‌شده) → Proto Messages (فعلی)
    ProductDto → ProductMessage
    OrderDto → OrderMessage
    UserDto → UserMessage
    
Proto-generated classes مستقیم در UI استفاده می‌شوند
یا به local DTOs map می‌شوند (برای UI-specific fields)

---

۵. Data Migration (سیستم قدیم → جدید)

۵.۱ پروژه DataMigration

DataMigration/
├── FourSat.DataMigration/      ← Console app
│   ├── Program.cs
│   ├── Migrators/
│   │   ├── UserMigrator.cs
│   │   ├── ProductMigrator.cs
│   │   ├── OrderMigrator.cs
│   │   └── ClubMigrator.cs
│   └── Mappings/
│       └── TableMappings.cs
└── FourSat.GeographySeeder/    ← Seed geography data
    ├── Program.cs
    └── Data/
        ├── provinces.json
        └── cities.json

۵.۲ Data Table Mappings

جدول مبدأ (قدیم)	جدول مقصد (CMS)	نکات
dbo.Users	CMS.Users	PhoneNumber as primary identifier
dbo.Products	CMS.Products	ImageUrl migration needed
dbo.Orders	CMS.Orders	Status enum remapping
dbo.Categories	CMS.Categories	Hierarchical → ParentId
dbo.NetworkTree	CMS.Users	Binary tree via NetworkParentId + LegPosition روی User
dbo.Wallets	CMS.UserWallets	۳ wallet types: Balance, NetworkBalance, DiscountBalance
dbo.Transactions	CMS.Transactions	Type enum remapping
dbo.Memberships	CMS.UserClubMemberships	+ Contract creation

۵.۳ SQL Scripts مهاجرت

اسکریپت	کاربرد
MigrateUsersToClubMembership.sql	انتقال همه کاربران
MigrateSpecificUsersToClubMembership.sql	انتقال انتخابی
ChargeUserWallets.sql	شارژ اولیه کیف‌پول‌ها
AddIsActiveToUserClubFeatures.sql	افزودن فیلد IsActive
SeedSitePages.sql	داده اولیه صفحات سایت
SystemConfigurations.sql	مقادیر پیش‌فرض تنظیمات
populate-weekly-commission-pools.sql	داده تاریخی Pool
update_products_price_10_percent.sql	افزایش قیمت ۱۰%

---

۶. Geography Seeder

FourSat.GeographySeeder:
    • ۳۱ استان
    • ~۱۲۰۰ شهر
    • منبع: دیتای رسمی تقسیمات کشوری
    • فرمت: JSON → EF Core Seed
    
استفاده:
    dotnet run --project FourSat.GeographySeeder

---

۷. Customer-Facing Capabilities Codex

۷.۱ خلاصه (بزرگ‌ترین سند — ۵,۳۰۰ خط)

این سند شامل مستندسازی کامل تمام قابلیت‌های کاربرمحور سیستم است:

بخش	محتوا
User Journey	فلوی کامل از ثبت‌نام تا خرید
Store Features	لیست محصول، فیلتر، سبد، پرداخت
Club Features	عضویت، درخت، کمیسیون، قرارداد
Content	بلاگ، صفحات، SEO
Admin Features	مدیریت محصول، سفارش، کاربر
Integration	Chatika، ZarinPal، Kavenegar، Daya
Mobile	Responsive، PWA (planned)

---

۸. وضعیت مهاجرت

مهاجرت	وضعیت	درصد
FrontOffice BFF → gRPC	✅	100%
BackOffice BFF → gRPC	✅	100%
API Gateway حذف	✅	100%
Data Migration (Users)	✅	100%
Data Migration (Products)	✅	100%
Data Migration (Orders)	✅	100%
Data Migration (Club/Network)	✅	100%
Geography Seeder	✅	100%
Proto package unification	✅	100%