#P1382

POST /api/v2/colleagues/billing

بخش	توضیحات
آدرس مسیر	POST /api/v2/colleagues/billing
کنترلر / تابع	ColleaguesController → general_billingV2(Request $request)
میان‌افزارها (Middlewares)	domainAccess ، ipTrust

۱. تحلیل عملکرد

این Route برای بازیابی اطلاعات صورتحساب عمومی همکار (Colleague Billing) در نسخه دوم API طراحی شده است. تابع ابتدا شناسه ورودی در فیلد id را بررسی می‌کند تا نوع موجودیت را تشخیص دهد (colleague یا personnel) و با توجه به آن مانده اعتباری سال جاری را محاسبه و برمی‌گرداند.

۲. ورودی‌ها (Inputs)

فیلد	نوع داده	اجباری	توضیح
id	string	بله	شناسهٔ همکار یا پرسنل. اگر شامل کاراکتر `-` باشد، نوع personnel تشخیص داده می‌شود، در غیر اینصورت colleague.

۳. خروجی موفق (Successful Response - HTTP 200)

در صورتی که نوع colleague باشد و شناسه معتبر باشد:

{
  "CreditLimit": 12000000,
  "CreditBalance": 4500000
}

مقدار CreditLimit از فیلد credit_amount مدل Colleague گرفته می‌شود. CreditBalance تفاوت بین CreditLimit و مانده (Balance) محاسبه‌شده توسط تابع CronController::colleaguesGeneralBilling($id) است.

۴. خروجی برای پرسنل (personnel)

{
  "CreditLimit": false,
  "CreditBalance": false
}

۵. وابستگی‌ها (Dependencies)

App\Http\Controllers\Api\CronController::colleaguesGeneralBilling($id)
App\Models\Colleague
Morilog\Jalali\Jalalian برای محاسبه سال جاری شمسی

۶. موارد خطا (Error Cases - HTTP 200)

شرط	خروجی JSON
عدم یافتن همکار در جدول Colleague	{ "message": "اطلاعات شرکت بدرستی ارسال نشده است." }

۷. شیوهٔ تست (Testing)

درخواست باید به صورت JSON و با Header Content-Type: application/json ارسال شود. مثلاً:

POST /api/v2/colleagues/billing
Headers:
  Content-Type: application/json
Body:
{
  "id": "1234"
}

۸. خلاصه پیاده‌سازی (Implementation Summary)

دریافت $request->id
تشخیص نوع بر اساس وجود -
محاسبه سال جاری شمسی با Jalalian::forge('now')
اگر colleague:
- واکشی مدل Colleague بر اساس id
- فراخوانی تابع colleaguesGeneralBilling()
- محاسبه CreditBalance = CreditLimit - Balance
اگر personnel → خروجی ثابت false/false