docs: Phase 9 — Q24-Q30 + History Interceptor + Rename + Migration

- CHANGELOG: add Phase 9 (9a-9d) with all new commits (CMS:a1024a3→fdbb91d→10d2ca2, FO:474d364, BO:6939780) - CHANGELOG: update summary table (279 items, 99%) - TASKS: add Phase 9 section with detailed descriptions + update commit list (30 total) - BIZ: update header to 'code complete — Phase 0-9 ✅' + add Phase 9 commits - TECH-01: add SP Worker (Q26), History Tracking System (Q27), IHasHistory, Interceptor docs - TECH-01: add UserWalletHistoryService (renamed from ChangeLog) - INDEX: update R3/R6 descriptions, update timestamp
2026-02-27 06:35:09 +03:30
parent 085583c274
commit e9f1fb9911
5 changed files with 166 additions and 21 deletions
@@ -1,10 +1,10 @@
 # 📦 سیستم مبتنی بر پکیج (Package-Based System)

-> **وضعیت:** در حال پیاده‌سازی — **فاز ۰-۴ تکمیل ✅** | فاز ۵-۶ در انتظار  
+> **وضعیت:** پیاده‌سازی کد تکمیل — **فاز ۰-۹ ✅** | تست + استقرار باقی‌مانده  
 > **تاریخ بروزرسانی:** ۸ اسفند ۱۴۰۴  
 > **نسخه:** v6 (آستانه موجودی + SP Worker + History Tables + UI Guidance)  
 > **تاثیرگذاری:** زیاد — **۹۵+** تغییر در ۶ لایه (۵۱ اصلی + ۴۴ سایدافکت)  
-> **کامیت‌ها:** `8b9c317` (Phase 0) → `ae92ab8` (Phase 1) → `a9cd2fd` (Phase 1.5) → `8e5c7c5` (Phase 2) → `ccb938e` (Phase 3) → `0002a5a` (Phase 4)
+> **کامیت‌ها:** `8b9c317` (Phase 0) → `ae92ab8` (Phase 1) → `a9cd2fd` (Phase 1.5) → `8e5c7c5` (Phase 2) → `ccb938e` (Phase 3) → `0002a5a` (Phase 4) → `a1024a3` (Q24+Q26) → `fdbb91d` (Q27) → `10d2ca2` (Rename+Interceptor+Migration)

 ---

@@ -4,7 +4,7 @@
 > **تاریخ تجمیع:** اسفند ۱۴۰۴  
 > **تعداد فایل‌های مبدأ:** ۵۳ فایل (~۳۲,۰۰۰ خط)  
 > **تعداد فایل‌های نهایی:** ۲۲ فایل (۱۵ اصلی + ۷ roadmap/business)  
-> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (تحول پکیج‌بیس فاز ۰-۴ + فعال‌سازی درگاه + مرج Production)
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (تحول پکیج‌بیس فاز ۰-۹ + Q24-Q30 + History Interceptor + Rename)

 ---

@@ -81,10 +81,10 @@ 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-6 تکمیل ✅** |
-| R3 | [PACKAGE-TRANSFORMATION-TASKS](../roadmap/PACKAGE-TRANSFORMATION-TASKS.md) | تحول پکیج‌بیس — تسک‌ها | ۵ فاز، **فاز 0-4 تکمیل ✅**، فاز 5-6 در انتظار |
+| R3 | [PACKAGE-TRANSFORMATION-TASKS](../roadmap/PACKAGE-TRANSFORMATION-TASKS.md) | تحول پکیج‌بیس — تسک‌ها | ۹ فاز، **فاز 0-9 تکمیل ✅**، تست + deploy در انتظار |
 | 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، ۲۳ تصمیم + ۵۱ تغییر + ۴۴ سایدافکت |
+| R6 | [BIZ-PACKAGE-BASED-SYSTEM](../business/BIZ-PACKAGE-BASED-SYSTEM.md) | طراحی سیستم پکیج‌بیس | v6، ۳۰ تصمیم (Q1-Q30) + ۵۱ تغییر + ۴۴ سایدافکت |

 ---

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

 > **همه فعالیت‌های پروژه به صورت بولت با توضیح یک‌خطی و درصد تکمیل**  
-> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: فاز ۸e — Per-Package Commission Reports | NuGet v0.0.187)
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: فاز ۹ — Q24-Q30 + Rename + History Interceptor + Migration | NuGet v0.0.188)

 ---

