docs: update all documentation for Package-Based Transformation Phase 0-4

- OVERVIEW-03-CHANGELOG: Add complete Package-Based section (Phase 0-4) with commit references, add summary table row, update timeline - OVERVIEW-05-ROADMAP: Add Package-Based progress bar (83%), update DONE/NOW sections with Phase 0-4 complete and Phase 5-6 pending - OVERVIEW-02-INDEX: Add 4 new roadmap files to index, update file counts - BIZ-PACKAGE-BASED-SYSTEM: Status → 'در حال پیاده‌سازی — فاز 0-4 تکمیل' with all 7 commit hashes - PACKAGE-TRANSFORMATION-TASKS: Mark Phase 0/1/2 as complete with commit refs, update overview diagram with completion markers
2026-02-26 00:32:33 +03:30
parent 977ef69e26
commit 37330a3e45
5 changed files with 118 additions and 28 deletions
@@ -1,9 +1,10 @@
 # 📦 سیستم مبتنی بر پکیج (Package-Based System)

-> **وضعیت:** تایید‌شده — آماده پیاده‌سازی  
+> **وضعیت:** در حال پیاده‌سازی — **فاز ۰-۴ تکمیل ✅** | فاز ۵-۶ در انتظار  
 > **تاریخ بروزرسانی:** ۷ اسفند ۱۴۰۴  
 > **نسخه:** v5 (قرارداد یک‌بار + فیچر DIFF + تاریخچه فعال‌سازی)  
-> **تاثیرگذاری:** زیاد — **۹۵+** تغییر در ۶ لایه (۵۱ اصلی + ۴۴ سایدافکت)
+> **تاثیرگذاری:** زیاد — **۹۵+** تغییر در ۶ لایه (۵۱ اصلی + ۴۴ سایدافکت)  
+> **کامیت‌ها:** `8b9c317` (Phase 0) → `ae92ab8` (Phase 1) → `a9cd2fd` (Phase 1.5) → `8e5c7c5` (Phase 2) → `ccb938e` (Phase 3) → `0002a5a` (Phase 4)

 ---

@@ -3,8 +3,8 @@
 > **فهرست کامل ۱۵ فایل مستند پروژه FourSat (کارا بازار سلامت)**  
 > **تاریخ تجمیع:** اسفند ۱۴۰۴  
 > **تعداد فایل‌های مبدأ:** ۵۳ فایل (~۳۲,۰۰۰ خط)  
-> **تعداد فایل‌های نهایی:** ۱۷ فایل (۱۵ اصلی + ۲ roadmap)  
-> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (فعال‌سازی درگاه + مرج Production + بهبود UI)
+> **تعداد فایل‌های نهایی:** ۲۲ فایل (۱۵ اصلی + ۷ roadmap/business)  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (تحول پکیج‌بیس فاز ۰-۴ + فعال‌سازی درگاه + مرج Production)

 ---

@@ -35,7 +35,10 @@ totalDoc/
 │
 └── 📁 roadmap/    (فیچرهای جدید — در حال توسعه)
    ├── MAGIC-WALLET-SPEC.md                مشخصات کیف‌پول جادویی
