# Function getFinancialCharter ### #### · هدف: این متد به عنوان یک موتور گزارش‌گیری مالی جامع برای یک چارتر خاص عمل می‌کند. هدف اصلی آن محاسبه و تجمیع تمام داده‌های مالی مرتبط با یک چارتر، از جمله درآمد، هزینه، سود، زیان، و مبالغ سوخت شده است. متد با واکشی تمام رزروهای قطعی، اطلاعات مالی هر رزرو را پردازش کرده و بر اساس کلاس (آیتم) و گروه سنی (`adult`, `child`, `infant`) دسته‌بندی می‌کند. همچنین، رزروهای گارانتی شده را شناسایی و در گروه‌های جداگانه‌ای بر اساس نوع گارانتی (`pledgers`, `warranties`) و شخص گارانتی‌کننده، دسته‌بندی می‌کند. در نهایت، متد مقادیر کلیدی مانند مبلغ پرداختی (`paid`), سود/زیان (`profit`), هزینه سوخت شده (`burned`) و تشخیص وضعیت کلی (`diagnosis`: `creditor`, `debtor`, `neutral`) را هم به تفکیک هر کلاس و هم به صورت مجموع برای کل چارتر محاسبه و ارائه می‌دهد.
**ویژگی‌ها****توضیحات**
**هدف کلی**ارائه گزارش مالی کامل و دقیق از عملکرد یک چارتر.
**تجمیع داده**پردازش و جمع‌بندی اطلاعات مالی از تمام رزروهای قطعی.
**دسته‌بندی دقیق**تفکیک آمار بر اساس کلاس/آیتم، گروه سنی و نوع گارانتی.
**محاسبات کلیدی**محاسبه `paid`, `payable`, `profit`, `burned`, `taxes`, `commissions`.
**تشخیص وضعیت**تعیین وضعیت نهایی چارتر به عنوان بستانکار، بدهکار یا خنثی.
**بهینه‌سازی**استفاده از یک حلقه برای پردازش تمام رزروها و تجمیع نتایج در یک ساختار داده واحد.
**گزارش گارانتی**شناسایی و دسته‌بندی جداگانه رزروهای انجام شده تحت پوشش گارانتی.
--- #### · ورودی‌ها (پارامتر‌ها):
**توضیحات****موقعیت****نوع داده****نام پارمتر**
**شناسه چارتر اصلی که گزارش مالی آن مورد نیاز است.****`Route/Body`****`integer`****`$request->id`**
--- #### · خروجی (Return):
**توضیحات****نوع داده**
**یک آبجکت `JSON` با کلید `payload`. این آبجکت شامل `information` (اطلاعات کلی چارتر)، `classes` (آرایه‌ای از کلاس‌ها با جزئیات مالی هر کدام)، `pledgers` و `warranties` (گروه‌بندی رزروهای گارانتی) و `total` (اعداد و ارقام مجموع) است.****`Illuminate\Http\JsonResponse`**
**در صورت بروز خطا، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.****`Illuminate\Http\JsonResponse`**
--- #### · مثال استفاده / سناریو: **سناریو: درخواست گزارش مالی برای چارتر پرواز با شناسه ۴۵۰** - **Request:** - `id`: 450 - **Action:** 1. اطلاعات اولیه چارتر ۴۵۰ و کلاس‌های آن واکشی می‌شود. 2. تمام رزروهای قطعی مربوط به این چارتر از دیتابیس خوانده می‌شوند. 3. متد روی هر رزرو حلقه می‌زند: a. اطلاعات مالی (خرید، فروش، کمیسیون، …) و گروه سنی استخراج می‌شود. b. این مقادیر به مجموع کل و مجموع کلاس مربوطه اضافه می‌شود. c. اگر رزرو گارانتی باشد، در گروه `pledgers` یا `warranties` نیز ثبت می‌شود. 4. پس از پایان حلقه، محاسبات نهایی (سود، سوخت شده، …) روی مقادیر تجمیع شده انجام می‌شود. - **Response:** - `HTTP Status`: `200 OK` - `Body`:
json
``` { "payload": { "information": { ... }, "classes": { "980": { "title": "Economy", "financial": { "paid": 50000000, "payable": 48000000, "profit": -2000000, "burned": 5000000, "diagnosis": "debtor", ... }, ... }, "981": { ... } }, "total": { "paid": 80000000, "payable": 79000000, "profit": -1000000, "burned": 5000000, "diagnosis": "debtor" }, "pledgers": { ... }, "warranties": { ... } }, "meta": { "timestamp": ... } } ```