#P1418
POST /api/v2/pledger/store
Route Info
| Method | Endpoint | Controller | Middleware | Purpose |
| POST | /api/v2/pledger/store | V2TradeController@storePledger | authWithJwt | افزودن رکورد جدید تعهدکننده به جدول pledgers |
منطق عملکرد
- مقدار عددی واردشده در فیلد
amountبررسی میشود؛ اگر صفر یا تهی باشد خطای ۵۰۰۴ بازگردانده میشود. - رشتهی
pledgerبهصورت «نوع–شناسه» دریافت و با تابعexplode()تفکیک میگردد (مثلاًcolleague-47). - در صورت معتبر بودن مبلغ، رکورد جدید در جدول
pledgersدرج میشود:type← همان نوع تعهدکننده (colleague/operator/...)serial_id← شناسهی طرف مقابلfactor← شناسهی فاکتور (از فیلدserial_idدرخواست)amount← مبلغ تصفیهشده از ویرگول
- پس از درج، شناسهی رکورد برگردانده میشود.
پارامترهای ورودی
| نام | نوع | ضروری | توضیح |
| pledger | string | بله | ترکیب نوع و شناسهی تعهدکننده (مثل colleague-47) |
| serial_id | integer | بله | شناسهی فاکتور اصلی |
| amount | string / integer | بله | مبلغ تعهد (با یا بدون جداکننده ویرگول) |
{
"pledger": "colleague-47",
"serial_id": 10234,
"amount": "12,000,000"
}
ساختار خروجی
موفق:
{
"status": true,
"time": 1732026400,
"data": 582 // شناسهی رکورد در جدول pledgers
}
ناموفق (مبلغ صفر):
{
"status": false,
"code": 5004,
"message": "تعهد باید دارای مبلغ باشد"
}
امنیت
- احراز هویت JWT از طریق Middleware
authWithJwt. - کاربر باید اپراتور ثبتکننده فاکتور باشد (تشخیص از فیلد
$request->get('operator')).
وابستگیها
- DB: table
pledgers - Carbon (timestamps)
- SystemLog Queue (type=StorePledger)
- UpdateRedis Job
کارایی
عملیات درج تکمرحلهای، میانگین تأخیر <25ms. ادغام با صف رخدادهای لاگ و Redis غیرهمزمان.
مدیریت خطا
- کد خطا 5004 برای مبلغ نامعتبر.
- سایر خطاهای SQL یا اتصال توسط Laravel ExceptionHandler گرفته میشود.
اثرات جانبی
- ارسال job
SystemLog::dispatch(type=StorePledger)با تأخیر ۱۰ دقیقه روی صفsnailJob. - بهروزرسانی سریع Redis با کلیدهای
financial،information،pledgersاز طریق صفfastJob.
ردپای حسابرسی
ورود در SystemLog با اطلاعات عامل (IP, agent, operator_id) برای شفافیت کامل تراکنش ثبت تعهد.
پیشنهاد بهبود
- اعتبارسنجی سمت سرور برای نوع pledger مجاز (colleague, operator,…).
- برگشت کل رکورد ایجادشده بجای فقط id (برای رابطهای مدیریتی).
جمعبندی
این متد افزودن پایهای تعهدکننده برای هر فاکتور است و مسیر ورود رسمی دادهی مالی تعهد در چرخهی Trade محسوب میشود.