@@ -9,13 +9,13 @@

 | حوزه | تعداد آیتم | تکمیل‌شده | درصد کل |
 |------|-----------|----------|---------|
-| **BackOffice** | 61 | 61 | **100%** |
-| **FrontOffice** | 40 | 40 | **100%** |
-| **CMS Core** | 72 | 72 | **100%** |
-| **Package-Based System** | 35 | 35 | **100%** |
+| **BackOffice** | 67 | 67 | **100%** |
+| **FrontOffice** | 47 | 47 | **100%** |
+| **CMS Core** | 82 | 82 | **100%** |
+| **Package-Based System** | 45 | 45 | **100%** |
 | **Deployment** | 22 | 21 | **95%** |
 | **Migration** | 16 | 16 | **100%** |
-| **مجموع** | **246** | **245** | **99%** |
+| **مجموع** | **279** | **278** | **99%** |

 ---

@@ -321,6 +321,32 @@
 - ✅ FO: فیلتر و ستون پکیج در CommissionDashboard + WeeklyBalance
 - ✅ NuGet: `0.0.186` → `0.0.187`

+### Phase 9 — Q24-Q30 Business Decisions + History Infrastructure ✅
+
+#### 9a: Q24+Q26 — Balance Threshold + SP Worker ✅ (CMS:`a1024a3`)
+- ✅ Q24: آستانه موجودی `Balance <= 1_000_000` ریال برای ورود Magic و خرید مجدد (بجای `== 0`)
+- ✅ Q26: `StoredProcedureDeploymentService` (IHostedService) — خواندن فایل‌های `.sql` از embedded resource، مقایسه checksum و اعمال خودکار در startup
+
+#### 9b: Q27 — History Tables Entities ✅ (CMS:`fdbb91d`)
+- ✅ `PackageHistory` entity — فیلدهای Old*/New* برای Price, ActivationFee, MagicMultiplier, MagicMaxDeposit, MaxBalancesPerLeg, IsActive
+- ✅ `ClubMembershipCycleHistory` entity — فیلدهای Old*/New* برای IsCurrentCycle, MagicStartedAt, MagicCompletedAt
+- ✅ `PackageAction` و `ClubMembershipCycleAction` enums
+- ✅ EF Configurations + DbSets + Navigation Properties
+
+#### 9c: Q28 — UI Guidance ✅ (FO:`474d364` BO:`6939780`)
+- ✅ FrontOffice: ۷ صفحه با MudAlert (G1-G7) — Packages, Checkout, MyPackages, MagicWallet, Commission, Membership, ActivationSection
+- ✅ BackOffice: ۶ صفحه با MudAlert (G8-G13) — PackageCRUD, ClubFeatures, ManualPayments, Commission Dashboard, UserPayouts, ClubMembers
+
+#### 9d: Rename + History Interceptor + Migration ✅ (CMS:`10d2ca2`)
+- ✅ تغییر نام `UserWalletChangeLog` → `UserWalletHistory` در ۵۴+ فایل (entities, configs, DTOs, commands, queries, protos, services)
+- ✅ تغییر نام ۳۴ فایل و ۱۱ دایرکتوری
+- ✅ تغییر نام proto: `userwalletchangelog.proto` → `userwallethistory.proto`
+- ✅ `IHasHistory<T>` generic interface — متد `CreateHistorySnapshot` برای ثبت خودکار
+- ✅ `HistoryTrackingSaveChangesInterceptor` — reflection-based، auto-fill Old* از OriginalValues
+- ✅ `Package` implements `IHasHistory<PackageHistory>`
+- ✅ EF Migration `Q27_HistoryTables_And_RenameWalletHistory` — **RenameTable** (حفظ داده) + rename PK/FK/Index via sp_rename
+- ✅ NuGet: `0.0.187` → `0.0.188`
+
 ---

 ## ۸. Timeline (جدول زمانی)
@@ -340,3 +366,4 @@
 | اسفند ۱۴۰۴ (هفته ۳) | 🚀 فعال‌سازی درگاه + بهبود UI ادمین + مرج پروداکشن | 97% |
 | اسفند ۱۴۰۴ (هفته ۴) | 📦 تحول پکیج‌بیس فاز ۰-۶ (Domain → Migration → Business → Package → CRUD → Commission per-pkg → Deprecation) | 97% |
 | اسفند ۱۴۰۴ (هفته ۵) | 📦 فاز 8e: گزارش‌های پورسانت per-package (Proto + CMS + BO + FO) | 98% |
