#P1518
POST /colleagues/update/general-billing
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/colleagues/update/general-billing |
V2ColleaguesController@updateGeneralBillingColleagues |
authWithJwt |
بازسازی و بهروزرسانی صورتحساب کلی (General Billing) همکاران بر اساس آخرین ماندهها، اسناد مالی و ترازها. |
منطق عملکرد تابع
تابع updateGeneralBillingColleagues دادههای مالی فعلی هر همکار را از جداول مختلف تجمیع کرده و صورتحساب کلی (General Billing) را بهروزرسانی میکند. هدف آن حفظ یکپارچگی اطلاعات مالی همکاران در سامانه است.
- دریافت پارامترهای فیلتر (id خاص یا بهروزرسانی جمعی)،
- اجرای محاسبات بدهی/بستانکاری هر همکار از
creditDebit، factor، pays و manual_documents.
- تعیین تشخیص وضعیت مالی (Diagnosis):
Creditor، Debtor یا Neutral.
- ذخیره مجموعها در جدول
colleagues (فیلد balance و diagnosis).
- بهروزرسانی مهر زمانی در Redis:
TIMESTAMP = 'TIME:colleagues:general_billing'
- بازگرداندن گزارش کلی از همکاران بهروزشده.
پارامترهای ورودی
| نام |
نوع |
محل |
الزامی |
توضیح |
| json |
string (JSON) |
Body |
بله |
شامل شناسهها و فیلترها (مثل id , from , to) |
| branch |
string |
Body |
خیر |
شناسه شعبه جهت تفکیک محاسبات |
| ids |
array |
Body |
خیر |
در صورت ارسال، فقط همین همکاران بهروزرسانی میشوند |
ساختار خروجی
{
"status": true,
"updated": 31,
"refreshDatetime": "2025-11-23 14:00:21",
"data": [
{
"colleague_id": 14,
"name": "شرکت سپهر پرواز",
"credit": 7800000,
"debit": 1040000,
"balance": 6760000,
"diagnosis": "Creditor",
"financial_ceiling": 30000000,
"category": "شرکت داخلی"
}
]
}
نکات امنیتی
- این مسیر فقط برای سطح دسترسی
finance.admin یا system.automation مجاز است.
- هر بار اجرای جمعی باید در context مربوط به branch صورت گیرد تا دادهها تداخل نکنند.
- دسترسی این endpoint باید از طریق JWT معتبر کنترل شود.
نکات عملکردی
- هر پردازش شامل محاسبات از چند جدول (pays, factors, manual_documents) است؛ بنابراین اجرای انبوه باید بهصورت async یا cron انجام شود.
- نتیجه آخرین اجرا در Redis ذخیره میشود تا دفعات بعد سریعتر قابل بازیابی باشد.
- Batch Size مناسب: 50–100 همکار در هر پردازش.
وابستگیها
- use Carbon\Carbon;
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Models\Colleague;
- use App\Http\Controllers\Functions;
کدهای خطا
| کد |
شرح خطا |
منبع |
| 401 |
عدم احراز هویت JWT |
Middleware |
| 422 |
پارامتر ناقص یا JSON نامعتبر |
Validation |
| 500 |
خطا در اجرای کوئری محاسبات مالی |
DB Transaction |
پیشنهادهای امنیتی
- محدودسازی دستی به نقش مالی (Finance Role).
- در حالت cron، log کامل user_id و branch نگهداری شود.
- رمزنگاری refreshDatetime در Redis با الگوریتم SHA256.
پیشنهادهای توسعهای
- افزودن امکان incremental update فقط برای همکاران ویرایششده از آخرین اجرای Redis.
- ایجاد دستور artisan برای اجرای خودکار این مسیر توسط cronjob.
- افزودن فیلد
duration_ms برای ثبت زمان اجرای واقعی هر batch.
ممیزی و لاگها
- رویداد:
GeneralBillingUpdate
- ثبت در جدول
system_reports با نوع فرایند billing_refresh.
- فیلدهای ثبت شده: user_id، تعداد همکاران بهروزشده، branch، زمان اجرا.
جمعبندی
تابع updateGeneralBillingColleagues پایهٔ نگهداری دادههای مالی کلان سیستم است. عملکرد درست آن موجب یکپارچگی ترازهای داخلی و صحت گزارشهای مالی میشود. اجرای همزمان آن با مسیر updateFinancialColleagues توصیه نمیشود تا تداخلی در cache و دادهها ایجاد نشود.
