diff --git a/business/BIZ-PACKAGE-BASED-SYSTEM.md b/business/BIZ-PACKAGE-BASED-SYSTEM.md index 161bec0..47830da 100644 --- a/business/BIZ-PACKAGE-BASED-SYSTEM.md +++ b/business/BIZ-PACKAGE-BASED-SYSTEM.md @@ -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) --- diff --git a/overview/OVERVIEW-02-INDEX.md b/overview/OVERVIEW-02-INDEX.md index 70277f9..d98852d 100644 --- a/overview/OVERVIEW-02-INDEX.md +++ b/overview/OVERVIEW-02-INDEX.md @@ -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) + ۵۱ تغییر + ۴۴ سایدافکت | --- diff --git a/overview/OVERVIEW-03-CHANGELOG.md b/overview/OVERVIEW-03-CHANGELOG.md index fab50f2..952a4c9 100644 --- a/overview/OVERVIEW-03-CHANGELOG.md +++ b/overview/OVERVIEW-03-CHANGELOG.md @@ -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` generic interface — متد `CreateHistorySnapshot` برای ثبت خودکار +- ✅ `HistoryTrackingSaveChangesInterceptor` — reflection-based، auto-fill Old* از OriginalValues +- ✅ `Package` implements `IHasHistory` +- ✅ 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% | diff --git a/roadmap/PACKAGE-TRANSFORMATION-TASKS.md b/roadmap/PACKAGE-TRANSFORMATION-TASKS.md index ce8b94b..32e7212 100644 --- a/roadmap/PACKAGE-TRANSFORMATION-TASKS.md +++ b/roadmap/PACKAGE-TRANSFORMATION-TASKS.md @@ -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` 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` — اولین 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* diff --git a/technical/TECH-01-CMS-ARCHITECTURE.md b/technical/TECH-01-CMS-ARCHITECTURE.md index 8cdcca6..749f1f2 100644 --- a/technical/TECH-01-CMS-ARCHITECTURE.md +++ b/technical/TECH-01-CMS-ARCHITECTURE.md @@ -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 Interface + +```csharp +public interface IHasHistory 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