# 🔄 مهاجرت داده، 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`  
> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: DataMigration Tool + EF Staging Migrations)

---

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

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

---

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

### ۲.۱ قبل

```mermaid
flowchart LR
    FO1["FrontOffice"] -->|HTTP/REST| BFF["BFF"]
    BO1["BackOffice"] -->|HTTP/REST| BFF
    BFF -->|gRPC| CMS1["CMS"]
```

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

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

```mermaid
flowchart LR
    FO2["FrontOffice"] -->|gRPC| CMS2["CMS مستقیم"]
    BO2["BackOffice"] -->|gRPC| CMS2
```

**مزایا:** ✅ حذف ۱ سرویس • کاهش ~50ms latency • Type-safety از proto تا UI • ساده‌سازی debug

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

```
مرحله ۱: ایجاد 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)

### ۳.۱ قبل

```mermaid
flowchart LR
    CL1["Client"] --> NG1["nginx"] --> OC["Ocelot Gateway"]
    OC --> CMS3["CMS"]
    OC --> BFF2["BFF"]
    OC --> FS1["FileService"]
```

### ۳.۲ بعد

```mermaid
flowchart LR
    CL2["Client"] --> NG2["nginx"] --> ING["K8s Ingress"]
    ING --> CMS4["CMS"]
    ING --> BO3["BackOffice"]
    ING --> FO3["FrontOffice"]
```

### ۳.۳ دلایل حذف

```
✅ 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 (.NET 9 + Dapper + Polly + Serilog)
│   ├── Program.cs              ← Entry point
│   ├── appsettings.json        ← Source/Target connection strings + TruncateTargetTables
│   ├── Services/
│   │   └── MigrationService.cs ← Smart retry, FK disable/enable, fallback table names
│   ├── Scripts/
│   │   └── PostMigration_DataTransformation.sql ← Guardشده با IF COL_LENGTH/OBJECT_ID
│   └── Mappings/
│       └── TableMappings.cs    ← Source → Target table/column mappings
└── FourSat.GeographySeeder/    ← Seed geography data
    ├── Program.cs
    └── Data/
        ├── provinces.json
        └── cities.json
```

### ۵.۱.۱ ویژگی‌های DataMigration Tool (اسفند ۱۴۰۴)

| ویژگی | توضیح |
|--------|--------|
| **Smart Retry** | فقط خطاهای transient SQL (deadlock, timeout, transport) — نه خطاهای منطقی |
| **FK Disable/Enable** | `ALTER TABLE NOCHECK/CHECK CONSTRAINT ALL` حول هر مهاجرت |
| **TruncateTargetTables** | حل duplicate key (`IX_ClubMembership_UserId`) هنگام re-run |
| **Fallback Table Name** | اگر جدول rename شده (`UserWalletChangeLogs` → `UserWalletHistories`) |
| **PostMigration Guards** | همه مراحل با `IF COL_LENGTH`/`OBJECT_ID` برای سازگاری با هر دو schema |
| **Polly Retry** | exponential backoff (2s, 8s, 32s) + لاگ structured |
| **Serilog** | لاگ فایل + کنسول با جزئیات هر جدول |

> **کامیت‌ها:** `0e8c6fd` → `8385c90` (MERGE fix) → `31cc464` (FK+truncate+PostMigration)
> **وضعیت:** Local only — بدون remote (در workspace `DataMigration/` قرار دارد)

### ۵.۲ 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` | افزایش قیمت ۱۰% |

### ۵.۴ Migrationهای EF Core اجراشده روی Production/Staging (اسفند ۱۴۰۴)

| Migration | توضیح | DB |
|-----------|--------|----||
| `ExpandDiscountProductFullInformation` | گسترش فیلدهای محصول تخفیفی | KBS (Production `45.149.79.127`) |
| `AddMagicWalletFields` (u21) | فیلدهای کیف‌پول جادویی + ClubMembershipCycle | KBS (Production) |
| ۵۵ migration کامل | از Initial تا `Q27_HistoryTables_And_RenameWalletHistory` | KBS Staging (`185.252.31.42,2019/KBS`) |
| ۵۵ migration کامل | از Initial تا `Q27_HistoryTables_And_RenameWalletHistory` | App DB (`194.5.195.53,31433/Foursat`) |

> ✅ **نکته:** CMS به ۲ DB مختلف وصل می‌شود — هر دو باید migrate شوند.
> ✅ Migration `u21` در زمان merge تکراری بود — فایل تکراری حذف شد.

---

## ۶. 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% |
| EF Migration پروداکشن | ✅ | 100% |
| DataMigration Tool (Prod→Staging) | ✅ | 100% |
| EF Migration استیجینگ (KBS + Foursat) | ✅ | 100% |