# POST /colleagues/update/general-billing

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 96%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td></tr><tr><td dir="ltr">POST</td><td dir="ltr">/api/v2/colleagues/update/general-billing</td><td dir="ltr">V2ColleaguesController@updateGeneralBillingColleagues</td><td dir="ltr">authWithJwt</td><td dir="rtl">بازسازی و به‌روزرسانی صورتحساب کلی (General Billing) همکاران بر اساس آخرین مانده‌ها، اسناد مالی و ترازها.</td></tr></tbody></table>

</div>### منطق عملکرد تابع

تابع **updateGeneralBillingColleagues** داده‌های مالی فعلی هر همکار را از جداول مختلف تجمیع کرده و صورتحساب کلی (General Billing)‌ را به‌روزرسانی می‌کند. هدف آن حفظ یکپارچگی اطلاعات مالی همکاران در سامانه است.

<div id="bkmrk-%D8%AF%D8%B1%DB%8C%D8%A7%D9%81%D8%AA-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1%D9%87%D8%A7%DB%8C-%D9%81%DB%8C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">1. دریافت پارامترهای فیلتر (id خاص یا به‌روزرسانی جمعی)،
2. اجرای محاسبات بدهی/بستانکاری هر همکار از `creditDebit`، `factor`، `pays` و `manual_documents`.
3. تعیین تشخیص وضعیت مالی (Diagnosis): `Creditor`، `Debtor` یا `Neutral`.
4. ذخیره مجموع‌ها در جدول `colleagues` (فیلد balance و diagnosis).
5. به‌روزرسانی مهر زمانی در Redis: `TIMESTAMP = 'TIME:colleagues:general_billing'`
6. بازگرداندن گزارش کلی از همکاران به‌روزشده.

</div>### پارامترهای ورودی

<div id="bkmrk-%D9%86%D8%A7%D9%85-%D9%86%D9%88%D8%B9-%D9%85%D8%AD%D9%84-%D8%A7%D9%84%D8%B2%D8%A7%D9%85%DB%8C-%D8%AA" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 95%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>نام</td><td>نوع</td><td>محل</td><td>الزامی</td><td>توضیح</td></tr><tr><td>json</td><td>string (JSON)</td><td>Body</td><td>بله</td><td>شامل شناسه‌ها و فیلترها (مثل id , from , to)</td></tr><tr><td>branch</td><td>string</td><td>Body</td><td>خیر</td><td>شناسه شعبه جهت تفکیک محاسبات</td></tr><tr><td>ids</td><td>array</td><td>Body</td><td>خیر</td><td>در صورت ارسال، فقط همین همکاران به‌روزرسانی می‌شوند</td></tr></tbody></table>

</div>### ساختار خروجی

```
{
  "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": "شرکت داخلی"
    }
  ]
}
```

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>### نکات امنیتی

<div id="bkmrk-%D8%A7%DB%8C%D9%86-%D9%85%D8%B3%DB%8C%D8%B1-%D9%81%D9%82%D8%B7-%D8%A8%D8%B1%D8%A7%DB%8C-%D8%B3%D8%B7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- این مسیر فقط برای سطح دسترسی `finance.admin` یا `system.automation` مجاز است.
- هر بار اجرای جمعی باید در context مربوط به branch صورت گیرد تا داده‌ها تداخل نکنند.
- دسترسی این endpoint باید از طریق JWT معتبر کنترل شود.

</div>### نکات عملکردی

<div id="bkmrk-%D9%87%D8%B1-%D9%BE%D8%B1%D8%AF%D8%A7%D8%B2%D8%B4-%D8%B4%D8%A7%D9%85%D9%84-%D9%85%D8%AD%D8%A7%D8%B3%D8%A8" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- هر پردازش شامل محاسبات از چند جدول (pays, factors, manual\_documents) است؛ بنابراین اجرای انبوه باید به‌صورت async یا cron انجام شود.
- نتیجه آخرین اجرا در Redis ذخیره می‌شود تا دفعات بعد سریع‌تر قابل بازیابی باشد.
- Batch Size مناسب: 50–100 همکار در هر پردازش.

</div>### وابستگی‌ها

<div id="bkmrk-use-carbon%5Ccarbon%3B-u" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- use Carbon\\Carbon;
- use Illuminate\\Support\\Facades\\DB;
- use Illuminate\\Support\\Facades\\Redis;
- use App\\Models\\Colleague;
- use App\\Http\\Controllers\\Functions;

</div>### کدهای خطا

<div id="bkmrk-%DA%A9%D8%AF-%D8%B4%D8%B1%D8%AD-%D8%AE%D8%B7%D8%A7-%D9%85%D9%86%D8%A8%D8%B9-401-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"><table border="1" cellpadding="6" style="width: 90%; margin: 15px auto; text-align: center; border-collapse: collapse;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>کد</td><td>شرح خطا</td><td>منبع</td></tr><tr><td>401</td><td>عدم احراز هویت JWT</td><td>Middleware</td></tr><tr><td>422</td><td>پارامتر ناقص یا JSON نامعتبر</td><td>Validation</td></tr><tr><td>500</td><td>خطا در اجرای کوئری محاسبات مالی</td><td>DB Transaction</td></tr></tbody></table>

</div>### پیشنهادهای امنیتی

<div id="bkmrk-%D9%85%D8%AD%D8%AF%D9%88%D8%AF%D8%B3%D8%A7%D8%B2%DB%8C-%D8%AF%D8%B3%D8%AA%DB%8C-%D8%A8%D9%87-%D9%86%D9%82" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- محدودسازی دستی به نقش مالی (Finance Role).
- در حالت cron، log کامل user\_id و branch نگهداری شود.
- رمزنگاری refreshDatetime در Redis با الگوریتم SHA256.

</div>### پیشنهادهای توسعه‌ای

<div id="bkmrk-%D8%A7%D9%81%D8%B2%D9%88%D8%AF%D9%86-%D8%A7%D9%85%DA%A9%D8%A7%D9%86-increme" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- افزودن امکان incremental update فقط برای همکاران ویرایش‌شده از آخرین اجرای Redis.
- ایجاد دستور artisan برای اجرای خودکار این مسیر توسط cronjob.
- افزودن فیلد `duration_ms` برای ثبت زمان اجرای واقعی هر batch.

</div>### ممیزی و لاگ‌ها

<div id="bkmrk-%D8%B1%D9%88%DB%8C%D8%AF%D8%A7%D8%AF%3A-generalbilli" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;">- رویداد: `GeneralBillingUpdate`
- ثبت در جدول `system_reports` با نوع فرایند `billing_refresh`.
- فیلدهای ثبت شده: user\_id، تعداد همکاران به‌روزشده، branch، زمان اجرا.

</div>### جمع‌بندی

تابع **updateGeneralBillingColleagues** پایهٔ نگهداری داده‌های مالی کلان سیستم است. عملکرد درست آن موجب یکپارچگی ترازهای داخلی و صحت گزارش‌های مالی می‌شود. اجرای همزمان آن با مسیر `updateFinancialColleagues` توصیه نمی‌شود تا تداخلی در cache و داده‌ها ایجاد نشود.

<div id="bkmrk-update-general-billing-colleagues" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.9;"></div>