Skip to main content
#P1664

POST /v2/charter

Charter: Create Inventory (Store)

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

Request Overview

URL: /v2/charter
Method: POST
Controller: CharterController@storeCharter
Middleware: authWithJwt

Key Features & Behavior

  • Poly-morphic Creation: پشتیبانی همزمان از پرواز (Route) و هتل (Accommodation) با یک ساختار واحد.
  • Auto-Inversion: تولید خودکار مسیر برگشت (Outbound) با جابجایی مبدا/مقصد و محاسبه اختلاف روز.
  • Smart Replication: تولید انبوه رکوردها بر اساس روزهای هفته (شمسی) یا بازه‌های زمانی.
  • Financial Complexity: مدیریت پلکانی قیمت‌ها، مارک‌آپ (Markup)، کمیسیون و قوانین ملیت.
  • Data Integrity: استفاده از تراکنش دیتابیس برای هر تاریخ (Fail-safe per date).

Payload Schema (Root Level)

Field Type Required Description
type string Yes نوع موجودی:
route | accommodation
subtype string Cond. برای route الزامی است:
aircraft | train | bus
branch integer Yes شناسه شعبه ایجاد کننده
items array Yes اطلاعات فیزیکی (شماره پرواز، ترمینال، هتل) و مسیر برگشت
repeat object No تنظیمات موتور تولید تاریخ (اگر نرسد، فقط یک رکورد ثبت می‌شود)
calculations array Yes آرایه‌ای از کلاس‌های نرخی، قیمت پایه، مالیات و قوانین مالی
rules object No قوانین استرداد (Refund) و قوانین عمومی (Public Rules)

Logic 1: Route & 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

Logic 2: Outbound Handling (Round Trip)

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

  • مسیر برگشت به عنوان یک موجودیت جداگانه اما وابسته (Linked) ساخته می‌شود.
  • جای origin و destination تعویض (Swap) می‌شود.
  • پارامتر diff محاسبه می‌شود: فاصله زمانی بین رفت و برگشت (برای استفاده در تولید تاریخ‌های بعدی).

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": "..."
}

Logic 4: Financial Calculations

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

Table Description
charter_taxes مالیات‌ها به تفکیک بزرگسال، کودک و نوزاد.
charter_financial_handling مدیریت سه نوع داده: Markup, Commission, Citizenship rules.
charter_accommodation_rooms (فقط هتل) نگاشت شماره اتاق‌ها و طبقات به کلاس نرخی.
mapping_accommodations (فقط هتل) اتصال شناسه هتل لوکال به شناسه چارتر تولید شده (Airplus ID).

Execution Flowchart

Start Request
↓
Resolve Cities & Objects
↓
Replication Engine
Generate List of Dates
↓
Main Loop (Foreach Date)
↓
Begin Transaction
↓
Insert 'Charters' (Header)
↓
Insert 'Scheduled Notifications'
↓
Insert 'Charter Items'
↓
Financial Loop
Calc / Tax / Markup / Rooms
↓
Insert Rules (Refund/Public)
↓
Commit Transaction
↓
Return Success Response

Response Example

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

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