+| اسفند ۱۴۰۴ (هفته ۶) | 📦 فاز ۹: Q24-Q30 (آستانه + SP Worker + History Tables + UI Guidance + Rename + Interceptor + Migration) | 99% |
@@ -1,13 +1,13 @@
 # 🔄 نقشه‌راه تحول پکیج‌بیس — تسک‌های گام‌به‌گام

-> **وضعیت:** در حال اجرا — **فاز ۰-۸f (UI تکمیل) ✅** | NuGet v0.0.188 | تست باقی‌مانده  
-> **تاریخ:** ۱۴۰۴/۱۲/۱۰  
-> **پیش‌نیاز:** [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) **v3** (تکمیل پورسانت per-package)  
+> **وضعیت:** در حال اجرا — **فاز ۰-۹ (تکمیل کد) ✅** | NuGet v0.0.188 | تست باقی‌مانده  
+> **تاریخ:** ۱۴۰۴/۱۲/۰۸  
+> **پیش‌نیاز:** [BIZ-PACKAGE-BASED-SYSTEM.md](../business/BIZ-PACKAGE-BASED-SYSTEM.md) **v6** (تکمیل Q24-Q30 + History + Rename)  
 > **هدف:** شکستن **۴۸+ تغییر** به تسک‌های اتمیک با ترتیب اجرا و وابستگی‌ها  
 > **کامیت‌ها:**  
-> CMS: `8b9c317`→`fe3edd1`→`ae92ab8`→`a9cd2fd`→`8e5c7c5`→`ccb938e`→`0002a5a`→`607f791`→`7176fe4`→`d19c569`→`469d97b`→`161f796`→`8446e0e`→`ce8e248`→`7554d70`→`aaaf7fc`→`dcd1135`  
-> FrontOffice: `b82cac4`→`71f391a`→`0bbc11e`→`d71d463`→`40882c8`→`a956cb9`→`3bffc13`  
-> BackOffice: `f1b0085`→`89f5241`→`c96377a`→`8be98ae`→`e020354`
+> CMS: `8b9c317`→`fe3edd1`→`ae92ab8`→`a9cd2fd`→`8e5c7c5`→`ccb938e`→`0002a5a`→`607f791`→`7176fe4`→`d19c569`→`469d97b`→`161f796`→`8446e0e`→`ce8e248`→`7554d70`→`aaaf7fc`→`dcd1135`→`a1024a3`→`fdbb91d`→`10d2ca2`  
+> FrontOffice: `b82cac4`→`71f391a`→`0bbc11e`→`d71d463`→`40882c8`→`a956cb9`→`3bffc13`→`474d364`  
+> BackOffice: `f1b0085`→`89f5241`→`c96377a`→`8be98ae`→`e020354`→`6939780`

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

@@ -36,9 +36,14 @@
                                            └─→ 8d: Proto cleanup      ✅ CMS:`7554d70` FO:`40882c8` BO:`c96377a`
                                                └─→ 8e: Per-package reports ✅ CMS:`aaaf7fc` FO:`a956cb9` BO:`8be98ae`
                                                    └─→ 8f: UI completion   ✅ CMS:`dcd1135` FO:`3bffc13` BO:`e020354`
-                                                        └─→ مرحله ۵: تست + استقرار (۳ روز)  ⬜
+                                                            └─→ مرحله ۹: Q24-Q30 + History + Rename
+                                                                ├─→ 9a: Q24+Q26 (threshold+SP) ✅ CMS:`a1024a3`
+                                                                ├─→ 9b: Q27 History entities  ✅ CMS:`fdbb91d`
+                                                                ├─→ 9c: Q28 UI Guidance       ✅ FO:`474d364` BO:`6939780`
+                                                                └─→ 9d: Rename+Interceptor+Mig ✅ CMS:`10d2ca2`
+                                                                    └─→ مرحله ۵: تست + استقرار (۳ روز)  ⬜

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

 ---
