#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~~ ~~باشد و شناسه معتبر باشد:~~(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

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