ehsan-dashboards/dashboards/blu/FINANCIAL_AND_WALLET_PROCEDURES.md

7.3 KiB
Executable file
Raw Blame History

مستندات فنی و منطق محاسباتی سیستم مالی و کیف پول اکیپا

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