-    └── MAGIC-WALLET-PLAN.md                پلن پیاده‌سازی + checklist
+    ├── MAGIC-WALLET-PLAN.md                پلن پیاده‌سازی + checklist
+    ├── PACKAGE-TRANSFORMATION-TASKS.md     تسک‌های تحول پکیج‌بیس (فاز 0-5)
+    ├── PACKAGE-TRANSFORMATION-UX.md        تاثیر بر UX فرانت‌ها
+    └── FEATURE-BACKLOG.md                  بکلاگ ۱۲ RPC آماده
 ```

 ---
@@ -77,7 +80,11 @@ totalDoc/
 | # | فایل | موضوع | خلاصه |
 |---|------|--------|--------|
 | R1 | [MAGIC-WALLET-SPEC](../roadmap/MAGIC-WALLET-SPEC.md) | کیف‌پول جادویی — مشخصات | State Machine، ضریب ×2.5، سقف 100M، قوانین، API، مدل داده |
-| R2 | [MAGIC-WALLET-PLAN](../roadmap/MAGIC-WALLET-PLAN.md) | کیف‌پول جادویی — پلن | ۶ فاز، **فاز 1-5 تکمیل ✅**، فاز 6 باقی |
+| R2 | [MAGIC-WALLET-PLAN](../roadmap/MAGIC-WALLET-PLAN.md) | کیف‌پول جادویی — پلن | ۶ فاز، **فاز 1-6 تکمیل ✅** |
+| R3 | [PACKAGE-TRANSFORMATION-TASKS](../roadmap/PACKAGE-TRANSFORMATION-TASKS.md) | تحول پکیج‌بیس — تسک‌ها | ۵ فاز، **فاز 0-4 تکمیل ✅**، فاز 5-6 در انتظار |
+| R4 | [PACKAGE-TRANSFORMATION-UX](../roadmap/PACKAGE-TRANSFORMATION-UX.md) | تاثیر بر UX | تحلیل تاثیر بر FrontOffice + BackOffice |
+| R5 | [FEATURE-BACKLOG](../roadmap/FEATURE-BACKLOG.md) | بکلاگ فیچرها | ۱۲ RPC آماده بدون UI، اولویت‌بندی‌شده |
+| R6 | [BIZ-PACKAGE-BASED-SYSTEM](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | طراحی سیستم پکیج‌بیس | v5، ۲۳ تصمیم + ۵۱ تغییر + ۴۴ سایدافکت |

 ---

@@ -1,7 +1,7 @@
 # 📜 تاریخچه کارهای انجام‌شده

 > **همه فعالیت‌های پروژه به صورت بولت با توضیح یک‌خطی و درصد تکمیل**  
-> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: فعال‌سازی درگاه + مرج پروداکشن + بهبود UI ادمین)
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: تحول پکیج‌بیس فاز ۰-۴ + فعال‌سازی درگاه + مرج پروداکشن)

 ---

@@ -11,10 +11,11 @@
 |------|-----------|----------|---------|
 | **BackOffice** | 61 | 60 | **98%** |
 | **FrontOffice** | 40 | 38 | **95%** |
-| **CMS Core** | 58 | 56 | **97%** |
+| **CMS Core** | 72 | 70 | **97%** |
+| **Package-Based System** | 30 | 25 | **83%** |
 | **Deployment** | 22 | 21 | **95%** |
 | **Migration** | 16 | 16 | **100%** |
-| **مجموع** | **197** | **191** | **97%** |
+| **مجموع** | **241** | **230** | **95%** |

 ---

@@ -217,7 +218,79 @@

 ---

-## ۷. Timeline (جدول زمانی)
+## ۷. تحول سیستم پکیج‌بیس (Package-Based Transformation) — 83%
+
+> 📦 تبدیل سیستم تک‌پکیجی hardcoded به معماری چند‌پکیجی داینامیک
+> مرجع: [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | [PACKAGE-TRANSFORMATION-TASKS.md](../roadmap/PACKAGE-TRANSFORMATION-TASKS.md)
+
+### Phase 0 — فیکس باگ‌های فوری ✅ (`8b9c317`, `fe3edd1`)
+- ✅ B1: DiscountBalance شارژ نمی‌شد در VerifyGoldenPackagePurchase — اضافه `DiscountBalance += Amount × 2` + WalletChangeLog
+- ✅ B2: UserPackagePurchase ساخته نمی‌شد در VerifyGoldenPackagePurchase — ساخت record بعد verify
+- ✅ B3: UserPackagePurchase ساخته نمی‌شد در VerifyPackagePurchase — ساخت record
+- ✅ B4: UserPackagePurchase ساخته نمی‌شد در VerifyBasePackagePayment — ساخت record
+- ✅ B6: EXIT Magic Mode — ریست PackagePurchaseMethod + بستن چرخه فعلی
+
+### Phase 1 — زیرساخت Domain ✅ (`ae92ab8`)
+- ✅ T1.1: Package Entity — ۱۱ فیلد جدید (SortOrder, IsActive, IsBasePackage, DiscountMultiplier, MagicWalletMultiplier, ...)
+- ✅ T1.2: PackageFeature Entity — رابطه M:N بین Package و ClubFeature
+- ✅ T1.3: ClubMembership — ۴ فیلد First/Last Activation + PackageId
+- ✅ T1.4-T1.6: اضافه PackageId به ClubMembershipCycle, WeeklyCommissionPool, UserCommissionPayout, NetworkWeeklyBalance, UserWalletChangeLog
+- ✅ T1.7: علامت‌گذاری ۹ SystemConstants به‌عنوان [Obsolete]
+- ✅ T1.8: EF Configurations — Index, Precision, FK relations
+
+### Phase 1.5 — Migration + Data Seed ✅ (`a9cd2fd`)
+- ✅ EF Migration `AddPackageBasedSystem` — ستون‌ها + جداول + ایندکس‌ها
+- ✅ Golden Package Seed (Id=1) — Price=56M, ActivationFee=25.2M, DiscountMultiplier=2.0, MagicWalletMultiplier=2.5
+- ✅ Data Backfill — تمام رکوردهای موجود → PackageId=1
+- ✅ فیکس nullable DateTime/long در ClubMembership
+- ✅ فیکس Shadow FK PackageId1
+
+### Phase 2 — منطق کسب‌وکار ✅ (`8e5c7c5`)
+- ✅ T2.1: ActivateClubMembership — ActivationFee از Package entity
+- ✅ T2.2: AcceptClubMembershipContract — Package features از DB
+- ✅ T2.3: CalculateWeeklyBalances — MaxBalancesPerLeg per-package
+- ✅ T2.4: ProcessUserPayouts — PackageId tracking
+- ✅ T2.5: DayaLoans — Package.Price بجای hardcoded
+- ✅ T2.6: ManualPayment — Package.Price بجای hardcoded
+- ✅ T2.7: InitiateBasePackage/VerifyBasePackage — Package-based
+- ✅ T2.8: ChargeMagicWallet/VerifyMagicWalletCharge — MagicWalletMultiplier per-package
+- ✅ T2.9: OrmCommissionCalculationStrategy — MaxBalancesPerLeg/MaxNetworkLevel per-package
+- ✅ T2.10: ConfigurationService/UserOrderService/UserWalletService — Package reads
+- ✅ **نتیجه:** صفر مصرف SystemConstants deprecated باقی مانده
+
+### Phase 3 — بازسازی لایه Package ✅ (`ccb938e`)
+- ✅ Proto: ۱۱ فیلد جدید در ۵ message (CreateNewPackageRequest, UpdatePackageRequest, GetPackageResponse, ...)
+- ✅ GetUserPackageStatus — پیاده‌سازی (قبلاً NotImplementedException بود!)
+- ✅ CustomerVerifyPackagePurchase — شارژ کیف‌پول اضافه شد (قبلاً missing بود!)
+- ✅ VerifyGoldenPackagePurchase — `package.DiscountMultiplier` بجای hardcoded ×2
+- ✅ GetAllPackageByFilter — فیلتر IsDeleted
+- ✅ GetCustomerPackages — فیلتر IsDeleted + IncludeInactive + SortOrder
+- ✅ GetCustomerPackageDetails — PackageFeatures از DB
+- ✅ GetCustomerPurchaseHistory — Include Transaction
+- ✅ UpdatePackageCommand — ۱۲ فیلد جدید
+
+### Phase 4 — تکمیل CRUD + Legacy Fixes ✅ (`0002a5a`)
+- ✅ CreateNewPackageCommand — ۱۲ فیلد جدید با default‌های مناسب
+- ✅ GetPackageResponseDto — ۱۲ فیلد جدید (Mapster auto-map)
+- ✅ GetAllPackageByFilterResponseModel — ۱۲ فیلد جدید
+- ✅ PurchaseGoldenPackage — حذف Title string match شکننده (`"طلایی"/"golden"`) → `IsDeleted/IsActive/SupportsDirectPurchase`
+- ✅ VerifyPackagePurchase — حذف hardcoded `order.Amount × 2` → `package.DiscountMultiplier` از DB
+
+### Phase 5 — پورسانت per-package ⬜ (در انتظار)
+- ⬜ SP پارامترهای داینامیک (@MaxBalancesPerLeg, @MaxNetworkLevel)
+- ⬜ Loop Service — حلقه روی پکیج‌های فعال
+- ⬜ Carryover مجزا per-package
+
+### Phase 6 — UI ⬜ (در انتظار)
+- ⬜ FrontOffice: کاشی‌های داینامیک پکیج
+- ⬜ FrontOffice: MyPackages + re-purchase
+- ⬜ FrontOffice: Commission Dashboard per-package
+- ⬜ BackOffice: Package CRUD UI
+- ⬜ BackOffice: فیلتر پکیج در گزارش‌ها
+
+---
+
+## ۸. Timeline (جدول زمانی)

 | زمان | رویداد | درصد پروژه |
 |------|--------|-----------|
@@ -232,3 +305,4 @@
 | اسفند ۱۴۰۳ (هفته ۴) | مستندات + نهایی‌سازی | 95% |
 | اسفند ۱۴۰۴ (هفته ۱-۲) | 🪄 کیف‌پول جادویی (فاز 1-6) + اصلاح VAT 10% | 96% |
 | اسفند ۱۴۰۴ (هفته ۳) | 🚀 فعال‌سازی درگاه + بهبود UI ادمین + مرج پروداکشن | 97% |
+| اسفند ۱۴۰۴ (هفته ۴) | 📦 تحول پکیج‌بیس فاز ۰-۴ (Domain + Migration + Business Logic + Package Layer + CRUD) | 95% |
@@ -1,20 +1,21 @@
 # 🗺️ نقشه راه، ریسک‌ها و کارهای باقیمانده

 > **Roadmap + Risk Register + Dependencies + Priorities**  
-> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: فعال‌سازی درگاه + مرج پروداکشن + بهبود UI)
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: تحول پکیج‌بیس فاز ۰-۴ + فعال‌سازی درگاه + مرج پروداکشن)

 ---

 ## ۱. وضعیت فعلی پروژه

 ```
