docs: consolidate 53 files into 15 structured files in 3 folders

- business/ (5): club-commission, payment, ecommerce, membership, content - technical/ (5): cms-arch, ui, deployment, migration, api - overview/ (5): flowcharts, index, changelog, glossary, roadmap - Removed all old folders: backoffice, cms, deployment, docs, frontoffice, migration, ui-modernization, business (old) - Updated internal links with relative folder paths
2026-02-18 22:29:37 +03:30
parent d7c32dab2a
commit efff5e9cd5
71 changed files with 3632 additions and 32267 deletions
@@ -0,0 +1,223 @@
+# 💰 سیستم مالی، پرداخت و درگاه‌ها
+
+> **منابع ادغام‌شده:** `payment-gateway.md`, `payment-architecture-pyms.md`, `daya-loan-integration.md`, `manual-payment-system.md`, `discount-shop-business.md`  
+> **آخرین بروزرسانی:** اسفند ۱۴۰۴
+
+---
+
+## ۱. معماری کلی مالی
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                    FourSat Payment Architecture                   │
+├──────────────┬──────────────┬──────────────┬─────────────────────┤
+│  ZarinPal    │  Daya Loan   │  Manual Pay  │  Discount Wallet    │
+│  (IPG)       │  (API)       │  (Card2Card) │  (Internal)         │
+├──────────────┴──────────────┴──────────────┴─────────────────────┤
+│                     PYMS (Payment Service)                        │
+│         gRPC ←→ CMS ←→ FrontOffice/BackOffice                   │
+├──────────────────────────────────────────────────────────────────┤
+│                     3 Wallet System                               │
+│     Balance (نقدی) │ NetworkBalance (شبکه) │ DiscountBalance     │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## ۲. درگاه ZarinPal (IPG)
+
+### ۲.۱ فلوی پرداخت
+
+```
+کاربر → انتخاب محصول → درخواست پرداخت
+    │
+    ▼
+CMS → CreatePaymentRequest (gRPC to PYMS)
+    │
+    ▼
+PYMS → ZarinPal API → دریافت Authority
+    │
+    ▼
+Redirect کاربر → صفحه پرداخت ZarinPal
+    │
+    ▼
+بازگشت با Authority → CMS VerifyPayment
+    │
+    ├─→ موفق: ثبت سفارش + شارژ کیف‌پول (در صورت نیاز)
+    └─→ ناموفق: نمایش پیام خطا
+```
+
+### ۲.۲ تنظیمات ZarinPal
+
+| پارامتر | مقدار |
+|----------|-------|
+| `MerchantId` | از appsettings |
+| `CallbackUrl` | `/payment/callback` |
+| `Sandbox` | true (staging) / false (production) |
+| `Currency` | IRR (ریال → تبدیل به تومان در UI) |
+
+---
+
+## ۳. سیستم وام دایا (DayaLoan)
+
+### ۳.۱ معماری
+
+```
+Hangfire Recurring Job (هر ۱۵ دقیقه)
+    │
+    ▼
+DayaLoanProcessorJob.Execute()
+    │
+    ▼
+بررسی LoanRequests با Status=Pending
+    │
+    ▼
+برای هر درخواست:
+    ├─→ ارسال به DayaLoan API (با Polly retry ×3)
+    ├─→ در صورت تأیید: شارژ ۳ کیف‌پول (هرکدام ۵۶M)
+    ├─→ ثبت Transaction + Log
+    └─→ در صورت رد: بروزرسانی Status=Rejected + ارسال SMS
+```
+
+### ۳.۲ Mock Mode
+
+```csharp
+// appsettings.json
+"DayaLoan": {
+    "UseMock": true,         // staging
+    "BaseUrl": "https://api.dayaloan.ir",
+    "ApiKey": "***",
+    "AutoApproveInMock": true
+}
+```
+
+### ۳.۳ مقادیر
+
+| آیتم | مقدار |
+|------|-------|
+| مبلغ وام | ۵۶,۰۰۰,۰۰۰ تومان |
+| شارژ هر کیف‌پول | ۵۶,۰۰۰,۰۰۰ تومان |
+| مجموع شارژ | ۱۶۸,۰۰۰,۰۰۰ تومان |
+| بازپرداخت | طبق شرایط دایا |
+
+---
+
+## ۴. پرداخت دستی (کارت‌به‌کارت)
+
+> ⚠️ **وضعیت: طراحی‌شده — پیاده‌سازی نشده**
+
+```
+فلوی پیشنهادی:
+    کاربر → انتخاب "کارت‌به‌کارت"
+    │
+    ▼
+    نمایش شماره‌کارت مقصد + مبلغ
+    │
+    ▼
+    کاربر → واریز + آپلود تصویر رسید
+    │
+    ▼
+    ادمین BackOffice → مشاهده لیست درخواست‌ها
+    │
+    ▼
+    تأیید/رد → شارژ خودکار کیف‌پول
+```
+
+**موجودیت‌های مورد نیاز:**
+- `ManualPaymentRequest` (UserId, Amount, ReceiptImage, Status, AdminNote)
+- `ManualPaymentStatus` enum: Pending, Approved, Rejected
+
+---
+
+## ۵. پرداخت ترکیبی فروشگاه تخفیفی (Hybrid Payment)
+
+### ۵.۱ فرمول
+
+```
+قیمت محصول = 1,000,000 تومان
+تخفیف باشگاه = 30%
+
+پرداخت از DiscountBalance = 1,000,000 × 0.30 = 300,000
+پرداخت نقدی (IPG)      = 1,000,000 × 0.70 = 700,000
+                                            ─────────
+                          مجموع             = 1,000,000
+```
+
+### ۵.۲ فلوی خرید فروشگاه تخفیفی
+
+```
+کاربر (عضو باشگاه) → مشاهده محصول
+    │
+    ▼
+قیمت تخفیف‌خورده نمایش داده می‌شود
+    │
+    ▼
+افزودن به سبد → بررسی DiscountBalance
+    │
+    ├─→ DiscountBalance کافی:
+    │       سهم تخفیف از DiscountBalance کسر
+    │       باقیمانده → IPG (ZarinPal)
+    │
+    └─→ DiscountBalance ناکافی:
+            فقط به اندازه موجودی از تخفیف
+            باقیمانده بیشتر → IPG
+```
+
+### ۵.۳ دسترسی فروشگاه تخفیفی
+
+| شرط | نتیجه |
+|------|--------|
+| `IsClubMember = true` | دسترسی به Discount Store |
+| `IsClubMember = false` | فقط Regular Store |
+| `DiscountBalance > 0` | می‌تواند از تخفیف استفاده کند |
+| `DiscountBalance = 0` | پرداخت ۱۰۰% نقدی |
+
+---
+
+## ۶. PYMS — سرویس پرداخت مرکزی
+
+### ۶.۱ gRPC Services
+
+```protobuf
+service PaymentService {
+    rpc CreatePayment (CreatePaymentRequest) returns (CreatePaymentResponse);
+    rpc VerifyPayment (VerifyPaymentRequest) returns (VerifyPaymentResponse);
+    rpc GetPaymentStatus (GetPaymentStatusRequest) returns (PaymentStatusResponse);
+    rpc RefundPayment (RefundPaymentRequest) returns (RefundPaymentResponse);
+}
+```
+
+### ۶.۲ Transaction Types
+
+| نوع | کد | توضیح |
+|-----|-----|--------|
+| PackagePurchase | 1 | خرید پکیج طلایی |
+| StorePurchase | 2 | خرید از فروشگاه |
+| DiscountStorePurchase | 3 | خرید از فروشگاه تخفیفی |
+| CommissionPayout | 4 | واریز کمیسیون هفتگی |
+| WalletCharge | 5 | شارژ مستقیم کیف‌پول |
+| ActivationFee | 6 | هزینه فعالسازی |
+| DayaLoanCharge | 7 | شارژ از وام دایا |
+
+---
+
+## ۷. مالیات و VAT
+
+```
+VAT = 10%  (configurable via SystemConstants)
+قیمت نمایشی = قیمت پایه × (1 + VAT)
+در صورتحساب: قیمت پایه + مالیات جداگانه نمایش داده می‌شود
+```
+
+---
+
+## ۸. خلاصه وضعیت پیاده‌سازی
+
+| ماژول | وضعیت | یادداشت |
+|-------|--------|---------|
+| ZarinPal IPG | ✅ کامل | Production ready |
+| وام دایا | ✅ کامل | Mock mode فعال در staging |
+| پرداخت ترکیبی | ✅ کامل | Discount + IPG |
+| Pool هفتگی | ✅ کامل | SP + Hangfire |
+| پرداخت دستی | ⬜ طراحی | نیاز به تصمیم مدیریت |
+| Refund | ⬜ طراحی | فقط در PYMS تعریف‌شده |