ehsan-dashboards/dashboards/blu/FINANCIAL_AND_WALLET_PROCEDURES.md

108 lines
7.3 KiB
Markdown
Executable file
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# مستندات فنی و منطق محاسباتی سیستم مالی و کیف پول اکیپا
این سند حاوی منطق دقیق، فرمول‌ها و ساختار پایگاه‌داده مربوط به ۳ پرسیجر و جداول اصلی مالی اکیپا روی دیتابیس PostgreSQL است.
---
## ۱. چرخه کلی سیستم مالی (Financial Lifecycle)
سیستم مالی اکیپا از طریق ۳ پرسیجر خودکار عمل می‌کند:
1. **`sp_reservation_payable()`**: محاسبه دقیق سهم فروشنده/برگزارکننده، اعمال کد تخفیف، پیش‌پرداخت، جریمه کنسلی‌ها و ذخیره در جدول `reservation_payable`.
2. **`sp_wallet_transactions()`**: شارژ بستانکاری رزروها در کیف پول و کسر هزینه‌های پکیج‌های تبلیغاتی پروموشن B2B با اعمال سقف ۱۵ میلیون تومان در جدول `wallet_transactions`.
3. **`sp_wallet_settlement()`**: ثبت تراکنش‌های تسویه بانکی و واریز وجه به شماره شبا برگزارکننده بر اساس جدول `financial_report`.
---
## ۲. پرسیجر اول: `sp_reservation_payable()`
### ورودی‌ها و داده‌های پایه
- **جدول مقصد:** `reservation_payable`
- **جداول منبع:** `reservations`, `payments`, `discount_codes`, `reservation_cancellations`, `rooms`, `room_dependents`
- **فیلتر زمانی جاری:** `reservations.date >= '2026-09-06 00:00:00+03:30'` (رزروهای غیر کنسلی ۶)
### متغیرهای کلیدی
- **قیمت کل سانس (`finalsans_price`):**
$$\text{finalsans\_price} = \text{base\_price} \times \text{number\_of\_players} \times \frac{100 - \text{discount\_percent}}{100}$$
- **پیش‌پرداخت خالص (`pish_pardakht`):**
- کارمزد ثابت (FIXED): $\text{amount} - \text{fee\_amount}$
- کارمزد درصدی (PERCENTAGE): $\frac{\text{amount} \times 100}{100 + \text{fee\_amount}}$
- **کد تخفیف کارمزد (`cfc_value`):**
اگر شناسه ارائه‌دهنده یا اتاق به صورت Base64 در کد باشد، ۵ درصد از کارمزد اکیپا کاسته می‌شود:
$$\text{Final Commission} = \max(\text{commission} - \text{cfc\_value}, 5\%)$$
(کف کارمزد اکیپا همیشه ۵٪ است).
### فرمول محاسبه سهم فروشنده (`payable_to_seller`)
1. **رزرو موفق (`status = 2`):**
$$\text{payable} = \min(\text{pish\_pardakht}, \text{final\_price} - \text{effective\_discount}) - \left( (\text{final\_price} - \text{brand\_discount}) \times \frac{\text{final\_commission}}{100} \right) + (\text{effective\_discount} - \text{brand\_discount})$$
*نکته:* مبلغ کارمزد از پیش‌پرداخت آنلاین کسر شده و مابه‌التفاوت تخفیف‌های سایت به فروشنده برمی‌گردد. تمام مبالغ به **تومان** است.
2. **کنسلی توسط مجموعه/برند (`status = 3`):**
$$\text{payable} = -1 \times \text{brand\_penalty}$$
3. **کنسلی توسط کاربر/پلیر (`status = 5`):**
$$\text{payable} = \text{player\_penalty} - \left( \text{player\_penalty} \times \frac{\text{final\_commission}}{100} \right)$$
### قوانین جریمه کنسلی‌ها (Penalties)
#### الف) اتاق‌های فرار استاندارد:
- **کنسلی توسط برند:**
- تا ۴۵ دقیقه پس از رزرو: ۰ تومان
- تا ۳ ساعت مانده به سانس: ۵۰٪ پیش‌پرداخت مصوب
- بیش از ۳ ساعت مانده به سانس: ۱۰٪ کل مبلغ سانس
- **کنسلی توسط کاربر:**
- تا ۳۰ دقیقه پس از رزرو: ۰ تومان (عودت کامل به کاربر)
- تا ۱۲ ساعت مانده به سانس: ۱۰۰٪ پیش‌پرداخت به عنوان جریمه کسر می‌شود.
- بین ۱۲ تا ۲۴ ساعت مانده به سانس: ۵۰٪ پیش‌پرداخت به عنوان جریمه.
- بیش از ۲۴ ساعت مانده به سانس: ۰ تومان جریمه (عودت کامل).
#### ب) رویداد، تور، سفر، کلاس، بردگیم، تجربه:
- **کنسلی توسط برند:**
- تا ۱ ساعت پس از رزرو یا بیش از ۷۲ ساعت مانده: ۰ تومان.
- بین ۲۴ تا ۷۲ ساعت مانده: ۱۰٪ کل مبلغ.
- کمتر از ۲۴ ساعت مانده: ۲۰٪ کل مبلغ.
- **کنسلی توسط کاربر:**
- تا ۱ ساعت پس از رزرو یا بیش از ۷۲ ساعت مانده: ۰ تومان.
- بین ۲۴ تا ۷۲ ساعت مانده: ۳۰٪ کل مبلغ.
- کمتر از ۲۴ ساعت مانده: ۱۰۰٪ کل مبلغ سانس.
---
## ۳. پرسیجر دوم: `sp_wallet_transactions()`
این پرسیجر دو بخش اصلی دارد:
### بخش اول: شارژ بستانکاری رزرو (`type = 'reservation'`)
- واکشی فیلد `payable` از جدول `reservation_payable` به عنوان مبلغ مثبت (`amount > 0`).
- وضعیت: ۱ (تایید شده).
### بخش دوم: کسر هزینه پکیج‌های تبلیغاتی B2B (`type = 'promotion'`)
- اتصال به جدول `package_history` به ازای پکیج‌های فعال در بازه تاریخی با `payment_type = 1` (پکیج‌های درصدی/کارمزدی).
- محاسبه هزینه خام پکیج:
$$\text{raw\_amount} = \text{percentage\_rate} \times (\text{final\_price} - \text{brand\_discount})$$
- **اعمال سقف تجمعی ۱۵,۰۰۰,۰۰۰ تومان:**
- با استفاده از Window Function جمع تجمعی هزینه‌ها به ترتیب تاریخ محاسبه می‌شود.
- اگر جمع قبلی پکیج به ۱۵ میلیون تومان رسیده باشد: هزینه ۰ منظور می‌شود.
- اگر با این رزرو از ۱۵ میلیون تومان عبور کند: فقط تا سقف ۱۵ میلیون کسر می‌شود.
- مبالغ به صورت منفی (`amount < 0`) در `wallet_transactions` ثبت می‌شوند.
---
## ۴. پرسیجر سوم: `sp_wallet_settlement()`
- **جدول منبع:** `public.financial_report`
- **نوع تراکنش:** `'settlement'` (منفی)
- **تبدیل واحد:** مبالغ در `financial_report` به ریال هستند و بر ۱۰ تقسیم می‌شوند:
$$\text{amount} = \frac{\text{fr.amount}}{10} \times (-1)$$
- **اطلاعات متادیتا:** شماره تراکنش، شماره شبا، نام دارنده حساب، بانک مقصد و تاریخ شمسی انتقال.
---
## ۵. ساختار انواع تراکنش‌های کیف پول (`wallet_transactions`)
| نوع تراکنش (`type`) | علامت مبلغ | کاربرد |
|---|---|---|
| `reservation` | مثبت (+) | سهم فروشنده از رزروهای موفق یا جریمه کنسلی کاربر |
| `promotion` | منفی (-) | کسر هزینه پکیج‌های پروموشن بازاریابی (با سقف ۱۵ میلیون) |
| `settlement` | منفی (-) | تسویه و واریز پول به حساب بانکی شبا مجموعه‌دار |
| `manual` | مثبت/منفی | اصلاحیه‌های دستی تیم مالی |
**موجودی نهایی کیف پول مجموعه‌دار:**
$$\text{Wallet Balance} = \sum (\text{amount}) \quad \text{به ازای status = 1}$$