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 و داده‌ها ایجاد نشود.