-██████████████████████████████████████████████████ 97%
+██████████████████████████████████████████████████ 95%

 Core Platform     ████████████████████████████████████████████████ 98%
 Club System       ████████████████████████████████████████████████ 98%
 E-Commerce        ████████████████████████████████████████████████ 98%
 Payment           ████████████████████████████████████████████████ 97%
 Magic Wallet      ████████████████████████████████████████████████ 100%
+Package-Based     ████████████████████████████████████████░░░░░░░░ 83%
 UI/UX             █████████████████████████████████████████████░░░ 93%
 Deployment        ██████████████████████████████████████████████░░ 95%
 Documentation     ████████████████████████████████████████████████ 100%
@@ -207,8 +208,11 @@ DONE (اسفند ۱۴۰۴):
    → بهبود UI ادمین (UserAutoComplete + نام کاربر در کیف‌پول) ✅
    → مرج پروداکشن هر ۳ ریپو (CMS + FO + BO) ✅
    → اجرای Migration روی پروداکشن ✅
+    → 📦 تحول پکیج‌بیس فاز 0-4 ✅ (Domain + Migration + Business + Package Layer + CRUD)
    
 NOW (این ماه):
+    → 📦 فاز 5: پورسانت per-package (SP + Loop Service + Carryover)
+    → 📦 فاز 6: UI (کاشی‌های داینامیک + فیلتر پکیج + MyPackages)
    → EF Migration نهایی
    → تست کامل پروداکشن
    
