masoodafar-web
39590d2cbe
Updated 8 docs: - CHANGELOG: Phase 10a-d (DataMigration tool, EF staging migrations, PackagePurchaseDialog, 4 UI fixes) - PAYMENT-FINANCE: Rial→Toman conversion chain documented, PackagePurchaseDialog status - TECH-02: Added PackagePurchaseDialog to folder structure + status table - TECH-04: DataMigration tool features (smart retry, FK handling, fallback tables), EF staging - PACKAGE-TASKS: Phase 10 graph, NuGet v0.0.189, T4.1+T4.2 marked ✅ - BIZ-PACKAGE: v6→v7, commits updated, T4.1+T4.2 marked ✅ - INDEX: Updated last-update + R3 description - ROADMAP: Progress bars updated, DONE section + NOW section refreshed
259 lines
9.5 KiB
Markdown
259 lines
9.5 KiB
Markdown
# 🔄 مهاجرت داده، 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% |
|