# Function listWarrantyCharter ### #### · هدف: این متد وظیفه واکشی و آماده‌سازی لیست گارانتی‌های مرتبط با یک چارتر خاص را بر عهده دارد. پس از استخراج رکوردهای گارانتی از جدول `charter_warranties`، متد برای هر گارانتی، اطلاعات تکمیلی مهمی را از منابع دیگر واکشی و به آبجکت خروجی ضمیمه می‌کند. اولاً، اطلاعات گارانتی‌کننده (همکار) را با اولویت از کش Redis (`colleagues:{id}`) می‌خواند و در صورت عدم وجود، از دیتابیس استعلام کرده و در کش ذخیره می‌کند. ثانیاً، اگر چارتر از نوع اقامتی باشد، جزئیات اتاق‌های گارانتی شده (مانند تعداد، کلاس و…) را از جدول `charter_warranty_accommodation_rooms` استخراج می‌کند. در نهایت، با فراخوانی `ReservationController::capacityItemCharter`، ظرفیت فعلی آیتم‌های گارانتی شده را محاسبه کرده و به خروجی اضافه می‌کند. این فرآیند یک نمای کامل و جامع از هر گارانتی، شامل جزئیات مالی، اطلاعات گارانتی‌کننده، ظرفیت و اتاق‌های مرتبط را فراهم می‌کند.
**ویژگی‌ها****توضیحات**
**هدف کلی**واکشی و نمایش لیست کامل گارانتی‌های یک چارتر.
**واکشی اصلی**استعلام از جدول `charter_warranties` بر اساس `main_id`.
**بهینه‌سازی با کش**خواندن اطلاعات گارانتی‌کننده (همکار) از Redis و ذخیره‌سازی در صورت نیاز.
**اطلاعات تکمیلی**ضمیمه کردن جزئیات اتاق‌های گارانتی شده برای چارتراهای اقامتی.
**محاسبه ظرفیت**محاسبه و افزودن ظرفیت فعلی (کل، باقیمانده، فروخته‌شده) برای هر آیتم گارانتی.
**خروجی جامع**تجمیع اطلاعات از جداول و کش‌های مختلف برای ارائه یک آبجکت کامل.
--- #### · ورودی‌ها (پارامتر‌ها):
**توضیحات****موقعیت****نوع داده****نام پارمتر**
**شناسه چارتر اصلی که لیست گارانتی‌های آن مورد نیاز است.****`Route/Body`****`integer`****`$request->id`**
--- #### · خروجی (Return):
**توضیحات****نوع داده**
**یک آبجکت `JSON` با کلید `items` (آرایه‌ای از آبجکت‌های گارانتی) و `meta`. هر آبجکت گارانتی شامل اطلاعات اصلی، آبجکت `guarantor`، آرایه `rooms` (در صورت وجود) و آبجکت `capacity` است.****`Illuminate\Http\JsonResponse`**
**در صورت بروز خطا، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.****`Illuminate\Http\JsonResponse`**
--- #### · مثال استفاده / سناریو: **سناریو: مشاهده لیست گارانتی‌های یک چارتر هتل** - **Request:** - `id`: 620 - **Action:** 1. متد تمام رکوردها از `charter_warranties` با `main_id=620` را واکشی می‌کند. 2. برای هر گارانتی (فرضاً شناسه گارانتی `15` و `guarantor` آن `22` است): a. اطلاعات همکار `22` از Redis خوانده می‌شود. b. تمام رکوردها از `charter_warranty_accommodation_rooms` با `warranty_id=15` واکشی می‌شود. c. ظرفیت آیتم‌های مرتبط با این گارانتی محاسبه می‌شود. 3. تمام این اطلاعات در یک آبجکت جامع تجمیع شده و به لیست خروجی اضافه می‌شود. - **Response:** - `HTTP Status`: `200 OK` - `Body`:
json
``` { "items": [ { "id": 15, "main_id": 620, "amount": 50000000, "guarantor": { "id": 22, "title_fa": "آژانس الف", ... }, "rooms": [ { "item_id": 110, "capacity": 5, ... }, { "item_id": 112, "capacity": 3, ... } ], "capacity": { "item_110": { "total": 5, "balance": 2, ... }, "item_112": { "total": 3, "balance": 3, ... } } } ], "meta": { "timestamp": ... } } ```