@@ -710,6 +715,79 @@ await connection.ExecuteAsync("CMS.sp_CalculateWeeklyBalances",

 ---

+## مرحله ۹ — Q24-Q30 Business Decisions + History Infrastructure ✅
+
+> ✅ تکمیل‌شده | وابستگی: مرحله ۸ | کامیت‌ها: CMS:`a1024a3`→`fdbb91d`→`10d2ca2` FO:`474d364` BO:`6939780`
+
+### 9a: Q24 آستانه موجودی + Q26 SP Worker ✅ (CMS:`a1024a3`)
+
+**Q24 — آستانه موجودی:**
+- شرط ورود به Magic و خرید مجدد از `Balance == 0` به `Balance <= 1_000_000` ریال تغییر کرد
+- چون قیمت محصولات متفاوته، Balance دقیقاً صفر نمی‌شه
+- فایل‌ها: `UserOrderService.cs` (شرط EXIT Magic + Re-purchase guard)
+
+**Q26 — SP Worker:**
+- `StoredProcedureDeploymentService` (IHostedService) — در startup فایل‌های `.sql` از embedded resource خوانده می‌شوند
+- مقایسه checksum با جدول `__SPChecksums` — فقط SP‌های تغییریافته re-deploy می‌شوند
+- فایل‌ها: `StoredProcedureDeploymentService.cs`, embedded `.sql` resources
+
+### 9b: Q27 History Tables Entities ✅ (CMS:`fdbb91d`)
+
+**Entity‌های جدید:**
+- `PackageHistory`: فیلدهای Old*/New* برای Price, ActivationFee, MagicMultiplier, MagicMaxDeposit, MaxBalancesPerLeg, IsActive + Action + PerformedBy + Reason
+- `ClubMembershipCycleHistory`: فیلدهای Old*/New* برای IsCurrentCycle, MagicStartedAt, MagicCompletedAt + Action + UserId + CycleNumber
+
+**Enums جدید:**
+- `PackageAction`: Created, Updated, Activated, Deactivated, PriceChanged, FeaturesChanged
+- `ClubMembershipCycleAction`: Created, MagicStarted, MagicCompleted, Closed, AdminModified
+
+**زیرساخت:**
+- EF Configurations (indexes, maxLength, precision)
+- DbSets در `IApplicationDbContext` و `ApplicationDbContext`
+- Navigation Properties: `Package.Histories`, `ClubMembershipCycle.Histories`
+
+### 9c: Q28 UI Guidance ✅ (FO:`474d364` BO:`6939780`)
+
+**FrontOffice — ۷ صفحه با MudAlert آموزشی:**
+- G1: Packages.razor — توضیح سیستم پکیج‌بیس
+- G2: Checkout — هشدار شارژ کیف‌پول اعتباری
+- G3: MyPackages — توضیح وضعیت پکیج‌ها
+- G4: MagicWallet — هشدار شرایط خروج + سقف شارژ
+- G5: CommissionDashboard — توضیح per-package
+- G6: ClubMembership — آموزش چرخه عضویت
+- G7: ActivationSection — هشدار هزینه فعال‌سازی
+
+**BackOffice — ۶ صفحه با MudAlert:**
+- G8: PackageCRUD — هشدار ثبت تغییرات در History
+- G9: ClubFeatures — توضیح ارتباط فیچر-پکیج
+- G10: ManualPayments — هشدار مبلغ بر اساس پکیج
+- G11: Commission Dashboard — توضیح Pool per-package
+- G12: UserPayouts — توضیح فیلتر پکیج
+- G13: ClubMembers — اطلاعات چرخه عضویت
+
+### 9d: Rename + History Interceptor + EF Migration ✅ (CMS:`10d2ca2`)
+
+**Rename (86 فایل):**
+- `UserWalletChangeLog` → `UserWalletHistory` در 54+ فایل (entities, configs, DTOs, commands, queries, protos, services)
+- 34 فایل rename شده + 11 دایرکتوری rename شده
+- Proto: `userwalletchangelog.proto` → `userwallethistory.proto`
+
+**History Interceptor:**
+- `IHasHistory<T>` generic interface در `Domain/Common` — متد `CreateHistorySnapshot(action, performedBy)`
+- `HistoryTrackingSaveChangesInterceptor` در `Infrastructure/Persistence/Interceptors` — reflection-based
+  - شناسایی entity‌های `IHasHistory<>` از ChangeTracker
+  - فراخوانی `CreateHistorySnapshot` برای Modified/Added
+  - Auto-fill فیلدهای `Old*` از `OriginalValues` با naming convention
+- `Package` implements `IHasHistory<PackageHistory>` — اولین entity
+
+**EF Migration (`Q27_HistoryTables_And_RenameWalletHistory`):**
+- ⚠️ EF Core اتوماتیک `DropTable` + `CreateTable` تولید کرد → **دستی اصلاح شد** به `RenameTable` (حفظ داده‌ها)
+- `RenameTable` + `RenameIndex` × 2 + `sp_rename` برای PK و FK‌ها
+- `CreateTable` برای `ClubMembershipCycleHistories` و `PackageHistories` (جداول جدید)
+- Down method: reverse rename + drop new tables
+
+---
+
 ## مرحله ۵ — تست و استقرار

 > ⏱️ **۳ روز** (v3: +۱) | وابستگی: مرحله ۴
@@ -778,4 +856,4 @@ await connection.ExecuteAsync("CMS.sp_CalculateWeeklyBalances",

 ---

-*آخرین بروزرسانی: ۱۴۰۴/۱۲/۱۰ — فاز ۰-۸f تکمیل (۲۷ کامیت: ۱۷ CMS + ۷ FO + ۵ BO) | NuGet v0.0.188 | T4.2+T4.3+T4.13+F2+F3 کامل | باقی‌مانده: تست + deploy*
+*آخرین بروزرسانی: ۱۴۰۴/۱۲/۰۸ — فاز ۰-۹d تکمیل (۳۰ کامیت: ۲۰ CMS + ۸ FO + ۶ BO) | NuGet v0.0.188 | باقی‌مانده: تست + deploy*
@@ -1,7 +1,7 @@
 # ⚙️ معماری CMS و زیرساخت فنی

 > **منابع ادغام‌شده:** `CMS-README.md`, `ICURRENTUSERSERVICE-IMPLEMENTATION.md`, `FILE-MANAGEMENT-ARCHITECTURE.md`, `FRONTOFFICE-CMS-API-COMPATIBILITY.md`, `BFF-REMOVAL-PLAN.md`, `system-constants.md`  
-> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet entities + gRPC)
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: History Interceptor + SP Worker + Rename UserWalletHistory)

 ---

