#P1402
POST /api/v2/trade/item/edit
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/trade/item/edit |
V2TradeController@editItemTrade |
authWithJwt |
ویرایش آیتم خاص در فاکتور (فاکتوری آنلاین یا آفلاین) براساس نوع خدمت |
منطق عملکرد
- متد امکان ویرایش جزئیات هر آیتم فاکتور را بسته به نوع
action (online, route, hotel, visa, service, ...) فراهم میکند.
- اگر فیلد
created وجود نداشته باشد، نوع و جزئیات آیتم تشخیص داده و فیلد details ساخته میشود.
- بر اساس
edit_all مشخص میکند که آیا باید تمام آیتمهای مشابه فاکتور بهروزرسانی شوند یا فقط آیتم موردنظر.
- در صورت وجود
created، قبل از تغییر تاریخ، بسته بودن دوره مالی بررسی میشود (بر اساس تنظیم END_OF_FINANCIAL_PERIOD_CLOSING_ACCOUNTS).
- تمام تغییرات به کمک
SystemLog::dispatch ثبتشده و کش Redis مربوط به آیتم حذف میشود.
- در صورت ویرایش همه آیتمها، تمام کلیدهای cache مربوطه
reference_item:*:information:title:fa پاک میشوند.
ورودیها
| نام فیلد |
نوع داده |
ضروری |
توضیح |
| item_id |
int |
بله |
شناسه آیتم فاکتور جهت ویرایش |
| action |
string |
بله |
نوع آیتم (online, route, visa, hotel, service, ...) |
| edit_all |
bool |
خیر |
در صورت true، تمام آیتمهای مشابه در فاکتور ویرایش میشوند |
| provider |
object | null |
خیر |
تامینکننده خدمت |
| buy |
int |
خیر |
مبلغ خرید (قیمت پایه از تأمینکننده) |
| sell |
int |
خیر |
مبلغ فروش نهایی |
| failure_bill |
bool |
خیر |
پرچم مشخصکننده وجود فاکتور معیوب |
| created |
YYYYMM |
خیر |
برای تغییر تاریخ ایجاد آیتم فاکتور (در حالت ویژه) |
| passenger |
object |
خیر |
اطلاعات مسافر، شامل شناسه و تاریخ تولد (در بلیتها) |
| currency |
object |
خیر |
واحد ارزی، ضریب تبدیل، و مبلغ تبدیلشده |
| online|route|hotel|visa|insurance|service |
object |
در حالت خاص |
جزئیات آیتم بر حسب نوع خدمت |
{
"item_id": 205,
"action": "online",
"edit_all": false,
"online": { "type": "aircraft", "flight_number": "W5-1155", "original_ticket_no": "774221", "date_time_path": "2025-11-21 13:20" },
"buy": 8800000,
"sell": 9400000,
"currency": { "unit": "IRR", "exchange": 1, "amount": 9400000 },
"provider": { "id": 2 }
}
ساختار <details> بر اساس action
- online.aircraft: شامل datetime، flight_number، original_ticket_no
- route.aircraft: شامل origin, destination, datetime_departure, flight_no, ticket_no, baggage و غیره
- hotel: شامل login, logout, room_type, room_rate, roommate, transfer, ...
- online.train: شامل service, passenger.age_title, origin، destination، datetime و اطلاعات مالی
- online.accommodation: شامل accommodation id، rate، check_in/out، room_type، roommate
- visa / insurance / service: شامل اطلاعات پایه، تاریخ صدور/انقضا و فایل پیوست
خروجی
| فیلد |
نوع |
شرح |
| status |
bool |
نتیجه نهایی عملیات |
| time |
int |
مهر زمانی سیستم |
| code |
int|null |
کد خطا در صورت وجود |
| message |
string|null |
توضیح خطا |
{
"status": true,
"time": 1732022461
}
کدهای خطا
| کد |
شرح |
منبع |
| 5002 |
آیتم فاکتور یافت نشد |
در صورت نبود item_id معتبر |
| 5003 |
خطا در اجرای تراکنش/پایگاه داده |
catch(Exception) |
| 5007 |
تلاش برای ویرایش تاریخ در دوره مالی بستهشده |
ولیدیشن تاریخی |
اثرات جانبی
- در صورت ویرایش موفق، Cache Redis برای آیتم مربوطه حذف میشود.
- در صورت
edit_all = true، کش تمام آیتمهای factor نیز حذف میگردد.
- SystemLog شامل لاگ کامل تغییرات (data diff) و اطلاعات اپراتور ثبت میشود.
امنیت
- احراز از طریق JWT الزامی است (
authWithJwt).
- تغییر تاریخ تنها در صورت بسته نبودن دوره مالی ممکن است.
- دسترسی فقط برای اپراتورهای معتبر مجاز است.
کارایی
- عملیات کاملاً DB transaction-safe نیست اما atomic روی سطر واحد اجرا میشود.
- dispatch لاگ با delay در صف
snailJob انجام میشود تا latency پاسخ کاهش یابد.
- در حالت
edit_all، بروزرسانی گروهی ممکن است تا 0.3s افزایش زمان پاسخ داشته باشد.
وابستگیها
- use Carbon\\Carbon;
- use Morilog\\Jalali\\Jalalian;
- use Illuminate\\Support\\Facades\\DB;
- use Illuminate\\Support\\Facades\\Redis;
- use App\\Helpers\\Functions;
- use App\\Jobs\\SystemLog;
پیشنهادهای بهبود
- استانداردسازی ساختار
details برای همه actionها در قالب Schema واحد.
- افزودن محدودکننده validation برای واحدهای پولی و نرخ تبدیل.
- بررسی امکان atomic transaction کامل هنگام ویرایش گروهی.
جمعبندی
متد editItemTrade نقطهی کنترل جزئیات دقیق فاکتور است؛ برای هر نوع خدمت (از بلیت هواپیما تا ویزا و بیمه) جزئیات را بازسازی و در پایگاه داده بهروزرسانی میکند. از نظر معماری با editTrade تفاوت دارد چون روی آیتم واحد تمرکز دارد و لاگینگ دقیق row-level را اعمال میکند. این ترکیب بین دقت، سرعت و قابلیت audit تعادل مطلوبی ایجاد کرده است.
