# Function storeCharterReservation ### #### · هدف: این متد به عنوان نقطه ورودی اصلی برای ثبت رزروهای جدید (یک یا چند مسافر) بر روی یک چارتر عمل می‌کند. منطق اصلی آن شامل اعتبارسنجی‌های چند لایه است: ابتدا با استفاده از `ReservationController::capacityItemCharter` ظرفیت خالی چارتر را بررسی می‌کند. سپس برای هر مسافر، اعتبارسنجی داده‌های هویتی (کد ملی، پاسپورت) را با `Validator::checkIdentity` انجام می‌دهد و مسافر را در جدول `passengers` درج یا به‌روزرسانی می‌کند. متد می‌تواند رزروهای عادی (با محاسبه قیمت از `ReservationController::financialCalculation`) و رزروهای اعتباری/گارانتی (که اطلاعات مالی مستقیماً در ورودی ارائه شده) را مدیریت کند. تمام رزروهای موفق در یک آرایه جمع‌آوری شده و در پاسخ نهایی به همراه شناسه‌های رزرو و PNR محلی بازگردانده می‌شوند. در صورت بروز خطا برای هر مسافر، اطلاعات خطا به جای نتیجه موفق در آرایه خروجی قرار می‌گیرد.
**ویژگی‌ها****توضیحات**
**هدف کلی**ثبت یک یا چند رزرو جدید برای یک آیتم چارتر مشخص.
**اعتبارسنجی ظرفیت**بررسی ظرفیت باقیمانده قبل از هرگونه پردازش.
**مدیریت مسافر**اعتبارسنجی و درج/به‌روزرسانی اطلاعات مسافر در جدول `passengers`.
**رزرو گروهی**قابلیت پردازش و ثبت چندین مسافر در یک درخواست.
**مدیریت مالی**پشتیبانی از رزروهای عادی (محاسبه قیمت) و اعتباری (قیمت از پیش تعیین‌شده).
**مدیریت استرداد در فایل**قابلیت ثبت مسافر با وضعیت “استرداد شده” از طریق فایل اکسل (`status == 'refund'`).
**ایجاد PNR**تولید شماره PNR محلی منحصر به فرد برای هر رزرو.
**پاسخ تفصیلی**بازگرداندن آرایه‌ای از نتایج که هر آیتم وضعیت موفقیت یا شکست رزرو یک مسافر را نشان می‌دهد.
--- #### · ورودی‌ها (پارامتر‌ها):
**توضیحات****موقعیت****نوع داده****نام پارمتر**
**شناسه چارتر اصلی.****`Body`****`integer`****`$request->main_id`**
**شناسه آیتم محاسباتی چارتر (کلاس پرواز/اتاق هتل).****`Body`****`integer`****`$request->item_id`**
**آرایه‌ای از آبجکت‌های مسافر برای ثبت.****`Body`****`array`****`$request->passengers`**
**ساختار آبجکت مسافر در آرایه `$request->passengers`:**
- `identity`: `array` - اطلاعات هویتی (کد ملی، پاسپورت، نام، …). - `email`: `string` - ایمیل مسافر. - `mobile`: `string` - شماره موبایل مسافر. - `age_title`: `string` - گروه سنی (`adult`, `child`, `infant`). - `status`: `string` - وضعیت رزرو (مثلاً `definite`, `refund`). - `financial`: `array` (اختیاری) - اگر ارائه شود، رزرو به صورت اعتباری/گارانتی با قیمت‌های مشخص ثبت می‌شود. شامل `supplier`, `sale_price`, `commission`.
--- #### · خروجی (Return):
**توضیحات****نوع داده**
**در صورت موفقیت، یک آبجکت JSON با کلید `items` که آرایه‌ای از نتایج هر رزرو است. هر نتیجه موفق شامل `status: true` و آبجکت `pnr` (حاوی `local`, `original`, `id`) می‌باشد. نتایج ناموفق شامل `status: false` و جزئیات خطا هستند. کد پاسخ `201 Created`.****`Illuminate\Http\JsonResponse`**
**در صورت پر بودن ظرفیت، یک پاسخ با کد `422 Unprocessable Entity` و پیام خطا.****`Illuminate\Http\JsonResponse`**
**در صورت بروز خطای کلی، یک پاسخ با کد `400 Bad Request` و جزئیات استثناء.****`Illuminate\Http\JsonResponse`**
--- #### · مثال استفاده / سناریو: **سناریو: ثبت دو مسافر (یک عادی، یک اعتباری) روی یک پرواز** - **Request Body:**
json
``` { "main_id": 450, "item_id": 980, "passengers": [ { "identity": {...}, "age_title": "adult", "status": "definite" }, { "identity": {...}, "age_title": "adult", "status": "definite", "financial": { "supplier": 22, "sale_price": 1500000, "commission": 50000 } } ] } ``` - **Action:** 1. ظرفیت آیتم 980 از چارتر 450 بررسی می‌شود. فرضاً ظرفیت کافی است. 2. **مسافر اول:** اطلاعات هویتی اعتبارسنجی می‌شود. `financialCalculation` برای محاسبه قیمت فراخوانی می‌شود. رزرو در جدول مربوطه درج می‌شود. 3. **مسافر دوم:** اطلاعات هویتی اعتبارسنجی می‌شود. چون `financial` وجود دارد، قیمت‌ها مستقیماً از ورودی خوانده شده و رزرو به عنوان اعتباری ثبت می‌شود. 4. برای هر دو رزرو موفق، PNR محلی تولید می‌شود. - **Response:** - `HTTP Status`: `201 Created` - `Body`:
json
``` { "items": [ { "status": true, "pnr": { "local": "CH-101", "original": "...", "id": 11234 } }, { "status": true, "pnr": { "local": "CH-102", "original": "...", "id": 11235 } } ], "meta": { "timestamp": ... } } ```