docs/business/BUSINESS-02-PAYMENT-FINANCE.md

💰 سیستم مالی، پرداخت و درگاه‌ها

منابع ادغام‌شده: 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

// 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

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 تعریف‌شده