#P1517
POST /colleagues/update/financial
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/colleagues/update/financial |
V2ColleaguesController@updateFinancialColleagues |
authWithJwt |
بهروزرسانی وضعیت مالی همکاران (بدهکار، بستانکار، مانده فعلی، سقف اعتباری) بر اساس اطلاعات تراکنشها و فاکتورها. |
منطق عملکرد تابع
تابع updateFinancialColleagues زمانی فراخوانی میشود که نیاز باشد اطلاعات مالی تمام یا بخشی از همکاران (Colleagues) بر اساس آخرین تراکنشها محاسبه مجدد شود. منطق کلی آن:
- خواندن اطلاعات درخواستی از کلاینت (درخواست عمومی یا برای همکار خاص).
- دریافت آخرین ماندهٔ مالی از جداول
pays، factors، و manual_documents.
- محاسبهٔ خالص بدهی (Debit) و بستانکاری (Credit) برای هر همکار.
- تعیین
Diagnosis هر همکار (Debtor, Creditor, Neutral).
- بهروزرسانی فیلدهای مالی در جدول
colleagues و ثبت زمان آخرین آپدیت در Redis Cache تحت کلید TIME:colleagues:general_billing.
- برگشت خروجی شامل وضعیت کلی هر همکار پس از بهروزرسانی.
پارامترهای ورودی
| نام |
نوع |
محل |
الزامی |
توضیح |
| json |
string (JSON) |
Body |
بله |
شامل پارامترهای فیلتر (from, to, id و ...) |
| category |
integer |
Body |
خیر |
دستهبندی همکار برای محدودسازی (مثلاً ۸: شرکت مسافربری) |
| update_type |
string |
Body |
خیر |
نوع بهروزرسانی: partial یا full. پیشفرض: full |
| branch |
string |
Body |
خیر |
شناسه شعبه برای محدودسازی محاسبه. |
ساختار خروجی
{
"status": true,
"updated": 46,
"refreshDatetime": "2025-11-23 13:30:06",
"data": [
{
"colleague_id": 72,
"name": "آژانس یاقوت شرق",
"category": "شرکت داخلی",
"credit": 9140000,
"debit": 6400000,
"balance": 2740000,
"diagnosis": "Creditor",
"financial_ceiling": 20000000
}
]
}
نکات امنیتی
- فقط مدیران مالی یا کاربران دارای نقش
finance.admin امکان فراخوانی دارند.
- بهروزرسانی کلان روی همهٔ همکاران در ساعت کاری توصیه نمیشود.
- کلید Redis هر اجرا باید با شناسه شعبه (branch) جدا شود تا تداخل در داده جلوگیری شود.
نکات عملکردی
- تابع از Batch Update برای کاهش تعداد Queryها استفاده میکند.
- Cache زمان آخرین محاسبه در Redis ذخیره میشود:
Redis::set('TIME:colleagues:general_billing', Carbon::now()->toString());
- بهطور میانگین از ۱۰۰ رکورد در هر بار اجرا پشتیبانی میکند (بهینه برای cron job).
وابستگیها
- use Carbon\Carbon;
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Http\Controllers\Functions;
- use App\Models\Colleague;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 401 |
توکن JWT نامعتبر |
authWithJwt |
| 422 |
پارامتر نامعتبر در json |
Validation |
| 500 |
خطای داخلی پایگاه داده هنگام تجمیع داده |
DB::Transaction |
پیشنهادهای امنیتی
- محدودسازی Endpoint برای نقشهای Finance.
- ثبت لاگ تمام تغییرات مالی بزرگتر از ۱۰۰ میلیون تومان.
- رمزنگاری کلید Redis با الگوریتم
HMAC_SHA256.
پیشنهادهای توسعهای
- ایجاد امکان Delta Update برای فقط همکاران تغییر یافته.
- افزودن فیلد
refresh_by در Redis برای ثبت شناسهٔ کاربر اجراکننده.
- ساخت گزارش خودکار پس از آپدیت برای مانیتورینگ.
ممیزی و لاگها
- نام رویداد:
UpdateFinancialColleagues
- لاگشده در جدول
system_reports با نوع "financial_refresh"
- شامل: user_id، branch، بازه زمانی، تعداد همکاران بهروزرسانیشده.
جمعبندی
تابع updateFinancialColleagues بازوی مرکزی حفظ یکپارچگی مالی همکاران است. با ادغام آن با تریگرهای تراکنش و کش Redis، سیستم مالی همکاران همیشه بهروزرسانیشده و همزمان باقی میماند. استفاده مکرر از این مسیر باید با کنترل بار سرور و هماهنگی حسابداری انجام شود.
