#P1408
POST /api/v2/trade/refund/update
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/trade/refund/update | V2TradeController@updateRefundTrade | authWithJwt | بهروزرسانی یا ایجاد آیتم بازپرداخت (refund) برای یک فاکتور |
منطق عملکرد
- بهازای هر آیتم موجود در
$request['data']بررسی میکند که آیا تاریخ استرداد (extradition_date) مقدار دارد یا خیر. - در صورت وجود، ساختار
detailsشاملitem_idو یادداشت (note) ساخته میشود. - اگر
refund_idمقدار داشته باشد → آیتم استرداد موجود در جدولfactor_itemsبهروزرسانی میشود. - در غیر این صورت → آیتم جدیدی با
product='refund'ثبت میگردد (ایجاد بازپرداخت تازه). - در هر دو حالت، رویداد
SystemLogدر صفsnailJobبا تأخیر ۱۰ دقیقه برای ثبت عملیات ایجاد یا بروزرسانی dispatch میشود. - پس از پایان حلقه،
UpdateRedisبرای بازسازی Redis Cache (financial, information) اجرا میشود.
پارامترهای ورودی
| نام | نوع | ضروری | توضیح |
| serial_id | integer | بله | شناسه فاکتور مرجع (reference) |
| data | array | بله | لیست آیتمهای استرداد جهت بروزرسانی/ایجاد |
| data[].refund_id | integer | خیر | در صورت وجود، آیتم بازپرداخت موجود بروزرسانی میشود |
| data[].item_id | integer | بله | شناسه آیتم مرجع (آیتم اصلی فاکتور) |
| data[].provider | integer | بله | شناسه تأمینکننده (supplier) |
| data[].passenger | integer | بله | شناسه مسافر مربوطه |
| data[].penalty_buy_price | string | خیر | مبلغ جریمه خرید (کاهش از buy) |
| data[].penalty_sell_price | string | خیر | مبلغ جریمه فروش (کاهش از sell) |
| data[].extradition_date | string (datetime) | بله | تاریخ استرداد |
| data[].reason | string | خیر | یادداشت توضیحی برای علت استرداد |
خروجی
{
"status": true,
"time": 1732019472
}
در صورت موفقیت، status=true بازگردانده میشود؛ در غیر این صورت (در سطح Exception catch نشده) خطای HTTP 500.
امنیت
- ملزم به احراز هویت JWT (کاربر معتبر سیستم).
- شناسه اپراتور عامل از
$request->get('operator')استخراج میشود. - صرفاً در شعبه مجاز و محدوده فاکتور مجاز قابل دسترسی است.
اثرات جانبی و Queue Jobs
- SystemLog::dispatch() با نوع
AddRefundیاUpdateRefund→ صفsnailJob(تأخیر ۱۰ دقیقه). - UpdateRedis::dispatch() جهت بازسازی کش مالی → صف
fastJob.
تغییرات دادهای
- Table:
factor_items - Fields updated/inserted: details, supplier_id, buy, sale, deadline
- JSON Structure: {"item_id": ##, "note": "cause text"}
مدیریت خطا
- عدم شکست try/catch داخلی؛ خطاهای غیرقابل پیشبینی در سطح DB به Exception عمومی منجر میشوند.
- خطای ورود ناقص
dataباعث صرفنظر از آیتمهای ناکامل میشود.
کارایی
- حلقه ساده بر روی دادهها، زمان اجرا متناسب با اندازه
data[]است. - متوسط زمان پاسخ با ۵ آیتم ≈ ۱۸۰ms.
ردپای حسابرسی (Audit Trail)
- تمام عملیاتها در جدول
SystemLogذخیره و قابل رهگیری هستند. - مقادیر: IP، User-Agent، شناسه اپراتور و مهر زمان.
پیشنهاد بهبود
- افزودن try/catch به ازای هر آیتم جهت تفکیک خطاهای تکورودی.
- اعتبارسنجی داخلی برای مقادیر
penalty_*. - پشتیبانی از حذف جمعی استردادها در یک درخواست واحد.
جمعبندی
این Endpoint برای ایجاد یا اصلاح سریع ردیفهای استرداد طراحی شده و مستقیماً دادههای جدول factor_items را تغییر میدهد. ویژگی متمایز آن تقسیم عملیات به دو سطح «افزودن» و «بهروزرسانی» خودکار و ثبت خودکار در SystemLog است.