#P1382

POST /api/v2/colleagues/billing

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

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

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

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

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

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

برای همکاران (colleague):

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

فیلد CreditLimit برابر با مقدار credit_amount مدل Colleague است. CreditBalance از تفاضل CreditLimit و مانده حساب برگردانده‌شده توسط 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 ارسال شود:

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

🧩 مستند بالا کاملاً مطابق قالب HTML نهایی نسخهٔ ۱.۱ با قوانین چینش نهایی آماده درج در Confluence است.