@@ -1,9 +1,10 @@
 # 🔄 نقشه‌راه تحول پکیج‌بیس — تسک‌های گام‌به‌گام

-> **وضعیت:** تایید‌شده — آماده شروع  
+> **وضعیت:** در حال اجرا — **فاز ۰-۴ تکمیل ✅** | فاز ۵ در انتظار  
 > **تاریخ:** ۱۴۰۴/۱۲/۰۶  
 > **پیش‌نیاز:** [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) **v3** (تکمیل پورسانت per-package)  
-> **هدف:** شکستن **۴۸+ تغییر** به تسک‌های اتمیک با ترتیب اجرا و وابستگی‌ها
+> **هدف:** شکستن **۴۸+ تغییر** به تسک‌های اتمیک با ترتیب اجرا و وابستگی‌ها  
+> **کامیت‌ها:** `8b9c317` → `fe3edd1` → `ae92ab8` → `a9cd2fd` → `8e5c7c5` → `ccb938e` → `0002a5a`

 > ⚠️ **تغییرات v3:** پورسانت per-package، carryover مجزا، SP parameters داینامیک، گزارش‌دهی FO/BO per-package

@@ -12,21 +13,24 @@
 ## 📊 نمای کلی

 ```
-مرحله ۰: فیکس باگ فوری (۱ روز)
-    └─→ مرحله ۱: زیرساخت Domain + DB (۴ روز)    ← +۱ روز (v3: NetworkWeeklyBalance)
-            ├─→ مرحله ۲: منطق کسب‌وکار (۴ روز)  ← موازی
-            │       └─→ مرحله ۴: UI (۵ روز)              ← +۲ (v3: FO/BO گزارش per-package)
-            └─→ مرحله ۳: پورسانت (۴ روز)         ← +۱ (v3: SP params + carryover)
-                            └─→ مرحله ۵: تست + استقرار (۳ روز) ← +۱
+مرحله ۰: فیکس باگ فوری (۱ روز)                           ✅ `8b9c317` + `fe3edd1`
+    └─→ مرحله ۱: زیرساخت Domain + DB (۴ روز)         ✅ `ae92ab8`
+        └─→ مرحله ۱.۵: Migration + Seed                    ✅ `a9cd2fd`
+            ├─→ مرحله ۲: منطق کسب‌وکار (۴ روز)           ✅ `8e5c7c5`
+            │       └─→ مرحله ۳: بازسازی لایه Package       ✅ `ccb938e`
+            │               └─→ مرحله ۴: CRUD + Legacy Fixes   ✅ `0002a5a`
+            │                       └─→ مرحله UI (۵ روز)  ⬜
+            └─→ مرحله ۳: پورسانت (۴ روز)               ⬜ موازی
+                            └─→ مرحله ۵: تست + استقرار (۳ روز)  ⬜

-مسیر بحرانی: ۰→۱→۲→۴→۵ = ~۱۷ روز (v2: ۱۳ روز)
+مسیر بحرانی: ۰→۱→۱.۵→۲→۳→۴→UI→۵ = ~۱۷ روز | انجام‌شده: ۰→۴ (~۱۰ روز)
 ```

 ---

