108 lines
7.3 KiB
Markdown
Executable file
108 lines
7.3 KiB
Markdown
Executable file
# مستندات فنی و منطق محاسباتی سیستم مالی و کیف پول اکیپا
|
||
|
||
این سند حاوی منطق دقیق، فرمولها و ساختار پایگاهداده مربوط به ۳ پرسیجر و جداول اصلی مالی اکیپا روی دیتابیس 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}$$
|