Skip to main content
#P1514

POST /colleagues/list

Route Info

Method Endpoint Controller Middleware Purpose
POST /api/v2/colleagues/list V2ColleaguesController@colleaguesList authWithJwt بازیابی فهرست همکاران (Colleagues) بر اساس شرایط فیلتر و عملیات موردنظر (بستانکاران، بدهکاران، تسویه و ...).

منطق عملکرد تابع

تابع colleaguesList وظیفه دارد لیست همکاران را بر اساس نوع عمل درخواستی (debtors، creditors، rounded و ...) برگرداند. در ابتدا دادهٔ JSON ارسالی از سمت کلاینت تجزیه می‌شود و پارامترهای شروع (start) و طول (length) برای صفحه‌بندی تعیین می‌گردد. سپس بر اساس نوع عمل ($request->action) جهت مرتب‌سازی مشخص می‌شود (ASC یا DESC).

در ادامه با ترکیب داده‌های دریافتی و وضعیت بدهی/بستانکاری از طریق متدهای محاسباتی، مجموعه‌ای از آیتم‌ها با ساختاری شامل اطلاعات شناسنامه‌ای، وضعیت مالی، سقف اعتباری، و وضعیت تشخیص حساب (neutral/debtor/creditor) تشکیل می‌شود.

ورودی‌ها

نام پارامتر نوع منبع الزامی توضیح
json string (JSON) Body بله پارامتر صفحه‌بندی و فیلترها شامل start, length, advanced.
action string Body بله نوع عملیات: debtors، creditors، یا rounded برای مرتب‌سازی.
operator string Body خیر شناسه کاربری یا نقش عامل.

خروجی (Response)

{
  "draw": 1,
  "recordsTotal": 162,
  "recordsFiltered": 162,
  "data": [
    {
      "serial_id": 8212,
      "system_serial": 12,
      "title": "دفتر آژانس مهر و ماه",
      "type": "شریک تجاری (بستانکاران)",
      "relationship": "ندارد",
      "category": "شرکت داخلی",
      "credit": 2400000,
      "debit": 600000,
      "balance": 1800000,
      "financial_ceiling": 25000000,
      "diagnosis": {"fa":"بستانکار","en":"Creditor"},
      "status": {"fa":"فعال","en":"active"},
      "documents": ...,
      "representative": ...
    }
  ],
  "refreshDatetime": "1404-09-23 14:30:00"
}

نکات امنیتی

  • این مسیر تحت پوشش middleware authWithJwt اجرا می‌شود و هویت کاربر الزامی است.
  • اطلاعات مالی براساس شعبه و سطح دسترسی کاربر فیلتر می‌شود.
  • در صورت وجود cache Redis، زمان آخرین به‌روزرسانی از کلید TIME:colleagues:general_billing خوانده می‌شود.

نکات عملکردی

  • پشتیبانی از صفحه‌بندی پویا با start و length.
  • استفاده از ترتیب صعودی یا نزولی به‌صورت پویا بر اساس action.
  • زمان پاسخ‌دهی با Redis Cache معمولاً زیر ۱۲۰ms است.

وابستگی‌ها

  • use Illuminate\Support\Facades\Redis;
  • use Morilog\Jalali\Jalalian;
  • use Carbon\Carbon;
  • use App\Http\Controllers\Functions;

کدهای خطا

کد شرح خطا منبع
401 توکن JWT نامعتبر یا منقضی شده است. authWithJwt
422 ساختار دادهٔ ارسالی اشتباه است. JSON Parse Request
500 خطا در پردازش داده‌ها از Redis یا پایگاه داده. DB/Routing

پیشنهادهای امنیتی

  • اعمال سطح دسترسی تفکیک‌شده (Role Restriction) برای مشاهده بستانکاران یا بدهکاران.
  • حذف فیلدهای حساس داخلی مانند شماره حساب‌ها از خروجی.

پیشنهادهای بهبود

  • افزودن پارامتر sort_field برای مرتب‌سازی بر اساس فیلد دلخواه.
  • ایجاد کش سطح شبکه برای بارگذاری سریع‌تر مقادیر ثابت (Category، Type).
  • پشتیبانی از فیلترهای ترکیبی چند شرطی در advanced.

ممیزی و لاگ‌ها

  • نوع لاگ: ColleaguesList.
  • جزئیات ثبت‌شده: user_id، زمان درخواست، action، pagination.
  • سطح حساسیت: Medium Audit.

جمع‌بندی

مسیر POST /colleagues/list نقطه ورود به سیستم مالی همکاران است و نقش کلیدی در تحلیل وضعیت اعتباری آنها دارد. کد این بخش ساختاری منعطف با پشتیبانی از صفحه‌بندی، فیلترگذاری و تشخیص خودکار نوع حساب مالی دارد. افزودن caching پیشرفته و Role-based access می‌تواند راندمان و امنیت را دوچندان کند.

Back to top