-## مرحله ۰ — فیکس باگ‌های فوری
+## مرحله ۰ — فیکس باگ‌های فوری ✅

-> ⏱️ ۱ روز | وابستگی: ندارد | ریسک: کم
+> ✅ تکمیل‌شده | کامیت: `8b9c317` + `fe3edd1`

 ### ✅ وضعیت باگ‌ها (بررسی اولیه لازم)

@@ -66,9 +70,9 @@

 ---

-## مرحله ۱ — زیرساخت (Domain + DB)
+## مرحله ۱ — زیرساخت (Domain + DB) ✅

-> ⏱️ ۳ روز | وابستگی: مرحله ۰ | ریسک: متوسط (migration)
+> ✅ تکمیل‌شده | کامیت: `ae92ab8` (Phase 1) + `a9cd2fd` (Phase 1.5 Migration)

 ### T1.1 — بروزرسانی Package Entity (۱۱ فیلد جدید — v3)

@@ -224,9 +228,9 @@ WHERE "PackageId" IS NULL;

 ---

-## مرحله ۲ — منطق کسب‌وکار
+## مرحله ۲ — منطق کسب‌وکار ✅

-> ⏱️ ۴ روز | وابستگی: مرحله ۱ | ریسک: بالا (رگرسیون)
+> ✅ تکمیل‌شده | کامیت: `8e5c7c5` (Phase 2) + `ccb938e` (Phase 3) + `0002a5a` (Phase 4)

 ### T2.1 — Generic Verify Handler

@@ -592,4 +596,4 @@ else

 ---

-*آخرین بروزرسانی: ۱۴۰۴/۱۲/۰۶ — v3 (پورسانت per-package + گزارش‌دهی + carryover)*
+*آخرین بروزرسانی: ۱۴۰۴/۱۲/۰۷ — فاز ۰-۴ تکمیل (۷ کامیت) | فاز ۵ پورسانت per-package در انتظار*