#P1401
POST /api/v2/trade/edit
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/trade/edit |
V2TradeController@editTrade |
authWithJwt |
ویرایش جزئیات فاکتور یا ادغام رفرنسهای مالی |
منطق عملکرد
- ورودی
action تعیینکننده نوع عملیات است؛ شامل پنج حالت متمایز:
- financial_description: ویرایش توضیحات مالی فاکتور (فیلد
financial_desc) و ثبت لاگ.
- details: بروزرسانی فیلدهای عمومی شامل
description، print، income، leader و status + پاکسازی Cache Redis مربوطه.
- merge: ادغام دو رفرنس مالی. بررسی مطابقت
operator هر دو رفرنس و جابجایی factor_items از یکی به دیگری.
- created: ویرایش تاریخ ایجاد رفرنس. اگر تاریخ بعد از بستهشدن حسابهای مالی باشد، عملیات رد میشود با کد 5007.
- announcement: ویرایش گروهی وضعیت (
status) یا چاپ (print) برای چند رفرنس.
تمام تغییرات با dispatch به SystemLog در صف snailJob ثبت میشوند.
در صورت نیاز، کشهای Redis با کلیدهای مرتبط با آن فاکتور حذف یا بهروزرسانی میگردند.
تمام مسیرها در بلوک try/catch محصورند؛ خطاهای سیستم با کد 5005 بازگردانده میشوند.
ورودیها
| نام فیلد |
نوع داده |
ضروری |
توضیح |
| action |
string |
بله |
نوع عملیات (financial_description, details, merge, created, announcement) |
| serial_id |
int |
بله |
شناسه رفرنس موردنظر برای ویرایش |
| financial_description |
string |
در حالت financial_description |
متن توضیحات مالی جدید |
| description |
string |
در حالت details |
توضیح یا شرح فاکتور |
| income |
int |
در حالت details |
شناسه درآمد مربوط |
| leader |
int |
در حالت details |
شناسه مشتری اصلی فاکتور |
| reference_merge |
string |
در حالت merge |
فرمت "idA-idB" برای ادغام دو فاکتور |
| created |
datetime |
در حالت created |
تاریخ جدید ایجاد رفرنس |
| serial_ids |
array |
در حالت announcement |
لیست شناسههای فاکتورها برای ویرایش گروهی |
{
"action": "details",
"serial_id": 245,
"description": "اصلاح اطلاعات مشتری",
"income": 7,
"leader": 28,
"status": 2,
"operator_reference": 5
}
خروجی
| فیلد |
نوع |
شرح |
| status |
bool |
نتیجه عملیات (true/false) |
| time |
int |
زمان سیستم هنگام پاسخ |
| code |
int|null |
کد خطا در حالت ناموفق |
| message |
string|null |
پیغام خطا یا توضیح |
{
"status": true,
"time": 1732022018
}
امنیت
- همه درخواستها از طریق authWithJwt احراز هویت میشوند.
- عدم توانایی تغییر تاریخ رفرنسهای بستهشده (بند عملکرد مالی بستهشده).
- ردیابی هر تغییر توسط SystemLog با IP و عامل سیستم.
- صفبندی برای جلوگیری از تراکم همزمانی در نوشتن لاگها و Redis.
کارایی
- با حذف مستقیم Cache Redis، اطلاعات بهروز بلافاصله در Dashboard در دسترساند.
- تغییرات سبک هستند و کمتر از ۵۰ms اجرا دارند مگر حالت merge.
- افزودن asynchronous job در بروزرسانی Redis باعث کاهش زمان پاسخ اولیه شده است.
وابستگیها
- use Carbon\\Carbon;
- use Illuminate\\Support\\Facades\\DB;
- use Illuminate\\Support\\Facades\\Redis;
- use App\\Helpers\\Functions;
- use App\\Jobs\\SystemLog;
- use App\\Jobs\\UpdateRedis;
- use Morilog\\Jalali\\Jalalian;
کدهای خطا
| کد |
شرح |
منبع |
| 5004 |
تلاش برای ادغام فاکتورها با اپراتور متفاوت |
action=merge |
| 5005 |
خطا در روند ویرایش یا تراکنش پایگاه داده |
catch(Exception) |
| 5007 |
تلاش برای تغییر تاریخ در بازه بسته مالی |
action=created |
پیشنهادهای بهبود
- ولیدیشن مرکزی برای مقدار
action پیش از ورود به منطق اصلی.
- تجمیع dispatchهای SystemLog برای کاهش حجم صف.
- گزارشگیری بصری تغییرات Redis برای مانیتورینگ دقیقتر cache hit/miss.
جمعبندی
متد editTrade واحد ویرایشی انعطافپذیر سیستم است که چند نوع تغییر مختلف را زیر یک endpoint سامان میدهد. با ساختار فعلی تمام ویرایشها در عین سرعت، قابل ردیابی و audit کامل هستند. ترکیب Redis و SystemLog باعث توازن ایدهآل بین كارایی و امنیت شده است.
