admin/docs

Files

T

masoodafar-web 39590d2cbe docs: Phase 10 — DataMigration + EF Staging + PackagePurchaseDialog + UI Fixes

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

2026-02-27 20:56:00 +03:30

9.5 KiB

Raw Blame History

🔄 مهاجرت داده، 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)

۲.۱ قبل

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

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

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)

۳.۱ قبل

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

۳.۲ بعد

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%

9.5 KiB Raw Blame History Unescape Escape