Skip to main content
#P1682

GET /v2/charter/financial/completion

Charter: Get Completion Financial Report

این اندپوینت برای ارائه یک گزارش تکمیل مالی و تحلیلی از یک چارتر طراحی شده است. این گزارش فراتر از تجمیع ساده داده‌های فروش رفته و با محاسبه شاخص‌های کلیدی عملکرد (KPIs) مانند هزینه کل خرید ظرفیت (Paid)، سود یا زیان (Profit)، و هزینه ظرفیت فروخته‌نشده (Burned)، یک دید ۳۶۰ درجه از وضعیت مالی چارتر ارائه می‌دهد.
خروجی این اندپوینت در چهار بخش اصلی سازماندهی شده است:

  1. Classes: گزارش دقیق مالی به تفکیک هر آیتم (کلاس پروازی/نوع اتاق) به همراه محاسبات سود و زیان.
  2. Pledgers: گزارش تجمیعی فروش برای رزروهای تعهد شده توسط همکاران.
  3. Warranties: گزارش تجمیعی فروش برای رزروهای گارانتی شده.
  4. Total: یک شیء جامع که کل شاخص‌های مالی چارتر را در خود جمع‌بندی می‌کند.

 

Request Overview

URL: /v2/charter/financial/completion
Method: GET
Controller: CharterController@getCompletionFinancialCharter
Middleware Stack: authWithJwt

Access Control

  • دسترسی معتبر JWT

Query Parameters

Field Type Description
id integer (الزامی) شناسه اصلی چارتر (main_id) که گزارش برای آن درخواست شده است.

Example Request

GET /v2/charter/financial/completion?id=451

Logic Details

منطق این اندپوینت در دو فاز اصلی اجرا می‌شود: فاز اول تجمیع داده‌های اولیه و فاز دوم محاسبه شاخص‌های مالی پیشرفته.

فاز اول: واکشی و تجمیع داده‌های اولیه

  • شناسایی جداول و واکشی داده‌ها: مانند اندپوینت قبلی، ابتدا جداول مربوطه شناسایی شده و تمام رزروها (`reserves`) و آیتم‌های محاسباتی (`calculations`) واکشی می‌شوند.
  • ساخت نقشه قیمت خرید (`$buyPrice`): یک نقشه از قیمت‌های خرید برای هر آیتم و رده سنی ساخته می‌شود. همچنین ظرفیت کل چارتر (`total.capacity`) با جمع کردن ظرفیت تمام آیتم‌ها محاسبه می‌شود.
  • حلقه اصلی روی رزروها: سیستم روی تمام رزروها حلقه می‌زند و داده‌ها را تجمیع می‌کند:
    • تجمیع در `classes`: داده‌های مالی هر رزرو (شامل count, payable, buy, taxes, commissions, markups) بر اساس `item_id` و رده سنی در `return['classes']` جمع می‌شوند.
    • تجمیع در `total`: مقادیر کلیدی هر رزرو (count, payable, buy, taxes, و ...) مستقیماً به شیء `return['total']` نیز اضافه می‌شوند تا جمع کل چارتر به دست آید.
    • تجمیع در `pledgers` و `warranties`: اگر رزرو دارای گارانتی یا تعهد باشد، داده‌های فروش آن (تعداد و مبلغ قابل پرداخت) در دسته‌بندی مربوطه نیز تجمیع می‌شود.

فاز دوم: محاسبه شاخص‌های سود و زیان ( حلقه دوم)

پس از اتمام حلقه اول و تجمیع داده‌های پایه، یک حلقه دوم روی آرایه تجمیع‌شده return['classes'] اجرا می‌شود تا محاسبات پیشرفته برای هر آیتم انجام شود:

  1. محاسبه هزینه کل آیتم (Paid):
    • فرمول: (Total Buy Price / Items Sold) * Total Capacity
    • توضیح: این مقدار، هزینه واقعی است که شرکت برای کل ظرفیت یک آیتم (چه فروخته شده و چه نشده) پرداخت کرده است. این محاسبه بر اساس میانگین قیمت خرید صندلی/اتاق‌های فروخته شده انجام می‌شود.
  2. محاسبه هزینه سوخت‌شده (Burned):
    • فرمول: Average Buy Price * (Total Capacity - Items Sold)
    • توضیح: این مقدار نشان‌دهنده هزینه ظرفیت فروخته‌نشده یا "سوخت‌شده" است. این یکی از مهم‌ترین شاخص‌ها برای ارزیابی عملکرد فروش است.
  3. محاسبه سود/زیان (Profit):
    • فرمول: Total Payable - Total Item Cost (Paid)
    • توضیح: این مقدار، تفاوت بین کل درآمد حاصل از فروش یک آیتم و کل هزینه پرداخت شده برای آن آیتم است. اگر مثبت باشد سود و اگر منفی باشد زیان را نشان می‌دهد.
  4. تشخیص وضعیت مالی (Diagnosis):
    • بر اساس مقدار `profit`، یک وضعیت متنی تعیین می‌شود:
      • creditor: بستانکار (سودده)
      • debtor: بدهکار (زیان‌ده)
      • neutral: سربه‌سر
  5. تجمیع نهایی در `total`: مقادیر محاسبه شده (`paid`, `burned`, `profit`) برای هر آیتم، به مقادیر متناظر در شیء `return['total']` اضافه می‌شوند تا جمع‌بندی نهایی برای کل چارتر به دست آید.

