docs: Magic Wallet + VAT 10% documentation update
- 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
This commit is contained in:
masoodafar-web
@@ -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; } // دور فعلی
|
||||
}
|
||||
```
|
||||
|
||||
@@ -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 پیادهسازی شده |
|
||||
|
||||
@@ -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["مشترک"]
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
@@ -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، هر محصول جداگانه |
|
||||
|
||||
Reference in New Issue
Block a user