# Function storeCharter ### #### · هدف: این تابع، موتور اصلی و بسیار پیچیده‌ی **ایجاد چارترهای جدید** در سیستم است که به عنوان یک نقطه پایانی واحد، قابلیت تعریف انواع مختلف چارتر با پیکربندی‌های گوناگون را فراهم می‌کند. هدف اصلی آن، دریافت یک ساختار داده‌ی پیچیده از کلاینت، پردازش آن بر اساس نوع چارتر (`route` یا `accommodation`) و منطق تکرار (`repeat`)، و در نهایت ثبت مجموعه‌ای از رکوردها در پایگاه داده به صورت **اتمی و یکپارچه** است. این تابع تمام عملیات‌های خود را درون یک `DB::transaction` قرار می‌دهد تا اطمینان حاصل شود که یا تمام مراحل (شامل ایجاد چارتر اصلی، کلاس‌های قیمتی، مالیات‌ها و دوره‌های تکرار) با موفقیت انجام می‌شوند، یا در صورت بروز کوچکترین خطا، تمام تغییرات به حالت اولیه بازمی‌گردند (`rollback`). این رویکرد، از ایجاد داده‌های ناقص یا متناقض در دیتابیس جلوگیری می‌کند. این متد همچنین مسئولیت آماده‌سازی داده‌های پیچیده‌ای مانند مسیرهای رفت و برگشت (`inbound/outbound`) و تولید تاریخ‌های تکرار بر اساس الگوهای مختلف (`dates`, `weekly`, `periodic`) را بر عهده دارد و در نهایت، خلاصه‌ای از شناسه‌های ایجاد شده را به عنوان خروجی بازمی‌گرداند.
**ویژگی‌ها****توضیحات**
**هدف کلی**ایجاد یک یا چند چارتر بر اساس تنظیمات ورودی، شامل نوع، جزئیات مسیر/اقامتگاه و الگوی تکرار.
**عملیات اتمی (Atomic)**استفاده از `DB::transaction` برای تضمین یکپارچگی داده‌ها؛ تمام عملیات یا با هم موفق می‌شوند یا با هم لغو می‌گردند.
**پشتیبانی از انواع چارتر**مدیریت منطق متفاوت برای چارترهای `route` (پرواز، قطار، اتوبوس) و `accommodation` (هتل).
**موتور تکرار (Repeat Engine)**قابلیت ایجاد چارترها بر اساس یک الگوی تکرار: لیست تاریخ‌های مشخص (`dates`)، روزهای هفتگی (`weekly`) یا دوره‌های زمانی متناوب (`periodic`).
**ساختار داده پیچیده**پردازش ساختارهای تو در تو برای جزئیات مسیر، کلاس‌های قیمتی (`calculations`)، مالیات‌ها (`taxes`) و اطلاعات مالی (`financial`).
**پاک‌سازی کش**پس از ایجاد موفقیت‌آمیز، کلیدهای مرتبط در Redis را حذف می‌کند تا اطمینان حاصل شود که داده‌های جدید در پاسخ‌های بعدی لحاظ می‌شوند.
--- #### · ورودی‌ها (پارامتر‌ها):
**توضیحات****نوع داده****نام پارمتر**
**آبجکت اصلی درخواست حاوی تمام داده‌های لازم برای ایجاد چارتر.****`Illuminate\Http\Request`****`$request`**
**کلید اصلی. نوع چارتر را مشخص می‌کند. مقادیر معتبر: `'route'` یا `'accommodation'`.****`string`****`$request->type`**
**(برای `type: 'route'`) نوع وسیله نقلیه را مشخص می‌کند: `'aircraft'`, `'train'`, `'bus'`.****`string`****`$request->subtype`**
**آرایه‌ای حاوی جزئیات اصلی چارتر، مانند مبدأ، مقصد، تاریخ و اطلاعات وسیله نقلیه.****`array`****`$request->items`**
**مهم. آرایه‌ای از آبجکت‌ها که کلاس‌های مختلف قیمتی و ظرفیتی چارتر را تعریف می‌کنند.****`array`****`$request->calculations`**
**(اختیاری) آبجکتی که منطق تکرار چارتر را مشخص می‌کند. شامل `type` (مانند `'weekly'`) و جزئیات مربوطه.****`object`****`$request->repeat`**
**(برای `type: 'accommodation'`) شامل `start` و `end` برای محدوده تاریخ اقامت.****`object`****`$request->date_range`**
**سایر فیلدها مانند `capacity`, `description`, `permissions` و غیره.**`...`**`...`**
--- #### · خروجی (Return):
**توضیحات****نوع داده**
**یک پاسخ JSON که در صورت موفقیت، حاوی یک آرایه با کلیدهای `main`، `calculations`، `taxes` و `financial` است. این کلیدها به ترتیب شناسه‌های ایجاد شده برای چارتر اصلی، کلاس‌های قیمتی، مالیات‌ها و اطلاعات مالی را در خود جای داده‌اند. در صورت بروز خطا، یک پاسخ با کد وضعیت `500` و پیام خطا برگردانده می‌شود.****`Illuminate\Http\JsonResponse`**
--- #### · مثال استفاده: ```php // سناریو: ایجاد یک چارتر پرواز هفتگی برای روزهای شنبه و دوشنبه // POST /api/panel/v2/charter/store // Body (JSON): { "type": "route", "subtype": "aircraft", "capacity": 180, "description": "چارتر هفتگی تهران-مشهد", "permissions": { /* ... */ }, "repeat": { "type": "weekly", "from": "1404/08/01", "to": "1404/08/30", "days": [6, 1] // شنبه و دوشنبه }, "items": [ { "details": { "origin": { "id": 1, "name": "THR" }, "destination": { "id": 2, "name": "MHD" }, "datetime": "1404/08/04 10:30", // تاریخ یکی از روزهای الگو (یک‌شنبه) "vehicle": { /* ... */ } } } ], "calculations": [ { "name": "اکونومی", "capacity": 150, "financial": { /* ... */ } }, { "name": "بیزنس", "capacity": 30, "financial": { /* ... */ } } ] } // خروجی مورد انتظار (در صورت موفقیت): { "main": [101, 102, 103, ...], // شناسه‌های چارترهای اصلی ایجاد شده برای هر تاریخ "calculations": [201, 202, 203, ...], // شناسه‌های کلاس‌های قیمتی "taxes": [301, 302, ...], // شناسه‌های مالیات‌ها "financial": [401, 402, ...] // شناسه‌های اطلاعات مالی } ```