# POST /v2/charter

# Charter: Create Inventory (Store)

این اندپوینت قلب تپنده سیستم تعریف موجودی (Inventory) است. وظیفه آن دریافت یک الگوی زمانی و قیمتی، و تبدیل آن به صدها رکورد فیزیکی در دیتابیس است. این متد از یک **Replication Engine** داخلی استفاده می‌کند تا تاریخ‌های پرواز یا رزرو هتل را بر اساس الگوهای هفتگی، دوره‌ای یا تاریخ‌های خاص تولید کرده و تمام وابستگی‌های مالی و قانونی را در قالب **تراکنش‌های اتمیک** ذخیره کند.

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

<div class="api-docs" id="bkmrk-url%3A-%2Fv2%2Fcharter-met"><div class="endpoint-info"><div>**URL:** `/v2/charter`</div><div>**Method:** <span class="method-post">POST</span></div><div>**Controller:** CharterController@storeCharter</div><div>**Middleware:** authWithJwt</div></div></div>## Key Features &amp; Behavior

<div class="api-docs" id="bkmrk-poly-morphic-creatio">- **Poly-morphic Creation:** پشتیبانی همزمان از پرواز (Route) و هتل (Accommodation) با یک ساختار واحد.
- **Auto-Inversion:** تولید خودکار مسیر برگشت (Outbound) با جابجایی مبدا/مقصد و محاسبه اختلاف روز.
- **Smart Replication:** تولید انبوه رکوردها بر اساس روزهای هفته (شمسی) یا بازه‌های زمانی.
- **Financial Complexity:** مدیریت پلکانی قیمت‌ها، مارک‌آپ (Markup)، کمیسیون و قوانین ملیت.
- **Data Integrity:** استفاده از تراکنش دیتابیس برای هر تاریخ (Fail-safe per date).

</div>## Payload Schema (Root Level)

<div class="api-docs" id="bkmrk-field-type-required-"><table class="schema-table"><thead><tr><th>Field</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td>type</td><td>string</td><td>Yes</td><td>نوع موجودی: <div class="code-inline">route | accommodation</div></td></tr><tr><td>subtype</td><td>string</td><td>Cond.</td><td>برای route الزامی است: <div class="code-inline">aircraft | train | bus</div></td></tr><tr><td>branch</td><td>integer</td><td>Yes</td><td>شناسه شعبه ایجاد کننده</td></tr><tr><td>items</td><td>array</td><td>Yes</td><td>اطلاعات فیزیکی (شماره پرواز، ترمینال، هتل) و مسیر برگشت</td></tr><tr><td>repeat</td><td>object</td><td>No</td><td>تنظیمات موتور تولید تاریخ (اگر نرسد، فقط یک رکورد ثبت می‌شود)</td></tr><tr><td>calculations</td><td>array</td><td>Yes</td><td>آرایه‌ای از کلاس‌های نرخی، قیمت پایه، مالیات و قوانین مالی</td></tr><tr><td>rules</td><td>object</td><td>No</td><td>قوانین استرداد (Refund) و قوانین عمومی (Public Rules)</td></tr></tbody></table>

</div>## Logic 1: Route &amp; Object Resolution

سیستم ابتدا داده‌های ورودی را نرمال‌سازی می‌کند:

```
IF type == 'route':
   IF subtype == 'aircraft':
       Origin/Dest IDs -> Look up 'airports' table -> Fetch City Name
   ELSE (train/bus):
       Origin/Dest IDs -> Used directly as City Name

IF type == 'accommodation':
   Object -> Hotel ID -> Look up 'hotels' table -> Fetch City Name
   Origin = Destination = City Name
   Start/End Time -> Set strictly to 00:00:00 / 23:59:59
  
```

<div class="api-docs" id="bkmrk--1"></div>## Logic 2: Outbound Handling (Round Trip)

اگر در اولین آیتم آرایه `items`، کلید `outbound` وجود داشته باشد:

