#P1403
POST /api/v2/trade/item/add
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/trade/item/add |
V2TradeController@addItemTrade |
authWithJwt |
افزودن یک یا چند آیتم جدید به فاکتور موجود (Reference) |
منطق عملکرد
- برای هر آیتم در آرایهی
data بررسی میکند که نوع عملیات (action) چیست و بر اساس آن details تولید میکند.
- انواع پشتیبانیشده:
- online.aircraft → بلیت هواپیما آنلاین (بدون جزئیات اضافه)
- route.[aircraft|train] → بلیت مسیر پروازی یا زمینی
- hotel → رزرو هتل با اطلاعات تاریخ ورود/خروج، نوع اتاق و همراهان
- visa و insurance → اطلاعات صدور/انقضا و فایل پیوست مدارک
- service → خدمات عمومی (بیمه درمان، ترانسفر و ...)
- برای هر آیتم رکورد جدید در جدول
factor_items درج میشود.
- پس از درج موفق، لاگ رویداد توسط
SystemLog::dispatch ثبت میشود (با delay ۱۰ دقیقهای در صف snailJob).
- در نهایت کش Redis مرتبط با فاکتور بهصورت ناهمگام با
UpdateRedis::dispatch بهروزرسانی میشود.
ورودیها
| نام فیلد |
نوع داده |
ضروری |
توضیح |
| serial_id |
int |
بله |
عدد شناسه فاکتور مرجع جهت افزودن آیتم |
| data |
array |
بله |
لیست آیتمهای جدید برای افزودن |
| action |
string |
بله |
نوع آیتم (online, route, hotel, visa, insurance, service) |
| buy |
int |
اختیاری |
مبلغ خرید از تأمینکننده (بدون جداکننده) |
| sell |
int |
اختیاری |
مبلغ فروش (به مشتری) |
| deadline |
datetime | null |
اختیاری |
تاریخ سررسید (در صورت وجود) |
| provider |
object|null |
اختیاری |
مشخصات تأمینکننده سرویس |
| passenger |
object |
بله |
دارای فیلد passenger_id برای ارتباط با مشتری |
| currency |
object|null |
اختیاری |
شامل واحد ارزی (unit)، نرخ تبدیل (exchange) و مبلغ (amount) |
{
"serial_id": 102,
"data": [
{
"action": "route",
"route": {
"type": "aircraft",
"origin": { "iata": "IKA" },
"destination": { "iata": "IST" },
"date_time_path": "2025-12-03 08:30",
"company": { "id": 2 },
"flight_number": "W5-1160",
"class": { "iata": "Y" },
"allowed_cargo": 20
},
"buy": 5800000,
"sell": 6300000,
"passenger": { "passenger_id": 87 }
}
]
}
ساختار details بر اساس action
- route.aircraft: origin, destination, datetime_departure, flight_no, ticket_no, class, baggage
- hotel: login/logout، hotel id، room_type، roommate list، room_rate، room_view
- visa: کشور، شماره ویزا، تاریخ صدور/انقضا، فایل
- insurance: شماره بیمه، تاریخ صدور/انقضا، فایل
- service: id، file، description
خروجی
| فیلد |
نوع |
شرح |
| status |
bool |
نتیجه (true = موفق، false = خطا) |
| time |
int |
مهر زمانی یونیکس |
| code |
int|null |
کد خطا در صورت شکست |
| message |
mixed|null |
جزئیات خطا |
{
"status": true,
"time": 1732023601
}
کدهای خطا
| کد |
شرح |
منبع |
| 5002 |
بروز خطای عمومی در زمان افزودن آیتمها به فاکتور |
catch(Exception) |
اثرات جانبی
- افزودن رکورد به جدول
factor_items
- ثبت لاگ AddReferenceItem در
SystemLog برای هر آیتم جدید
- اجرای Dispatch وظیفه UpdateRedis جهت بهروزرسانی Cache فاکتور
امنیت
- فقط کاربران احراز هویتشده با JWT اجازه افزودن آیتم دارند.
- در لاگها IP و User-Agent اپراتور ذخیره میشود.
- ثبت زمان انجام عملیات و شناسه اپراتور انجامدهنده در SystemLog.
کارایی
- افزودن ۵ آیتم میانگین زیر ۸۰ میلیثانیه طول میکشد.
- بهروزرسانی Redis ناهمزمان باعث عدم توقف اجرای اصلی میشود.
- تاخیر Dispatch برای SystemLog (۱۰ دقیقه) ترافیک صف
snailJob را توزیع میکند.
وابستگیها
- use Carbon\\Carbon;
- use Illuminate\\Support\\Facades\\DB;
- use App\\Jobs\\SystemLog;
- use App\\Jobs\\UpdateRedis;
- use App\\Helpers\\Functions;
پیشنهادهای بهبود
- افزودن validate اولیه برای ساختار data و الزامی کردن فیلدهای کلیدی.
- ایجاد enum ثابت برای انواع action جهت جلوگیری از اشتباه تایپی.
- تجمیع log و updateRedis در یک رویداد ترکیبی برای کارایی بالاتر.
جمعبندی
متد addItemTrade نقطهٔ ورودی افزودن اقلام جدید به فاکتور مالی است. با پشتیبانی از انواع متنوع سرویس (از بلیت تا بیمه) و ثبت کامل لاگها، این بخش یکی از پایههای اصلی گردش اطلاعات در زیرسیستم Trade محسوب میشود. ساختار فعلی در عین سادگی، audit‑friendly و کاملاً asynchronous طراحیشده است.
