#P1408

POST /api/v2/trade/refund/update

Route Info

Method	Endpoint	Controller	Middleware	Purpose
POST	/api/v2/trade/refund/~~delete~~update	~~V2TradeController@deleteRefundTrade~~V2TradeController@updateRefundTrade	authWithJwt	~~حذف~~به‌روزرسانی یا ایجاد آیتم بازپرداخت از(refund) برای یک فاکتور ~~و پاک‌سازی کش مرتبط~~

منطق عملکرد

بابه‌ازای ~~دریافت~~هر آیتم موجود در $request['data'] بررسی می‌کند که آیا تاریخ استرداد (extradition_date) مقدار دارد یا خیر.

در صورت وجود، ساختار details شامل item_id و یادداشت (note) ساخته می‌شود.

اگر refund_id ازمقدار ~~درخواست،~~داشته ~~رکورد~~باشد ~~مرتبط~~→ باآیتم ~~محصول~~استرداد refundموجود ~~را از~~در جدول factor_items ~~حذف~~به‌روزرسانی می‌~~کند.~~شود.
~~پیش~~در ازغیر ~~حذف،~~این ~~داده‌ی~~صورت ~~قبلی~~→ آیتم جدیدی با DB::first()product='refund' ~~واکشی~~ثبت ومی‌گردد ~~جهت~~(ایجاد ~~ذخیره~~بازپرداخت ~~لاگ~~تازه).

~~نگهداری~~

در هر دو حالت، رویداد SystemLog در صف snailJob با تأخیر ۱۰ دقیقه برای ثبت عملیات ایجاد یا بروزرسانی dispatch می‌شود.
پس از ~~حذف،~~پایان SystemLog ~~با نوع~~ DeleteRefundItem ~~در صف~~ snailJob ~~ثبت می‌شود.~~

~~در نهایت، عملیات~~حلقه، UpdateRedis برای بازسازی کشRedis ~~مالی~~Cache و(financial, ~~اطلاعات فاکتور~~information) اجرا ~~می‌شود.~~

~~در صورت بروز استثناء، خروجی همراه با~~ code=5005 ~~و جزئیات Trace بازگردانده~~ می‌شود.

پارامترهای ورودی

نام	نوع	ضروری	توضیح
serial_id	integer	بله	شناسه فاکتور مرجع ~~جهت بروزرسانی کش Redis~~(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.

{
  "status": false,
  "time": 1732019472,
  "code": 5005,
  "message": "...",
  "trace": [...]
}

امنیت

ملزم به احراز هویت JWT ~~الزامی~~(کاربر ~~است.~~معتبر سیستم).
~~عملیات با نقش~~شناسه اپراتور ~~اجرا~~عامل از $request->get('operator') استخراج می‌شود.

صرفاً در شعبه مجاز و درمحدوده ~~SystemLog~~فاکتور ~~ثبت~~مجاز ~~می‌شود.~~قابل دسترسی است.

اثرات جانبی و Queue Jobs

SystemLog::dispatch() با نوع DeleteRefundItemAddRefund یا UpdateRefund → صف snailJob (تأخیر ۱۰ دقیقه).
UpdateRedis::dispatch() ~~برای~~جهت ~~بروزرسانی~~بازسازی کش مالی → صف fastJob.

تغییرات داده‌ای

DB Table: factor_items
~~Action:~~Fields ~~DELETE~~updated/inserted: ~~where~~details, ~~id=[refund_id]~~supplier_id, ~~and~~buy, ~~product='refund'~~sale, deadline

JSON Structure: {"item_id": ##, "note": "cause text"}

مدیریت خطا

~~محصور~~عدم شکست try/catch داخلی؛ خطاهای غیرقابل پیش‌بینی در try/catchسطح →DB ~~بازگرداندن~~به ~~ساختار~~Exception ~~JSON~~عمومی ~~استاندارد~~منجر ~~خطا.~~می‌شوند.
خطای ورود ناقص code 5005data ~~برای~~باعث ~~خطای~~صرف‌نظر ~~کلی~~از ~~حذف.~~آیتم‌های ناکامل می‌شود.

کارایی

~~عملیات~~حلقه ساده ~~خواندن~~بر وروی ~~حذف~~داده‌ها، ~~single-row.~~زمان اجرا متناسب با اندازه data[] است.
~~میانگین~~متوسط زمان پاسخ با ۵ آیتم ≈ ~~90ms.~~۱۸۰ms.

ردپای حسابرسی (Audit Trail)

تمام عملیات‌ها در جدول SystemLog ذخیره ~~داده~~و ~~قبل~~قابل ازرهگیری ~~حذف جهت شفافیت.~~هستند.
~~ردیابی~~مقادیر: ~~اپراتور،~~IP، IPUser-Agent، شناسه اپراتور و ~~User-Agent.~~مهر زمان.

پیشنهاد بهبود

افزودن ~~امکان~~try/catch به ازای هر آیتم جهت تفکیک خطاهای تک‌ورودی.

اعتبارسنجی داخلی برای مقادیر penalty_*.

پشتیبانی از حذف ~~گروهی~~جمعی ~~refundها~~استردادها ~~جهت~~در ~~بهبود~~یک ~~کارایی.~~

درخواست

~~ارسال کد وضعیت HTTP 400 به جای ساختار 5005 برای خطای منطقی.~~واحد.

جمع‌بندی

این Endpoint ~~ابزار~~برای ~~دقیق~~ایجاد ~~حذف~~یا ~~بازپرداخت‌هاست~~اصلاح سریع ردیف‌های استرداد طراحی شده و بامستقیماً داده‌های جدول factor_items را تغییر می‌دهد. ویژگی متمایز آن تقسیم عملیات به دو سطح «افزودن» و «به‌روزرسانی» خودکار و ثبت ~~دقیق وقایع~~خودکار در ~~SystemLog،~~SystemLog کنترل حسابرسی کامل را تضمین می‌کند. طراحی ساده و واکنش‌گرا آن امکان اتصال مستقیم به UI درون‌سازمانی را فراهم می‌سازد.است.