POST /api/v2/colleagues/billing

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

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

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

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

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

توجه: اعمال Middleware های امنیتی domainAccess و ipTrust نشان‌دهندهٔ حساسیت دسترسی به این اطلاعات مالی است و تنها IPهای لیست سفید و دامنه‌های مجاز مجاز به فراخوانی هستند.

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

4️⃣ منطق اجرایی (Detailed Logic Flow Analysis)

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

// 1. استخراج Type و ID از ورودی

if (strpos($request->id, ‘-’)) {

// مثال: ورودی "colleague-100"
$parts = explode('-', $request->id);
$type = $parts[0]; // 'colleague'
$id = $parts[1];   // '100'
} else {

// مثال: ورودی "100" (پیش‌فرض همکار در نظر گرفته می‌شود)
$type = 'colleague';
$id = $request->id;
}

// 2. تعیین سال شمسی جاری برای محاسبات تراز

$currentYear = Jalalian::forge(‘now’)->format(‘%Y’); // مثال: ‘1404’

// 3. پردازش برای همکاران (Colleague)

if ($type == ‘colleague’) {

$Colleague = Colleague::where('id', $id)->first();

if ($Colleague) {
    // اجرای تابع محاسبات مالی پیچیده
    $billingData = CronController::colleaguesGeneralBilling($id);
    
    // محاسبه ماندهٔ تراکنش‌های سال جاری
    $yearlyBalance = $billingData[$id][$currentYear]['Balance'] ?? 0;
    
    // محاسبه مانده خالص اعتباری
    $creditLimit = $Colleague->credit_amount ?? 0;
    $creditBalance = $creditLimit - $yearlyBalance;

    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)

{

“CreditLimit”: 2500000,

“CreditBalance”: 800000

}

{

“CreditLimit”: false,

“CreditBalance”: false

}

{

“status”: false,

“message”: “شناسه همکار در دیتابیس یافت نشد.”

}

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

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

برای اعتبارسنجی صحت عملکرد، نمونه‌های زیر پیشنهاد می‌شود:

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

POST /api/v2/colleagues/billing

Headers: { Authorization: Bearer … }

Body: { “id”: “colleague-452” }

مثال ۲: درخواست برای یک کارمند عادی (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️⃣ ملاحظات امنیتی و استثناها

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

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

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

{

“100”: {

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

}

محاسبه نهایی بر اساس فیلد Balance موجود در آرایهٔ مربوط به سال جاری شمسی (1404 در این مثال) انجام می‌شود.