@@ -140,6 +140,7 @@ public class CreateProductCommandHandler
 | `CategoryService` | category.proto | GetCategories, Create, Update |
 | `SystemConfigService` | config.proto | GetConfig, UpdateConfig |
 | `UserWalletService` | userwallet.proto | GetCustomerWallet, InitiateMagicCharge, GetMagicWalletStatus |
+| `UserWalletHistoryService` | userwallethistory.proto | *(renamed from UserWalletChangeLogService)* |

 ### ۴.۲ PaginationState (مشترک)

@@ -195,6 +196,45 @@ Engine: MSSQL 2022-CU16, Collation=Arabic_CI_AS
 | `sp_CalculateWeeklyBalances` | محاسبه بالانس هفتگی هر عضو |
 | `sp_CalculateWeeklyCommissionPool` | توزیع Pool هفتگی |

+### ۵.۴ SP Auto-Deploy Worker (Q26)
+
+```csharp
+// StoredProcedureDeploymentService : IHostedService
+// در startup:
+// 1. خواندن فایل‌های .sql از embedded resource
+// 2. مقایسه checksum با جدول __SPChecksums
+// 3. فقط SP‌های تغییریافته re-deploy می‌شوند
+```
+
+---
+
+## ۵.۵ History Tracking System (Q27)
+
+### IHasHistory<T> Interface
+
+```csharp
+public interface IHasHistory<THistory> where THistory : BaseAuditableEntity, new()
+{
+    THistory CreateHistorySnapshot(string action, string? performedBy);
+}
+```
+
+### HistoryTrackingSaveChangesInterceptor
+
+- **مکان:** `Infrastructure/Persistence/Interceptors/HistoryTrackingSaveChangesInterceptor.cs`
+- **مکانیسم:** `SaveChangesInterceptor` — قبل از `SaveChanges` اجرا می‌شود
+- **شناسایی:** از `ChangeTracker` entity‌هایی که `IHasHistory<>` پیاده‌سازی کردن (Modified/Added)
+- **Auto-fill:** فیلدهای `Old*` از `entry.OriginalValues` با naming convention (مثلاً `OldPrice` ← `OriginalValues["Price"]`)
+- **Entity‌های فعال:** `Package` → `PackageHistory`
+
+### History Tables
+
+| جدول | Entity مرتبط | فیلدهای Old/New |
+|------|-------------|----------------|
+| `PackageHistories` | Package | Price, ActivationFee, MagicMultiplier, MagicMaxDeposit, MaxBalancesPerLeg, IsActive |
+| `ClubMembershipCycleHistories` | ClubMembershipCycle | IsCurrentCycle, MagicStartedAt, MagicCompletedAt |
+| `UserWalletHistories` | UserWallet | *(renamed from UserWalletChangeLogs — RenameTable migration)* |
+
 ---

 ## ۶. حذف BFF / Gateway