POST /api/v2/colleagues/billing

📘

POST مستند فنی Endpoint: بررسی وضعیت مالی همکار (General Billing V2)

1️⃣ معرفی کلّی و هدف‌گذاری

این Endpoint با متد POST و مسیر /api/v2/colleagues/billing طراحی شده است تا امکان دریافت اطلاعات مالی دقیق و به‌روز همکاران (Colleagues) را فراهم آورد. هدف اصلی، ارائهٔ ماندهٔ خالص اعتباری فعال یک همکار در سال جاری شمسی است. تفاوت اصلی این نسخه (V2) در نحوهٔ شناسایی موجودیت مورد نظر (همکار در مقابل کارمند عادی) از طریق پارامتر ورودی id است.

اگر شناسهٔ ورودی (ID) با پیشوند مشخصی (مانند colleague-) همراه باشد، سیستم آن را به عنوان یک رکورد همکار تجاری در نظر می‌گیرد و محاسبات اعتبار انجام می‌شود. در صورتی که شناسهٔ ورودی صرفاً یک عدد یا یک شناسهٔ کارمند عادی (personnel) باشد، مقادیر مربوط به اعتبار با false بازگردانده می‌شوند، چرا که ساختار مالی این موجودیت‌ها متفاوت است و این Endpoint صرفاً برای همکاران طراحی شده است.

2️⃣ اطلاعات مسیر (Route Information)

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

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

3️⃣۲. ورودی‌ها (Request Body Inputs)

4️⃣۳. منطقخروجی اجراییموفق (DetailedSuccessful LogicResponse Flow- Analysis)HTTP 200)

جریاندر پردازشصورتی برکه اساسنوع تجزیهٔcolleague ورودیباشد idو شکلشناسه می‌گیرد.معتبر این مرحله حیاتی‌ترین بخش برای تعیین مسیر اجرایی است.باشد:

//{
  1."CreditLimit": استخراج12000000,
  Type"CreditBalance": و4500000
ID}
    

مقدار CreditLimit از ورودیفیلد ifcredit_amount (strpos($request->id,مدل ‘-’)) { // مثال: ورودی "colleague-100" $parts = explode('-', $request->id); $type = $parts[0]; // 'colleague' $id = $parts[1]; // '100' } else { // مثال: ورودی "100" (پیش‌فرض همکار در نظرColleague گرفته می‌شود)شود. $typeCreditBalance =تفاوت 'colleague';بین $idCreditLimit =و $request->id; } // 2. تعیین سال شمسی جاری برای محاسبات تراز $currentYear = Jalalian::forge(‘now’)->format(‘%Y’); // مثال: ‘1404’ // 3. پردازش برای همکارانمانده (Colleague)Balance) ifمحاسبه‌شده ($type == ‘colleague’) { $Colleague = Colleague::where('id', $id)->first(); if ($Colleague) { // اجرایتوسط تابع محاسبات مالی پیچیده $billingData = CronController::colleaguesGeneralBilling($id); //است.

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

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

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

۶. 0;موارد //خطا محاسبه(Error مانده خالص اعتباری $creditLimit = $Colleague->credit_amount ?? 0; $creditBalance = $creditLimitCases - $yearlyBalance;HTTP return [ 'CreditLimit' => $creditLimit, 'CreditBalance' => $creditBalance ]; } else { // خطای عدم تطابق شناسه با دیتابیس return [ 'status' => false, 'message' => 'شناسه همکار در دیتابیس یافت نشد.' ]; } } // 4. پردازش برای کارمندان (Personnel) else if ($type == ‘personnel’) { // بازگشت مقادیر ثابت و نامعتبر برای این نوع موجودیت return [ 'CreditLimit' => false, 'CreditBalance' => false ]; } // 5. مدیریت حالت‌های پیش‌بینی نشده (مانند نوع نامشخص) else { return [ 'status' => false, 'message' => 'نوع رکورد نامشخص یا نامعتبر است.' ]; }

فرمول محاسبهٔ تراز اعتباری:

که در آن $\text{Balance}_{\text{CurrentYear}}$ از خروجی تابع colleaguesGeneralBilling استخراج می‌شود.

5️⃣ خروجی‌ها (Response Structures)200)

{

“CreditLimit”: 2500000,

“CreditBalance”: 800000

}

{

“CreditLimit”: false,

“CreditBalance”: false

}

{

“status”: false,

“message”: “شناسهیافتن همکار در دیتابیسجدول یافتColleague

6️⃣۷. وابستگی‌ها و سرویس‌های خارجی

7️⃣ سناریوهایشیوهٔ تست (Integration Testing Examples)Testing)

برایدرخواست اعتبارسنجیباید صحتبه عملکرد،صورت نمونه‌هایJSON زیرو پیشنهادبا می‌شود:Header Content-Type: application/json ارسال شود. مثلاً:

مثال ۱: درخواست موفق برای یک همکار خاص

POST /api/v2/colleagues/billing
Headers:
  {Content-Type: Authorization: Bearer … }application/json
Body:
{
  “id”"id": “colleague-452”"1234"
}
    

مثال

۸. ۲:خلاصه درخواست برای یک کارمند عادیپیاده‌سازی (Personnel)

POST /api/v2/colleagues/billing

Body: { “id”: “personnel-201” }

نتیجه مورد انتظار: {"CreditLimit": false, "CreditBalance": false}

مثال ۳: درخواست با شناسه عددی (پیش‌فرض Colleague)

POST /api/v2/colleagues/billing

Body: { “id”: 452 }

سیستم این را به عنوان colleague-452 تفسیر می‌کند و منطق همکار را اعمال می‌نماید.

8️⃣ ملاحظات امنیتی و استثناهاSummary)

📎 پیوست: ساختار داده‌های ورودی به تابع کمکی

برای درک کامل منطق، لازم است ساختار داده‌ای که توسط تابع CronController::colleaguesGeneralBilling تولید می‌شود، مورد توجه قرار گیرد. این تابع داده‌های تراکنشی راColleague بر اساس IDid و

// ساختار داده مورد انتظار برای IDCreditBalance = 100

{

“100”: {

"1403": {
  "Balance": 500000, // مانده سال قبل (نادیده گرفته می‌شود)
  "Invoices": [...],
  "Payments": [...]
},
"1404": { // سال جاری
  "Balance": 1700000, // این مقدار از CreditLimit کم می‌شود
  "Invoices": [...],
  "Payments": [...]
}
}

}