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