# GET /v2/charter/financial/completion

# Charter: Get Completion Financial Report

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

<div class="api-docs" id="bkmrk-classes%3A-%DA%AF%D8%B2%D8%A7%D8%B1%D8%B4-%D8%AF%D9%82%DB%8C%D9%82-">1. **Classes:** گزارش دقیق مالی به تفکیک هر آیتم (کلاس پروازی/نوع اتاق) به همراه محاسبات سود و زیان.
2. **Pledgers:** گزارش تجمیعی فروش برای رزروهای تعهد شده توسط همکاران.
3. **Warranties:** گزارش تجمیعی فروش برای رزروهای گارانتی شده.
4. **Total:** یک شیء جامع که کل شاخص‌های مالی چارتر را در خود جمع‌بندی می‌کند.

</div><div class="api-docs" id="bkmrk-"></div>## Request Overview

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcharter%2Ffin"><div class="endpoint-info"><div>**URL:** `/v2/charter/financial/completion`</div><div>**Method:** <span class="method-get">GET</span></div><div>**Controller:** CharterController@getCompletionFinancialCharter</div><div>**Middleware Stack:** authWithJwt</div></div></div>## Access Control

<div class="api-docs" id="bkmrk-%D8%AF%D8%B3%D8%AA%D8%B1%D8%B3%DB%8C-%D9%85%D8%B9%D8%AA%D8%A8%D8%B1-jwt">- دسترسی معتبر JWT

</div>## Query Parameters

<div class="api-docs" id="bkmrk-field-type-descripti"><table class="schema-table" dir="rtl"><thead><tr><th>Field</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>id</td><td>integer</td><td>**(الزامی)** شناسه اصلی چارتر (`main_id`) که گزارش برای آن درخواست شده است.</td></tr></tbody></table>

</div>#### Example Request

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

<div class="api-docs" id="bkmrk--1"></div>## Logic Details

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

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

<div class="api-docs" id="bkmrk-%D8%B4%D9%86%D8%A7%D8%B3%D8%A7%DB%8C%DB%8C-%D8%AC%D8%AF%D8%A7%D9%88%D9%84-%D9%88-%D9%88%D8%A7%DA%A9%D8%B4">- **شناسایی جداول و واکشی داده‌ها:** مانند اندپوینت قبلی، ابتدا جداول مربوطه شناسایی شده و تمام رزروها (`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`:** اگر رزرو دارای گارانتی یا تعهد باشد، داده‌های فروش آن (تعداد و مبلغ قابل پرداخت) در دسته‌بندی مربوطه نیز تجمیع می‌شود.

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

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

<div class="api-docs" id="bkmrk-%D9%85%D8%AD%D8%A7%D8%B3%D8%A8%D9%87-%D9%87%D8%B2%DB%8C%D9%86%D9%87-%DA%A9%D9%84-%D8%A2%DB%8C%D8%AA%D9%85">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'\]` اضافه می‌شوند تا جمع‌بندی نهایی برای کل چارتر به دست آید.

</div>### محاسبه نهایی

<div class="api-docs" id="bkmrk-%D8%AF%D8%B1-%D8%A7%D9%86%D8%AA%D9%87%D8%A7%D8%8C-%DB%8C%DA%A9-%60diagno">- در انتها، یک `diagnosis` نهایی برای کل چارتر بر اساس مقادیر `total.payable` و `total.paid` محاسبه و در `return\['total'\]` قرار می‌گیرد.

</div>## Response Structure

### پاسخ موفق

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

<div class="api-docs" id="bkmrk-status-code%3A-200-ok-">- **Status Code:** `200 OK`
- **Body:**```json
    {
      "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 }
    }
    ```

</div>### پاسخ خطا

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

<div class="api-docs" id="bkmrk-status-code%3A-400-bad">- **Status Code:** `400 Bad Request`
- **Body:**```json
    {
      "message": "Error details...",
      "trace": [
        // ... Stack trace for debugging ...
      ]
    }
    ```

</div>## Helper Functions

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

#### `Functions::getClassName($class, $lang)`

```php

```

#### `ReservationController::priceHandle($price, $values)`

```php

```

<div class="api-docs" id="bkmrk--4"></div>## Flowchart

<div class="api-docs" id="bkmrk-start-%28get-%2Ffinancia"><div class="flowchart"><div class="flow-item">Start (GET /financial/completion)</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e3f2fd;">**Phase 1: Aggregation**  
1. Fetch `reserves` &amp; `calculations`.  
2. Build `$buyPrice` map.  
3. Loop `reserves` to populate initial `classes`, `pledgers`, `warranties`, and `total` (buy, payable, counts).</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #fffde7; border: 1px solid #fbc02d;">**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.</div><div class="flow-arrow">↓</div><div class="flow-item-process" style="background-color: #e8f5e9;">**Final Step**  
Calculate final `diagnosis` for the `total` object.</div><div class="flow-arrow">↓</div><div class="flow-item-success">Return 200 OK with full `payload` (including `total` and calculated fields)</div><div class="flow-error-path" style="margin-top: 20px;"><div class="flow-arrow-error">→ On Any Exception</div><div class="flow-item-error">Return 400 with Exception Details</div></div></div></div>