#P1405
POST /api/v2/trade/item/value_added
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/trade/item/value_added |
V2TradeController@valueAddedItemTrade |
authWithJwt |
ویرایش یا تعریف مقدار «ارزش افزوده» برای آیتمهای فاکتور |
منطق عملکرد
- داده دریافتشده از کلید
value_added بررسی و آماده برای درج در دیتابیس میشود.
- فیلدهای
type_value_added و value_added بر اساس مقدار ورودی بهروزرسانی میشوند.
- در انتهای کار، SystemLog با نوع رویداد ValueAddedReferenceItem در صف
snailJob ثبت میشود.
- در صورت بروز خطا، کد خطای ۵۰۰۳ با Trace کامل بازگردانده میشود.
ورودیها
| نام فیلد |
نوع داده |
ضروری |
توضیح |
| item_id |
int |
بله |
شناسه آیتمی که ارزش افزوده آن باید تغییر کند |
| value_added.type |
string |
بله |
نوع ارزش افزوده (مثل درصد یا مبلغ ثابت) |
| value_added.value |
float|int |
بله |
مقدار ارزش افزوده مطابق نوع تعیینشده |
{
"item_id": 415,
"value_added": {
"type": "percent",
"value": 9
}
}
خروجی
| فیلد |
نوع |
شرح |
| status |
bool |
نتیجه نهایی (true در صورت موفقیت) |
| time |
int |
مهر زمانی Unix |
| code |
int|null |
کد خطا در صورت بروز Exception |
| message |
string|null |
پیغام خطا (در حالت شکست) |
| trace |
array|null |
اطلاعات فنی از مسیر خطا |
{
"status": true,
"time": 1732023601
}
تعامل با دیتابیس
- جدول مورد استفاده:
factor_items
- آپدیت فیلدهای:
type_value_added و value_added
- بهروزرسانی ستون
updated_at با زمان فعلی
اثرات جانبی
- ایجاد رویداد log از طریق
SystemLog::dispatch
- ذخیره در صف snailJob با تأخیر ۱۰ دقیقهای برای پردازش لاگ
کدهای خطا
| کد |
شرح |
| 5003 |
خطای کلی در حین بهروزرسانی مقادیر ارزش افزوده یا عملیات دیتابیس |
امنیت
- دسترسی محدود به کاربران احراز هویتشده با JWT
- داده اپراتور (شناسه، IP، User-Agent) در SystemLog ذخیره میشود
کارایی
- عملیات UPDATE فقط روی یک رکورد انجام میشود (در کمتر از ۱۵ میلیثانیه).
- ثبت لاگ ناهمزمان مانع از توقف جریان پاسخ میشود.
وابستگیها
- use Carbon\\Carbon;
- use Illuminate\\Support\\Facades\\DB;
- use App\\Jobs\\SystemLog;
- use App\\Helpers\\Functions;
پیشنهاد بهبود
- افزودن اعتبارسنجی سمت سرور برای جلوگیری از ورود نوع نامعتبر (مثلاً مقادیر منفی).
- افزودن محاسبهٔ بلادرنگ تأثیر ارزش افزوده در محاسبات Redis.
جمعبندی
این متد یک endpoint سبک و سریع برای ویرایش اعداد «ارزش افزوده» در سطح آیتمهای فاکتور است. طراحی آن audit‑friendly است و با ساختار SystemLog هماهنگ، باعث حفظ تاریخچهی تغییرات مالی هر آیتم میشود.
