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

Behavior Summary

  • شناسایی هوشمند نوع محصول (Route vs Accommodation)
  • مدیریت خودکار مسیر برگشت (Round Trip Logic)
  • تولید انبوه تاریخ‌ها بر اساس الگوی تکرار (Repeat Pattern)
  • استفاده از DB::transaction برای هر تاریخ تولید شده
  • درج همزمان جداول وابسته (Items, Financials, Rules, Taxes)

Payload Schema (Root Parameters)

Field Type Required Description
type string yes نوع محصول:
route | accommodation
subtype string conditional فقط برای route:
aircraft | train | bus
items array yes آرایه‌ای از مشخصات فیزیکی (جزئیات پرواز یا هتل)
repeat object no تنظیمات موتور تولید تاریخ (بسیار مهم)
calculations array yes قوانین مالی، قیمت‌گذاری، کلاس نرخی و ویژگی‌ها
rules object no قوانین استرداد (refund) و قوانین عمومی

Logic 1: Initialization & Resolution

سیستم ابتدا نوع داده را تشخیص می‌دهد و داده‌های خام را به شناسه‌های دیتابیس تبدیل می‌کند:

// Route (Aircraft)
Origin/Dest IDs -> Lookup 'airports' table -> Get City ID

// Route (Train/Bus)
Origin/Dest IDs -> Used directly as City ID

// Accommodation
Hotel ID -> Lookup 'hotels' table -> Get City ID
Start/End Time -> Set to 00:00:00 and 23:59:59

Logic 2: Round Trip Handling

اگر در `items` پارامتر outbound وجود داشته باشد:

  • یک آبجکت جدید برای مسیر برگشت ساخته می‌شود.
  • مبدا و مقصد جابجا (Swap) می‌شوند.
  • اختلاف روز (Diff) بین رفت و برگشت محاسبه می‌شود تا در تولید انبوه تاریخ‌ها لحاظ گردد.

Logic 3: Date Replication Engine

بر اساس آبجکت repeat، متغیر $charterDates پر می‌شود:

Mode: Dates

"type": "dates",
"dates": ["2025-10-01", "2025-10-05"]
// تکرار دقیق روی همین تاریخ‌ها

Mode: Weekly

"type": "weekly",
"days": [1, 3, 5], // شنبه، دوشنبه، چهارشنبه
"from": "...", "to": "..."
// چک کردن روز هفته با Jalalian::getDayOfWeek()

Mode: Periodic

"type": "periodic",
"repeat_day": 3, // هر 3 روز یکبار
"from": "...", "to": "..."

Logic 4: The Transaction Loop

برای هر تاریخ تولید شده، مراحل زیر در یک DB::transaction اجرا می‌شود:

  • Charters Table: درج هدر اصلی، تولید سریال نامبر، تنظیم پرمیشن‌ها.
  • Notifications: درج در `scheduled_notifications` (اگر `schedule` ارسال شده باشد).
  • Items: درج در `charter_items` (انکود کردن جزئیات پرواز/هتل).

Logic 5: Financial & Calculations

پیچیده‌ترین بخش که جداول مالی را پر می‌کند. داده‌ها در {type}_calculation ذخیره می‌شوند.

// Loop through request->calculations

if (type == 'route') {
   // Insert Base Pricing (Adult/Child/Infant)
   // Insert Taxes, Baggage, Features (is_round_trip)
}

if (type == 'accommodation') {
   // Insert Room Rates, Capacity, Facilities
   // Handle 'mapping_roomtypes' logic
}

Financial Handling Table:

شامل سه نوع داده است که با فیلد type تفکیک می‌شوند:

  • Markup (افزایش نرخ)
  • Commission (کمیسیون)
  • Citizenship (قوانین ملیت)

Logic 6: Rules Insertion

// Refund Rules
تبدیل زمان به "دقیقه" و درج در charter_refund_rules

// Public Rules
درج توضیحات عمومی در charter_public_rules

Response Structure

در صورت موفقیت:

{
  "status": true,
  "time": 1733221456
}

در صورت خطا (Exception Caught):

{
  "status": false,
  "time": 1733221456,
  "message": "SQL Error...",
  "trace": [...]
}

Flowchart

Start Request
↓
Check Type (Route/Hotel)
↓
Resolve IDs & Round Trip Logic
↓
Generate Date List (Repeat Engine)
↓
Loop Through Dates
↓
Begin DB Transaction
↓
Insert Charter & Items
↓
Insert Financials (Calc/Tax/Comms)
↓
Insert Rules (Refund/Public)
↓
Commit Transaction
↓
Return Success
Back to top