<div class="api-docs" id="bkmrk-%D9%85%D8%B3%DB%8C%D8%B1-%D8%A8%D8%B1%DA%AF%D8%B4%D8%AA-%D8%A8%D9%87-%D8%B9%D9%86%D9%88%D8%A7%D9%86-">- مسیر برگشت به عنوان یک موجودیت جداگانه اما وابسته (Linked) ساخته می‌شود.
- جای `origin` و `destination` تعویض (Swap) می‌شود.
- پارامتر `diff` محاسبه می‌شود: فاصله زمانی بین رفت و برگشت (برای استفاده در تولید تاریخ‌های بعدی).

</div>## Logic 3: The Replication Engine

متغیر کلیدی `$charterDates` بر اساس آبجکت `repeat` پر می‌شود. این بخش هوشمند سیستم است:

### Type: Dates (Manual)

```
{ "type": "dates", "dates": ["2024-01-01", "2024-01-05"] }
// دقیقاً برای همین تاریخ‌ها رکورد تولید می‌شود.
  
```

### Type: Weekly (Pattern)

```
{
  "type": "weekly",
  "days": [1, 3, 5], // 1=شنبه, 3=دوشنبه ...
  "from": "2024-01-01",
  "to": "2024-03-01"
}
// حلقه روی بازه زمانی می‌چرخد و روزهای هفته شمسی را چک می‌کند.
  
```

### Type: Periodic (Interval)

```
{
  "type": "periodic",
  "repeat_day": 2, // یک روز در میان
  "from": "...", "to": "..."
}
  
```

<div class="api-docs" id="bkmrk--2"></div>## Logic 4: Financial Calculations

داده‌های مالی در جداول جداگانه بر اساس `type` ذخیره می‌شوند. همچنین جداول واسط زیر پر می‌شوند:

<div class="api-docs" id="bkmrk-table-description-ch"><table class="schema-table"><thead><tr><th>Table</th><th>Description</th></tr></thead><tbody><tr><td>charter\_taxes</td><td>مالیات‌ها به تفکیک بزرگسال، کودک و نوزاد.</td></tr><tr><td>charter\_financial\_handling</td><td>مدیریت سه نوع داده: **Markup**, **Commission**, **Citizenship** rules.</td></tr><tr><td>charter\_accommodation\_rooms</td><td>(فقط هتل) نگاشت شماره اتاق‌ها و طبقات به کلاس نرخی.</td></tr><tr><td>mapping\_accommodations</td><td>(فقط هتل) اتصال شناسه هتل لوکال به شناسه چارتر تولید شده (Airplus ID).</td></tr></tbody></table>

</div>## Execution Flowchart

<div class="api-docs" id="bkmrk-start-request-%E2%86%93-reso"><div class="flowchart"><div class="flow-item">Start Request</div><div class="flow-arrow">↓</div><div class="flow-item">Resolve Cities &amp; Objects</div><div class="flow-arrow">↓</div><div class="flow-item">**Replication Engine**  
<small>Generate List of Dates</small></div><div class="flow-arrow">↓</div><div class="flow-item">**Main Loop (Foreach Date)**</div><div class="flow-arrow">↓</div><div class="flow-item" style="border-style: dashed; border-color: #4caf50;">Begin Transaction</div><div class="flow-arrow">↓</div><div class="flow-item">Insert 'Charters' (Header)</div><div class="flow-arrow">↓</div><div class="flow-item">Insert 'Scheduled Notifications'</div><div class="flow-arrow">↓</div><div class="flow-item">Insert 'Charter Items'</div><div class="flow-arrow">↓</div><div class="flow-item">**Financial Loop**  
<small>Calc / Tax / Markup / Rooms</small></div><div class="flow-arrow">↓</div><div class="flow-item">Insert Rules (Refund/Public)</div><div class="flow-arrow">↓</div><div class="flow-item" style="border-style: dashed; border-color: #4caf50;">Commit Transaction</div><div class="flow-arrow">↓</div><div class="flow-item">Return Success Response</div></div></div>## Response Example

```
// Success
{
    "status": true,
    "time": 1715432100
}

// Error (Exception handled)
{
    "status": false,
    "time": 1715432105,
    "message": "SQL Error: Column 'x' not found...",
    "trace": [...]
}
  
```