محاسبه نهایی

  • در انتها، یک `diagnosis` نهایی برای کل چارتر بر اساس مقادیر `total.payable` و `total.paid` محاسبه و در `return['total']` قرار می‌گیرد.

Response Structure

پاسخ موفق

پاسخ موفق 200 OK حاوی یک شیء `payload` با ساختاری بسیار غنی است که شامل بخش `total` در کنار سه بخش دیگر می‌باشد.

  • Status Code: 200 OK
  • Body: 
    {
  "payload": {
    "classes": {
      "1234": { // Key is the item_id
        "title": { "en": "Y | Economy/Coach", "fa": "Y | اکونومی - Economy/Coach" },
        "age": {
          "adl": { "count": 10, "payable": 12000000, "buy": 10000000, "buy_per": 1000000, "taxes": 1080000, "commissions": 600000, "markups": 0 },
          "chd": { "count": 2, "payable": 2000000, "buy": 1600000, "buy_per": 800000, "taxes": 180000, "commissions": 100000, "markups": 0 },
          "inf": { "count": 1, "payable": 150000, "buy": 100000, "buy_per": 100000, "taxes": 0, "commissions": 0, "markups": 0 }
        },
        "financial": {
          "count": 13,
          "capacity": 20,
          "payable": 14150000,
          "buy": 11700000,
          "burned": 6300000,  // <-- New Field
          "paid": 18000000,     // <-- New Field
          "profit": -3850000,   // <-- New Field
          "diagnosis": "debtor", // <-- New Field
          "taxes": 1260000,
          "commissions": 700000,
          "markups": 0
        }
      }
      // ... other classes
    },
    "pledgers": { /* ... Same structure as previous endpoint ... */ },
    "warranties": { /* ... Same structure as previous endpoint ... */ },
    "changes": [],
    "total": { // <-- New Object
      "count": 13,
      "capacity": 20,
      "payable": 14150000,
      "buy": 11700000,
      "burned": 6300000,
      "profit": -3850000,
      "diagnosis": "debtor",
      "paid": 18000000,
      "taxes": 1260000,
      "commissions": 700000,
      "markups": 0
    }
  },
  "meta": { "timestamp": 1733290800 }
}

پاسخ خطا

در صورت بروز خطا، پاسخ 400 Bad Request با جزئیات استثنا بازگردانده می‌شود.

  • Status Code: 400 Bad Request
  • Body: 
    {
  "message": "Error details...",
  "trace": [
    // ... Stack trace for debugging ...
  ]
}

Helper Functions

این اندپوینت از همان توابع کمکی اندپوینت قبلی برای ترجمه نام کلاس و محاسبه مقادیر درصدی/ثابت استفاده می‌کند.

Functions::getClassName($class, $lang)

ReservationController::priceHandle($price, $values)

Flowchart

Start (GET /financial/completion)
↓
Phase 1: Aggregation
1. Fetch `reserves` & `calculations`.
2. Build `$buyPrice` map.
3. Loop `reserves` to populate initial `classes`, `pledgers`, `warranties`, and `total` (buy, payable, counts).
↓
Phase 2: Profit Calculation
1. Loop through aggregated `classes`.
2. For each class, calculate:
- `paid` (Total Item Cost)
- `burned` (Unsold Cost)
- `profit` (Payable - Paid)
- `diagnosis` (creditor/debtor)
3. Add these results to `total` object.
↓
Final Step
Calculate final `diagnosis` for the `total` object.
↓
Return 200 OK with full `payload` (including `total` and calculated fields)
→ On Any Exception
Return 400 with Exception Details
Back to top