From 421a65197569289baac525a13169eb31fb37da5c Mon Sep 17 00:00:00 2001 From: masoodafar-web Date: Sun, 22 Feb 2026 20:09:01 +0330 Subject: [PATCH] docs: Magic Wallet + VAT 10% documentation update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - All 14 totalDoc files updated with Magic Wallet additions - MAGIC-WALLET-PLAN.md: Phase 1-6 checklist fully marked complete - Business docs: Magic Wallet section, commission filter, new entities - Payment docs: VAT 9%→10%, TransactionType 14+15, ZarinPal 4th usage - Technical docs: UserWallet fields, ClubMembershipCycle, gRPC RPCs - Overview docs: Magic flowchart, ER diagram, changelog, glossary, roadmap --- business/BUSINESS-01-CLUB-COMMISSION.md | 78 ++++++++++++++++++++- business/BUSINESS-02-PAYMENT-FINANCE.md | 21 +++--- business/BUSINESS-03-ECOMMERCE-STORES.md | 6 +- business/BUSINESS-04-USER-MEMBERSHIP.md | 6 +- business/BUSINESS-05-CONTENT-MANAGEMENT.md | 7 +- overview/OVERVIEW-01-FLOWCHARTS.md | 34 ++++++++- overview/OVERVIEW-02-INDEX.md | 9 +-- overview/OVERVIEW-03-CHANGELOG.md | 21 ++++-- overview/OVERVIEW-04-GLOSSARY.md | 7 +- overview/OVERVIEW-05-ROADMAP.md | 19 +++-- roadmap/MAGIC-WALLET-PLAN.md | 46 ++++++------ technical/TECH-01-CMS-ARCHITECTURE.md | 6 +- technical/TECH-02-BACKOFFICE-FRONTOFFICE.md | 9 ++- technical/TECH-05-API-INTEGRATION.md | 14 +++- 14 files changed, 221 insertions(+), 62 deletions(-) diff --git a/business/BUSINESS-01-CLUB-COMMISSION.md b/business/BUSINESS-01-CLUB-COMMISSION.md index dc78640..bc8758b 100644 --- a/business/BUSINESS-01-CLUB-COMMISSION.md +++ b/business/BUSINESS-01-CLUB-COMMISSION.md @@ -1,7 +1,7 @@ # 🏆 سیستم باشگاه، کمیسیون و درخت شبکه‌ای > **منابع ادغام‌شده:** `club-commission-system-complete.md`, `balance-calculation-rules.md`, `club-membership-contract-system.md` -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet + کمیسیون) --- @@ -13,6 +13,8 @@ | **درخت باینری** | هر کاربر حداکثر ۲ فرزند مستقیم (چپ/راست) — بدون محدودیت عمق | | **کمیسیون هفتگی** | محاسبه بر اساس تعادل چپ/راست — یکشنبه ۰۰:۰۵ (Hangfire cron) | | **۳ کیف پول** | `Balance` (نقدی) + `NetworkBalance` (طلایی/کمیسیون) + `DiscountBalance` (تخفیفی) | +| **کیف‌پول جادویی** | وقتی Balance=0 → حالت Magic فعال → شارژ ×2.5 → سقف 100M/دور | +| **چرخه عضویت** | `ClubMembershipCycle` — هر خرید پکیج = یک دور جدید (برای تاریخ کمیسیون) | --- @@ -105,6 +107,21 @@ flowchart LR > فرمت هفته: `YYYY-Www` (شمسی، شنبه‌پایه) +### ۴.۴ فیلتر کاربران Magic از کمیسیون + +> ⚠️ **کاربرانی که در حالت Magic هستند (`WalletMode = 1`) از محاسبات کمیسیون هفتگی خارج می‌شوند.** + +``` +فیلتر در ۳ نقطه: + ✅ CalculateWeeklyBalancesCommandHandler.cs → WHERE wallet.WalletMode != Magic + ✅ OrmCommissionCalculationStrategy.cs → فیلتر LINQ + ✅ sp_CalculateWeeklyBalances.sql → NOT EXISTS (WalletMode=1) + +تاریخ محاسبه: + قبل: ClubMembership.ActivatedAt (مشکل: بعد از خرید مجدد overwrite می‌شد) + بعد: ClubMembershipCycle.PackagePurchasedAt (هر دور تاریخ مستقل) +``` + --- ## ۵. تنظیمات سیستمی (SystemConstants) @@ -120,6 +137,9 @@ flowchart LR | `MaxDirectChildrenPerLeg` | 1 | حداکثر فرزند مستقیم هر پا | | `MinimumWithdrawAmount` | 1,000,000 | حداقل مبلغ برداشت (ریال) | | `ShopVAT` | 0.1 (10%) | مالیات ارزش افزوده | +| `MagicWalletMultiplier` | 2.5 | ضریب شارژ جادویی (واریز × 2.5) | +| `MagicWalletMaxDeposit` | 1,000,000,000 | سقف واریز هر دور (100M تومان = 1B ریال) | +| `MagicWalletMaxCredit` | 2,500,000,000 | سقف اعتبار هر دور (250M تومان) | | `CommissionCalculationMethod` | "SP" | روش محاسبه = Stored Procedure | --- @@ -158,3 +178,59 @@ flowchart TD | **Retry** | Polly — ۳ تلاش، backoff نمایی | | **فعال‌سازی** | فقط برای اعضای فعال باشگاه | | **وضعیت** | ✅ Production ready | + +--- + +## ۹. کیف‌پول جادویی (Magic Wallet) ✅ + +> **وضعیت: فاز ۱ تا ۵ پیاده‌سازی شده — فاز ۶ باقیمانده** +> **مرجع کامل:** [MAGIC-WALLET-SPEC](../roadmap/MAGIC-WALLET-SPEC.md) + +### ۹.۱ چرخه کامل + +```mermaid +flowchart TD + A["خرید پکیج 56M\nBalance=56M, Discount=112M"] --> B["خرید از فروشگاه\nBalance کم می‌شود"] + B --> C{"Balance = 0?"} + C -->|خیر| B + C -->|بله| D{"عضو باشگاه فعال؟"} + D -->|خیر| E["حالت عادی باقی بمان"] + D -->|بله| F["🪄 ورود به حالت جادویی\nWalletMode = Magic"] + F --> G["شارژ از درگاه\nواریز × 2.5 = اعتبار Balance"] + G --> H{"Balance=0 AND\nTotalDeposited≥100M?"} + H -->|خیر| G + H -->|بله| I["خروج از جادویی\nWalletMode = Normal"] + I --> J["خرید مجدد پکیج\nفقط IPG — بدون دایا"] + J --> A +``` + +### ۹.۲ قوانین کلیدی + +| قانون | مقدار | +|-------|-------| +| ضریب شارژ | واریز × 2.5 = اعتبار Balance | +| سقف واریز/دور | 100M تومان (1B ریال) | +| سقف اعتبار/دور | 250M تومان (2.5B ریال) | +| کمیسیون در Magic | ❌ غیرفعال | +| شرط خروج | Balance=0 **و** TotalDeposited≥100M (هر دو همزمان) | +| ریست سقف | هر خرید مجدد پکیج → سقف از صفر | + +### ۹.۳ Entity‌های جدید + +```csharp +// فیلدهای جدید UserWallet +public WalletMode WalletMode { get; set; } // Normal=0, Magic=1 +public long MagicTotalDeposited { get; set; } // مجموع واریزی دور فعلی +public long MagicTotalCredited { get; set; } // مجموع اعتبار دریافتی +public DateTime? MagicActivatedAt { get; set; } +public DateTime? MagicCompletedAt { get; set; } + +// Entity جدید — حل مشکل تاریخ کمیسیون +public class ClubMembershipCycle { + public long Id { get; set; } + public long ClubMembershipId { get; set; } + public int CycleNumber { get; set; } // شماره دور (1, 2, 3, ...) + public DateTime PackagePurchasedAt { get; set; } // تاریخ خرید این دور + public bool IsCurrentCycle { get; set; } // دور فعلی +} +``` diff --git a/business/BUSINESS-02-PAYMENT-FINANCE.md b/business/BUSINESS-02-PAYMENT-FINANCE.md index b0b691c..75e8e52 100644 --- a/business/BUSINESS-02-PAYMENT-FINANCE.md +++ b/business/BUSINESS-02-PAYMENT-FINANCE.md @@ -1,7 +1,7 @@ # 💰 سیستم مالی، پرداخت و درگاه‌ها > **منابع ادغام‌شده:** `payment-gateway.md`, `payment-architecture-pyms.md`, `daya-loan-integration.md`, `manual-payment-system.md`, `discount-shop-business.md` -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet + VAT 10%) --- @@ -34,10 +34,11 @@ flowchart TD ## ۲. درگاه ZarinPal (IPG) -> **⚠️ محل استفاده:** ZarinPal فقط در سه جا استفاده می‌شود: +> **⚠️ محل استفاده:** ZarinPal فقط در چهار جا استفاده می‌شود: > 1. **فروشگاه تخفیفی** — باقیمانده بعد از کسر DiscountBalance (اگر > 0) > 2. **شارژ کیف‌پول** — واریز مستقیم از پروفایل کاربر > 3. **خرید پکیج** — (فعلاً غیرفعال: "درگاه پرداخت متصل نیست") +> 4. **شارژ کیف‌پول جادویی** — واریز با ضریب ×2.5 (فقط در حالت Magic) > > ❌ **فروشگاه عادی (Regular Store) از ZarinPal استفاده نمی‌کند** — فقط کسر از Balance کیف‌پول @@ -148,7 +149,7 @@ flowchart TD C --> D["سهم تخفیف = MIN(قیمت×MaxDiscount%, DiscountBalance)"] D --> E["باقیمانده = مجموع - سهم تخفیف"] E --> F{"باقیمانده > 0?"} - F -->|بله| G["کسر DiscountBalance\n+ Redirect → ZarinPal IPG\nباقیمانده + 9% VAT"] + F -->|بله| G["کسر DiscountBalance\n+ Redirect → ZarinPal IPG\nباقیمانده + 10% VAT"] F -->|خیر| H["فقط کسر از DiscountBalance\nبدون درگاه → ثبت مستقیم"] ``` @@ -187,20 +188,21 @@ service PaymentService { | WalletCharge | 5 | شارژ مستقیم کیف‌پول | | ActivationFee | 6 | هزینه فعالسازی | | DayaLoanCharge | 7 | شارژ از وام دایا | +| MagicWalletDeposit | 14 | واریز به کیف‌پول جادویی | +| MagicWalletBonus | 15 | بونوس ضریب ×2.5 کیف‌پول جادویی | --- ## ۷. مالیات و VAT ``` -هر دو فروشگاه از نرخ 9% استفاده می‌کنند: +هر دو فروشگاه از نرخ 10% استفاده می‌کنند: - Regular Store → const vatRate = 0.09m (hardcoded در SubmitShopBuyOrderCommandHandler) - Discount Store → VatCalculator.VAT_RATE = 0.09m + Regular Store → const vatRate = 0.10m (hardcoded در SubmitShopBuyOrderCommandHandler) + Discount Store → VatCalculator.VAT_RATE = 0.10m + SystemConstants.ShopVAT = 0.1 (10%) - ⚠️ SystemConstants.ShopVAT = 0.1 (10%) — تعریف‌شده ولی استفاده نمی‌شود (stale constant) - -قیمت نمایشی = قیمت پایه × (1 + 0.09) +قیمت نمایشی = قیمت پایه × (1 + 0.10) در صورتحساب: قیمت پایه + مالیات جداگانه نمایش داده می‌شود ``` @@ -216,3 +218,4 @@ service PaymentService { | Pool هفتگی | ✅ کامل | SP + Hangfire | | پرداخت دستی | ⬜ طراحی | نیاز به تصمیم مدیریت | | Refund | ⬜ طراحی | فقط در PYMS تعریف‌شده | +| کیف‌پول جادویی (Magic) | ✅ کامل | فاز 1-5 پیاده‌سازی شده | diff --git a/business/BUSINESS-03-ECOMMERCE-STORES.md b/business/BUSINESS-03-ECOMMERCE-STORES.md index 6b904c2..8d44aba 100644 --- a/business/BUSINESS-03-ECOMMERCE-STORES.md +++ b/business/BUSINESS-03-ECOMMERCE-STORES.md @@ -1,7 +1,7 @@ # 🛒 فروشگاه، موجودی و محصولات > **منابع ادغام‌شده:** `discount-shop-business.md`, `DISCOUNT-STORE-STATUS.md`, `package-purchase-system.md`, `INVENTORY-IMPROVEMENTS.md`, `INVENTORY-REFACTORING-STATUS.md`, `PRODUCT-BUNDLE-FEATURE.md`, `SHOP-UNIFICATION.md` -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: VAT 10%) --- @@ -13,14 +13,14 @@ flowchart LR R1["همه کاربران"] R2["پرداخت از Balance کیف‌پول"] R3["قیمت عادی"] - R4["VAT = 9%"] + R4["VAT = 10%"] end subgraph DS["Discount Store — /discount-store"] D1["فقط اعضای باشگاه"] D2["پرداخت ترکیبی تخفیف+نقد"] D3["تخفیف بر اساس MaxDiscountPercent"] - D4["VAT = 9%"] + D4["VAT = 10%"] end subgraph SHARED["مشترک"] diff --git a/business/BUSINESS-04-USER-MEMBERSHIP.md b/business/BUSINESS-04-USER-MEMBERSHIP.md index 2378bc7..62bb563 100644 --- a/business/BUSINESS-04-USER-MEMBERSHIP.md +++ b/business/BUSINESS-04-USER-MEMBERSHIP.md @@ -1,7 +1,7 @@ # 👤 سفر کاربر، ثبت‌نام و چرخه عضویت > **منابع ادغام‌شده:** `club-membership-contract-system.md`, `REGISTRATION-FLOW-FIXES.md`, `chatika-integration.md`, `club-feature-management-services.md`, `ADMIN-CUSTOMER-SEPARATION-FIX.md`, `ICURRENTUSERSERVICE-IMPLEMENTATION.md` -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet cycle) --- @@ -20,6 +20,10 @@ flowchart TD G --> H["فعالسازی 25.2M"] H --> I["عضویت درخت باینری"] I --> J["دسترسی فروشگاه تخفیفی\nفیچرهای باشگاه\nکمیسیون هفتگی"] + J --> K{"Balance = 0?"} + K -->|بله| L["🪄 کیف‌پول جادویی\nشارژ ×2.5 از درگاه"] + L --> M["خروج از Magic\nخرید مجدد پکیج"] + M --> F ``` --- diff --git a/business/BUSINESS-05-CONTENT-MANAGEMENT.md b/business/BUSINESS-05-CONTENT-MANAGEMENT.md index 704f0da..1c67812 100644 --- a/business/BUSINESS-05-CONTENT-MANAGEMENT.md +++ b/business/BUSINESS-05-CONTENT-MANAGEMENT.md @@ -1,7 +1,7 @@ # 📄 محتوا، صفحات، بلاگ و ایمیل/SMS > **منابع ادغام‌شده:** `SITE-PAGES-SIMPLIFICATION.md`, `system-constants.md`, `email-sms-configuration.md`, `chatika-integration.md`, `CMS-README.md` -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet + VAT 10%) --- @@ -178,7 +178,10 @@ CREATE TABLE SystemConfigurations ( | Club | `BasePackageAmount` | 56000000 | قیمت پکیج طلایی (ریال) | | Club | `CommissionMaxNetworkLevel` | 15 | عمق محاسبه کمیسیون | | Club | `CommissionMaxWeeklyBalancesPerLeg` | 300 | سقف هفتگی | -| Payment | `ShopVAT` | 0.1 (10%) | مالیات (فروشگاه تخفیفی: 9%) | +| Payment | `ShopVAT` | 0.1 (10%) | مالیات ارزش افزوده (هر دو فروشگاه) | +| Magic | `MagicWalletMultiplier` | 2.5 | ضریب شارژ جادویی | +| Magic | `MagicWalletMaxDeposit` | 1,000,000,000 | سقف واریز/دور (100M تومان) | +| Magic | `MagicWalletMaxCredit` | 2,500,000,000 | سقف اعتبار/دور (250M تومان) | | Payment | `DayaLoanAmount` | 56000000 | مبلغ وام (ریال) | | Payment | `MinimumWithdrawAmount` | 1000000 | حداقل برداشت (ریال) | | Store | `MaxDiscountPercent` | per-product | 0-100، هر محصول جداگانه | diff --git a/overview/OVERVIEW-01-FLOWCHARTS.md b/overview/OVERVIEW-01-FLOWCHARTS.md index dca7c0c..4481b9e 100644 --- a/overview/OVERVIEW-01-FLOWCHARTS.md +++ b/overview/OVERVIEW-01-FLOWCHARTS.md @@ -1,7 +1,7 @@ # 📊 فلوچارت‌ها و دیاگرام‌های کلان -> **دید بالا (Big Picture): فلوی کاربر، مالی و داده** -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **دید بالا (Big Picture): فلوی کاربر، مالی، داده و کیف‌پول جادویی** +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet + VAT 10%) --- @@ -24,6 +24,24 @@ flowchart TD I --> K["درخت شبکه\nباینری"] I --> L["کمیسیون\nهفتگی"] I --> M["Chatika AI"] + I --> N["🪄 کیف‌پول جادویی\nشارژ ×2.5"] +``` + +--- + +## ۱.۱ فلوی کیف‌پول جادویی (Magic Wallet) ✅ + +```mermaid +flowchart TD + A["خرید پکیج 56M\nBalance=56M"] --> B["خرید از فروشگاه\nBalance کم می‌شود"] + B --> C{"Balance = 0 +\nعضو فعال باشگاه?"} + C -->|خیر| B + C -->|بله| D["🪄 Magic Mode\nWalletMode = 1"] + D --> E["شارژ از درگاه\nواریز × 2.5"] + E --> F{"Balance=0 AND\nDeposited≥100M?"} + F -->|خیر| G["خرید یا شارژ ادامه"] + G --> F + F -->|بله| H["خروج از Magic\nخرید مجدد پکیج"] ``` --- @@ -144,7 +162,7 @@ flowchart TD D2 --> E2["محاسبه سهم تخفیف\nMaxDiscount% هر محصول"] E2 --> F2["محاسبه باقیمانده\ngatewayAmount = total - discountUsed"] F2 --> G2{"gatewayAmount > 0?"} - G2 -->|بله| H2["کسر DiscountBalance\n+ ZarinPal IPG برای باقیمانده + 9% VAT"] + G2 -->|بله| H2["کسر DiscountBalance\n+ ZarinPal IPG برای باقیمانده + 10% VAT"] H2 --> I2["Redirect → ZarinPal\nCallback → ثبت سفارش"] G2 -->|خیر| J2["فقط کسر از DiscountBalance\nبدون درگاه"] J2 --> K2["ثبت سفارش"] @@ -203,12 +221,22 @@ erDiagram UserWallet ||--o{ UserWalletChangeLog : logs + ClubMembership ||--o{ ClubMembershipCycle : has + BlogPost }o--|| Category : belongs_to UserWallet { long Balance long NetworkBalance long DiscountBalance + int WalletMode + long MagicTotalDeposited + long MagicTotalCredited + } + ClubMembershipCycle { + int CycleNumber + datetime PackagePurchasedAt + bool IsCurrentCycle } User { Guid NetworkParentId diff --git a/overview/OVERVIEW-02-INDEX.md b/overview/OVERVIEW-02-INDEX.md index aa66105..eafa3f5 100644 --- a/overview/OVERVIEW-02-INDEX.md +++ b/overview/OVERVIEW-02-INDEX.md @@ -3,7 +3,8 @@ > **فهرست کامل ۱۵ فایل مستند پروژه FourSat (کارا بازار سلامت)** > **تاریخ تجمیع:** اسفند ۱۴۰۴ > **تعداد فایل‌های مبدأ:** ۵۳ فایل (~۳۲,۰۰۰ خط) -> **تعداد فایل‌های نهایی:** ۱۷ فایل (۱۵ اصلی + ۲ roadmap) +> **تعداد فایل‌های نهایی:** ۱۷ فایل (۱۵ اصلی + ۲ roadmap) +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (Magic Wallet + VAT fix) --- @@ -45,8 +46,8 @@ totalDoc/ | # | فایل | موضوع | خلاصه | |---|------|--------|--------| -| B1 | [BUSINESS-01-CLUB-COMMISSION](../business/BUSINESS-01-CLUB-COMMISSION.md) | باشگاه و کمیسیون | درخت باینری، فرمول ۴مرحله‌ای، Pool هفتگی، وام دایا، Chatika | -| B2 | [BUSINESS-02-PAYMENT-FINANCE](../business/BUSINESS-02-PAYMENT-FINANCE.md) | مالی و پرداخت | ZarinPal IPG، ۳ کیف‌پول، PYMS، پرداخت ترکیبی، VAT | +| B1 | [BUSINESS-01-CLUB-COMMISSION](../business/BUSINESS-01-CLUB-COMMISSION.md) | باشگاه و کمیسیون | درخت باینری، فرمول ۴مرحله‌ای، Pool هفتگی، وام دایا، Chatika، **🪄 کیف‌پول جادویی** | +| B2 | [BUSINESS-02-PAYMENT-FINANCE](../business/BUSINESS-02-PAYMENT-FINANCE.md) | مالی و پرداخت | ZarinPal IPG، ۳ کیف‌پول، PYMS، پرداخت ترکیبی، VAT 10%، **Magic Charge** | | B3 | [BUSINESS-03-ECOMMERCE-STORES](../business/BUSINESS-03-ECOMMERCE-STORES.md) | فروشگاه | Regular + Discount Store، Lazy Load، موجودی خودکار، باندل | | B4 | [BUSINESS-04-USER-MEMBERSHIP](../business/BUSINESS-04-USER-MEMBERSHIP.md) | کاربر و عضویت | ثبت‌نام OTP، قرارداد، فیچرهای باشگاه، Auth-Aware، Referral | | B5 | [BUSINESS-05-CONTENT-MANAGEMENT](../business/BUSINESS-05-CONTENT-MANAGEMENT.md) | محتوا | Site Pages (Shopify)، بلاگ، مدیریت فایل، SMS/Email، Landing | @@ -76,7 +77,7 @@ 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) | کیف‌پول جادویی — پلن | ۶ فاز، checklist، تخمین زمان، وابستگی ChargeDiscountWallet | +| R2 | [MAGIC-WALLET-PLAN](../roadmap/MAGIC-WALLET-PLAN.md) | کیف‌پول جادویی — پلن | ۶ فاز، **فاز 1-5 تکمیل ✅**، فاز 6 باقی | --- diff --git a/overview/OVERVIEW-03-CHANGELOG.md b/overview/OVERVIEW-03-CHANGELOG.md index 54b1ea5..749ca67 100644 --- a/overview/OVERVIEW-03-CHANGELOG.md +++ b/overview/OVERVIEW-03-CHANGELOG.md @@ -1,7 +1,7 @@ # 📜 تاریخچه کارهای انجام‌شده > **همه فعالیت‌های پروژه به صورت بولت با توضیح یک‌خطی و درصد تکمیل** -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet + VAT 10%) --- @@ -10,11 +10,11 @@ | حوزه | تعداد آیتم | تکمیل‌شده | درصد کل | |------|-----------|----------|---------| | **BackOffice** | 58 | 57 | **98%** | -| **FrontOffice** | 35 | 32 | **91%** | -| **CMS Core** | 45 | 42 | **93%** | +| **FrontOffice** | 38 | 35 | **92%** | +| **CMS Core** | 55 | 52 | **95%** | | **Deployment** | 20 | 18 | **90%** | | **Migration** | 15 | 15 | **100%** | -| **مجموع** | **173** | **164** | **95%** | +| **مجموع** | **186** | **177** | **95%** | --- @@ -86,6 +86,7 @@ - ✅ نمای درخت شبکه — باینری بصری - ✅ امضای قرارداد — OTP + scroll-to-bottom - ✅ صفحه Chatika — چت AI +- ✅ کیف‌پول جادویی — MagicWallet.razor + فرم شارژ + پروگرس‌بار سقف ### محتوا و ناوبری - ✅ بلاگ — لیست + جزئیات + pagination @@ -129,6 +130,17 @@ - ✅ Club Features — activate/deactivate - ✅ DayaLoan Integration — Hangfire + Polly +### 🪄 کیف‌پول جادویی (Magic Wallet) — فاز 1-5 +- ✅ فاز ۱: WalletMode enum + UserWallet fields + ClubMembershipCycle entity + TransactionType (14,15) +- ✅ فاز ۲: Trigger ورود/خروج Magic در SubmitShopBuyOrder + ActivateClubMembership Cycle +- ✅ فاز ۳: ChargeMagicWallet + VerifyMagicWalletCharge + HTTP callback + gRPC RPCs +- ✅ فاز ۴: فیلتر Magic از کمیسیون (C# + SP) + تاریخ Cycle +- ✅ فاز ۵: MagicWallet.razor UI + WalletService + تایل داشبورد +- ⬜ فاز ۶: محدودیت دایا بعد از دور اول + +### VAT +- ✅ اصلاح VAT از 9% به 10% در همه فایل‌ها (VatCalculator, UserOrderService, Checkout, VATService) + ### محتوا - ✅ Blog CRUD — با pagination - ✅ SitePage Settings — JSON typed @@ -194,3 +206,4 @@ | اسفند ۱۴۰۳ (هفته ۲) | Site Pages + BackOffice audit | 75% | | اسفند ۱۴۰۳ (هفته ۳) | Inventory + Lazy Load + Images | 85% | | اسفند ۱۴۰۳ (هفته ۴) | مستندات + نهایی‌سازی | 95% | +| اسفند ۱۴۰۴ | 🪄 کیف‌پول جادویی (فاز 1-5) + اصلاح VAT 10% | 96% | diff --git a/overview/OVERVIEW-04-GLOSSARY.md b/overview/OVERVIEW-04-GLOSSARY.md index 35217e7..d2f66c7 100644 --- a/overview/OVERVIEW-04-GLOSSARY.md +++ b/overview/OVERVIEW-04-GLOSSARY.md @@ -1,7 +1,7 @@ # 📖 واژه‌نامه، استانداردها و قراردادهای کد > **اصطلاحات فارسی/انگلیسی، الگوهای نام‌گذاری و استانداردهای حرفه‌ای** -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet) --- @@ -28,6 +28,11 @@ | وام دایا | Daya Loan | وام آنلاین برای خرید پکیج | | کد معرف | Referral Code | کد یکتا هر عضو برای دعوت | | موجودی | Inventory | تعداد محصول در انبار | +| کیف‌پول جادویی | Magic Wallet | حالت ویژه: Balance=0 → شارژ ×2.5 از درگاه | +| حالت جادویی | Magic Mode | WalletMode=1 — کمیسیون غیرفعال | +| ضریب شارژ | Magic Multiplier | واریز × 2.5 = اعتبار Balance | +| سقف دور | Per-Cycle Cap | 100M تومان واریز → 250M اعتبار | +| دوره عضویت | Membership Cycle | ClubMembershipCycle — هر خرید پکیج = یک دور | ### ۱.۲ مفاهیم فنی diff --git a/overview/OVERVIEW-05-ROADMAP.md b/overview/OVERVIEW-05-ROADMAP.md index 56ae95f..3faf6dd 100644 --- a/overview/OVERVIEW-05-ROADMAP.md +++ b/overview/OVERVIEW-05-ROADMAP.md @@ -1,20 +1,21 @@ # 🗺️ نقشه راه، ریسک‌ها و کارهای باقیمانده > **Roadmap + Risk Register + Dependencies + Priorities** -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet completed) --- ## ۱. وضعیت فعلی پروژه ``` -██████████████████████████████████████████████████ 95% +██████████████████████████████████████████████████ 96% Core Platform ████████████████████████████████████████████████ 98% -Club System █████████████████████████████████████████████░░░ 95% +Club System ████████████████████████████████████████████████ 98% E-Commerce ████████████████████████████████████████████████ 98% -Payment ██████████████████████████████████████░░░░░░░░░ 80% -UI/UX ████████████████████████████████████████░░░░░░░ 85% +Payment ████████████████████████████████████████████░░░░ 90% +Magic Wallet ████████████████████████████████████████░░░░░░░░ 83% +UI/UX ██████████████████████████████████████████░░░░░░ 88% Deployment ████████████████████████████████████████████░░░ 90% Documentation ████████████████████████████████████████████████ 100% ``` @@ -197,8 +198,14 @@ gantt ## ۸. خلاصه اولویت‌بندی ``` +DONE (اسفند ۱۴۰۴): + → Documentation consolidation ✅ + → 🪄 Magic Wallet فاز 1-5 ✅ (فاز 6 باقی) + → اصلاح VAT 9% → 10% ✅ + NOW (این ماه): - → Documentation consolidation ✅ DONE + → Magic Wallet فاز 6 — محدودیت دایا + → EF Migration نهایی NEXT (فروردین): → Mobile Responsive (H2) diff --git a/roadmap/MAGIC-WALLET-PLAN.md b/roadmap/MAGIC-WALLET-PLAN.md index 40940df..369f818 100644 --- a/roadmap/MAGIC-WALLET-PLAN.md +++ b/roadmap/MAGIC-WALLET-PLAN.md @@ -178,31 +178,31 @@ ## Checklist پیاده‌سازی -- [ ] **فاز ۱:** WalletMode enum -- [ ] **فاز ۱:** UserWallet entity + 5 فیلد جدید -- [ ] **فاز ۱:** ClubMembershipCycle entity (جدید) -- [ ] **فاز ۱:** TransactionType + 2 مقدار -- [ ] **فاز ۱:** SystemConstants + 3 ثابت -- [ ] **فاز ۱:** EF Configuration (UserWallet + ClubMembershipCycle) +- [x] **فاز ۱:** WalletMode enum +- [x] **فاز ۱:** UserWallet entity + 5 فیلد جدید +- [x] **فاز ۱:** ClubMembershipCycle entity (جدید) +- [x] **فاز ۱:** TransactionType + 2 مقدار +- [x] **فاز ۱:** SystemConstants + 3 ثابت +- [x] **فاز ۱:** EF Configuration (UserWallet + ClubMembershipCycle) - [ ] **فاز ۱:** Migration: AddMagicWalletFields - [ ] **فاز ۱:** Migration: AddClubMembershipCycle + data seed -- [ ] **فاز ۲:** Trigger ورود Magic (SubmitShopBuyOrder) -- [ ] **فاز ۲:** Trigger خروج Magic -- [ ] **فاز ۲:** ActivateClubMembership → ActivatedAt نگه‌داشته بشه + Cycle جدید -- [ ] **فاز ۲:** PurchaseCycleCount -- [ ] **فاز ۳:** InitiateMagicChargeCommand + Handler -- [ ] **فاز ۳:** VerifyMagicChargeCommand + Handler -- [ ] **فاز ۳:** MagicWalletController (HTTP callback) -- [ ] **فاز ۳:** gRPC Proto + Service -- [ ] **فاز ۳:** ۲ تراکنش + ۱ لاگ (اجباری) -- [ ] **فاز ۴:** فیلتر کمیسیون Magic (C# handler + SP) -- [ ] **فاز ۴:** تاریخ کمیسیون: ActivatedAt → Cycle.PackagePurchasedAt (C# + SP) -- [ ] **فاز ۵:** MagicWallet.razor -- [ ] **فاز ۵:** MagicPaymentCallback.razor -- [ ] **فاز ۵:** WalletService gRPC client -- [ ] **فاز ۵:** Profile + Wallet page updates -- [ ] **فاز ۶:** Daya restriction -- [ ] **فاز ۶:** Club activation restriction +- [x] **فاز ۲:** Trigger ورود Magic (SubmitShopBuyOrder) +- [x] **فاز ۲:** Trigger خروج Magic +- [x] **فاز ۲:** ActivateClubMembership → ActivatedAt نگه‌داشته بشه + Cycle جدید +- [x] **فاز ۲:** PurchaseCycleCount +- [x] **فاز ۳:** InitiateMagicChargeCommand + Handler +- [x] **فاز ۳:** VerifyMagicChargeCommand + Handler +- [x] **فاز ۳:** MagicWalletController (HTTP callback) +- [x] **فاز ۳:** gRPC Proto + Service +- [x] **فاز ۳:** ۲ تراکنش + ۱ لاگ (اجباری) +- [x] **فاز ۴:** فیلتر کمیسیون Magic (C# handler + SP) +- [x] **فاز ۴:** تاریخ کمیسیون: ActivatedAt → Cycle.PackagePurchasedAt (C# + SP) +- [x] **فاز ۵:** MagicWallet.razor +- [x] **فاز ۵:** MagicPaymentCallback — نتیجه پرداخت از طریق ?payment= query param در همان MagicWallet.razor هندل میشه +- [x] **فاز ۵:** WalletService gRPC client +- [x] **فاز ۵:** Profile + Wallet page updates +- [x] **فاز ۶:** Daya restriction (CheckAndProcessDayaLoansCommandHandler + FO Purchase UI) +- [x] **فاز ۶:** Club activation restriction (ActivateClubMembershipCommandHandler + WalletMode guard) --- diff --git a/technical/TECH-01-CMS-ARCHITECTURE.md b/technical/TECH-01-CMS-ARCHITECTURE.md index 4345bb7..8cdcca6 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) --- @@ -139,6 +139,7 @@ public class CreateProductCommandHandler | `SitePageService` | sitepage.proto | GetPage, SaveSettings | | `CategoryService` | category.proto | GetCategories, Create, Update | | `SystemConfigService` | config.proto | GetConfig, UpdateConfig | +| `UserWalletService` | userwallet.proto | GetCustomerWallet, InitiateMagicCharge, GetMagicWalletStatus | ### ۴.۲ PaginationState (مشترک) @@ -180,7 +181,8 @@ Engine: MSSQL 2022-CU16, Collation=Arabic_CI_AS | SitePages | صفحات سایت | ~10 | | UserClubMemberships | عضویت باشگاه | ~500 | | UserContracts | قراردادها (SignGuid, SignedPdfFile) | ~500 | -| UserWallets | کیف‌پول (Balance, NetworkBalance, DiscountBalance) | ~5K | +| UserWallets | کیف‌پول (Balance, NetworkBalance, DiscountBalance, WalletMode) | ~5K | +| ClubMembershipCycles | دوره‌های عضویت (CycleNumber, PackagePurchasedAt, IsCurrentCycle) | ~500 | | Transactions | تراکنش‌ها | ~5K | | SystemConfigurations | تنظیمات | ~30 | | ChatMessages | پیام‌های چاتیکا | ~1K | diff --git a/technical/TECH-02-BACKOFFICE-FRONTOFFICE.md b/technical/TECH-02-BACKOFFICE-FRONTOFFICE.md index b42e72b..4b8e2ec 100644 --- a/technical/TECH-02-BACKOFFICE-FRONTOFFICE.md +++ b/technical/TECH-02-BACKOFFICE-FRONTOFFICE.md @@ -1,7 +1,7 @@ # 🖥️ BackOffice و FrontOffice — معماری UI > **منابع ادغام‌شده:** `BACKOFFICE-ARCHITECTURE.md`, `BACKOFFICE-STORE-UNIFICATION.md`, `UI-MODERNIZATION-PLAN.md`, `UI-UNIFICATION-PLAN.md`, `PHASE-1-COMPLETE.md`, `PHASE-3-COMPLETE.md`, `PRODUCT-IMAGES-SQUARE.md` -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet UI + ProjectReference) --- @@ -111,6 +111,9 @@ FrontOffice/src/FrontOffice/ │ │ ├── Dashboard.razor ← داشبورد باشگاه │ │ ├── NetworkTree.razor ← نمای درخت │ │ └── Contract.razor ← امضای قرارداد +│ ├── Profile/ +│ │ ├── Index.razor ← داشبورد پروفایل + تایل Magic +│ │ └── MagicWallet.razor ← 🪄 کیف‌پول جادویی (NEW) │ ├── Blog/ │ ├── Auth/ │ │ ├── Login.razor @@ -119,6 +122,8 @@ FrontOffice/src/FrontOffice/ ├── Services/ │ ├── ProductService.cs ← با GetProductsPagedAsync │ ├── ClubService.cs +│ ├── WalletService.cs ← + MagicWalletStatus, InitiateMagicChargeAsync +│ ├── VATService.cs ← VAT 10% از سرور + LocalStorage cache │ └── ... └── Shared/ ├── AppImage.razor @@ -247,6 +252,8 @@ if (user.Identity?.IsAuthenticated == true) { | Store Unification | ✅ | 100% | | SitePage Typed Editors | ✅ | 100% | | RTL Support | ✅ | 100% | +| Magic Wallet UI | ✅ | 100% | +| Proto ProjectReference | ✅ | 100% | | Mobile Responsive (Phase 7) | ⬜ | 0% | | Dark Mode | ⬜ | 0% | | PWA | ⬜ | 0% | diff --git a/technical/TECH-05-API-INTEGRATION.md b/technical/TECH-05-API-INTEGRATION.md index 7032bf9..26dc562 100644 --- a/technical/TECH-05-API-INTEGRATION.md +++ b/technical/TECH-05-API-INTEGRATION.md @@ -1,7 +1,7 @@ # 🔌 API، Protobuf و یکپارچه‌سازی خارجی > **منابع ادغام‌شده:** `FRONTOFFICE-CMS-API-COMPATIBILITY.md`, `REMAINING-TASKS.md`, `chatika-integration.md`, `payment-gateway.md`, `club-feature-management-services.md` -> **آخرین بروزرسانی:** اسفند ۱۴۰۴ +> **آخرین بروزرسانی:** اسفند ۱۴۰۴ (بروزرسانی: Magic Wallet gRPC RPCs) --- @@ -125,6 +125,13 @@ service SystemConfigService { rpc UpdateConfig (UpdateConfigRequest) returns (Empty); rpc GetAllConfigs (Empty) returns (ConfigListResponse); } + +// ===== userwallet.proto ===== (NEW — Magic Wallet) +service UserWalletService { + rpc GetCustomerWallet (GetCustomerWalletRequest) returns (GetCustomerWalletResponse); + rpc InitiateMagicCharge (InitiateMagicChargeRequest) returns (InitiateMagicChargeResponse); + rpc GetMagicWalletStatus (GetMagicWalletStatusRequest) returns (MagicWalletStatusResponse); +} ``` ### ۲.۲ Shared Messages @@ -299,9 +306,12 @@ flowchart TD A["CMS/src/Protos/*.proto"] --> B["pack-protos.sh"] B --> C["Foursat.CMSMicroservice.Protobuf.nupkg\nv1.0.x"] C --> D["Push to BaGet / Nexus"] - D --> E["BackOffice + FrontOffice\nPackageReference"] + D --> E["BackOffice\nPackageReference"] + D --> F["FrontOffice\nProjectReference ✅"] ``` +> ⚠️ FrontOffice از NuGet package به **ProjectReference** مستقیم سوییچ شده (برای دسترسی به پروتوهای جدید Magic Wallet) + --- ## ۶. Remaining Tasks / Integration Gaps