Skip to main content
#P1520

GET /colleague/get

Route Info

Method Endpoint Controller Middleware Purpose
GET /api/v2/colleague/get V2ColleaguesController@getColleague authWithJwt دریافت جزئیات کامل یک همکار (colleague) شامل اطلاعات عمومی، مالی و ارتباطی

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

تابع getColleague برای خواندن جزئیات کامل یک همکار از پایگاه داده طراحی شده است. ورودی شامل شناسه همکار می‌باشد که از query string در GET request دریافت می‌شود. در خروجی، داده‌ها از جداول colleagues، colleague_additional و وابستگی‌ها تجمیع می‌شود. چنانچه داده در کش Redis موجود باشد، تابع مستقیماً از آن استفاده می‌کند و در غیر این صورت از Database خوانده، سپس در Redis ذخیره می‌کند.

  1. خواندن پارامتر id از Query string.
  2. بررسی موجود بودن cache (کلید: colleague:{id}) در Redis.
  3. در صورت وجود → بارگذاری داده از cache، در غیر این صورت:
    • دریافت رکورد اصلی از جدول colleagues.
    • پیوستن دادهٔ اضافی از colleague_additional.
    • دریافت روابط از mapping_colleagues (در حوزه شرکت اصلی).
    • تبدیل فیلدهای ساختار‌یافته (dates, phone, category, type) به قالب خروجی استاندارد UI.
  4. ارسال نتیجهٔ نهایی به صورت JSON.

پارامترهای ورودی

نام نوع محل الزامی توضیح
id integer query بله شناسه همکار
branch string query خیر شناسه شعبه برای اعمال محدودیت دامنه
cache boolean query خیر اگر false باشد، کش نادیده گرفته می‌شود و داده از DB بارگذاری می‌شود

ساختار خروجی

{
  "status": true,
  "data": {
    "id": 142,
    "office": "آژانس تابان پرواز",
    "type": 3,
    "category": 4,
    "diagnosis": "Creditor",
    "financial_code": "103245897",
    "credit_amount": 50000000,
    "phone": "+98-31-32110",
    "email": "info@taban.ir",
    "branch": "isfahan",
    "relationship": "official",
    "created_at": "2025-04-21 11:22:53",
    "updated_at": "2025-11-23 14:47:15",
    "additional": {
      "iban": "IR210550080300087123456001",
      "address": "اصفهان، خیابان حکیم نظامی، ساختمان مهر"
    }
  },
  "cache": true
}

نکات امنیتی

  • دسترسی فقط برای کاربران با نقش‌های finance.read یا crm.viewer.
  • داده‌های مالی حساس (financial_code, iban) فقط برای مدیر مالی بازمی‌گردند.
  • کنترل سطح دسترسی اضافی با policy CanViewColleague انجام می‌شود.

نکات عملکردی

  • در حالت cache فعال، زمان پاسخ زیر ۱۰ ms می‌باشد.
  • هر بار cache پس از update در تابع operationColleague با job UpdateRedis به‌روزرسانی می‌شود.
  • کلید کش: colleague:{id} و ساختار ساده JSON ذخیره‌شده.

Dependencies

  • use Illuminate\Support\Facades\DB;
  • use Illuminate\Support\Facades\Redis;
  • use App\Models\Colleague;
  • use App\Models\ColleagueAdditional;
  • use App\Models\MappingColleagues;

کدهای خطا

کد شرح منبع
400 پارامتر id ارسال نشده Validation
401 توکن JWT نامعتبر یا منقضی است Middleware
404 همکار در سیستم یافت نشد DB Query
500 خطای داخلی پایگاه داده یا Redis Exception Handler

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

  • رمزنگاری فیلدهای حساس پیش از ارسال (خصوصاً کد مالی و IBAN).
  • محدود کردن نرخ درخواست (Rate Limit) روی Endpoint برای جلوگیری از enumeration.
  • ثبت لاگ دسترسی کاربران برای هر فراخوانی.

پیشنهادهای توسعه‌ای

  • امکان درخواست چندگانه (Bulk Fetch) بر اساس آرایه شناسه‌ها.
  • افزودن فیلد last_transaction_at جهت نشان دادن آخرین تعامل مالی همکار.
  • پیاده‌سازی response cache expiring بر اساس TTL پویا.

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

  • Event ممیزی: ColleagueFetched
  • فیلدهای لاگ: user_id, colleague_id, ip, user_agent, cached, datetime
  • ثبت گزارش در جدول system_logs با نوع read_colleague

جمع‌بندی

تابع getColleague مرجع اصلی برای ارائهٔ جزئیات کامل هر همکار است و به علت وابستگی به کش Redis سرعت پاسخ بالاست. در فرآیندهای مالی و مدیریتی، این endpoint پایه‌ای برای نمایش اطلاعات همکار در تمامی ماژول‌ها (تجارت، حسابداری، آمار) محسوب می‌شود.

Back to top