#P1521
GET /colleague/search
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| GET |
/api/v2/colleague/search |
V2ColleaguesController@searchColleague |
authWithJwt |
جستوجوی سریع همکاران بر اساس نام، کد مالی، یا شناسه |
منطق عملکرد تابع
تابع searchColleague برای اجرای جستوجوی بلادرنگ در دادههای همکار طراحی شده است. این API در تمام نقاط سامانه (حسابداری، تسویه، CRM و billing) برای autocomplete باکسهای انتخاب همکار استفاده میشود.
- دریافت پارامتر
query از Query String.
- درخواست از کش Redis (کلید: colleagues:list:light) در صورت فعال بودن برای پاسخ فوری.
- اگر در کش موجود نباشد:
- یافتن رکوردها در جدول
colleagues با فیلترهای فازی روی فیلدهای office، first_name، last_name و financial_code.
- ترکیب نتایج با جدول
colleague_additional برای تکمیل email/phone.
- محدودسازی خروجی به ۲۰ رکورد برای کارایی.
- بازگرداندن آرایهای از نتایج به فرمت استاندارد id‑title‑meta جهت استفاده در کامپوننتهای انتخاب.
پارامترهای ورودی
| نام |
نوع |
محل |
الزامی |
توضیح |
| query |
string |
query |
بله |
عبارت جستوجو (نام، نامخانوادگی یا شناسه عددی) |
| limit |
integer |
query |
خیر |
حداکثر تعداد نتایج برگرداندهشده (پیشفرض: ۲۰) |
| branch |
string |
query |
خیر |
در صورت ارسال، جستوجو فقط در آن شعبه انجام میشود |
| cache |
boolean |
query |
خیر |
در صورت false، داده به اجبار از DB خوانده میشود |
ساختار خروجی
{
"status": true,
"results": [
{
"id": 142,
"title": "آژانس تابان پرواز",
"meta": {
"type": "Creditor",
"category": "آژانس",
"financial_code": "103245897",
"phone": "+98-31-32110"
}
},
...
],
"cache": true
}
نکات امنیتی
- برای جلوگیری از نشت داده، فقط فیلدهای ضروری برگردانده میشوند.
- در صورت ورود نقش مالی (finance.admin) فیلد کد اقتصادی هم ضمیمه میشود.
- همهٔ نتایج از طریق Middleware
authWithJwt بررسی خواهند شد.
نکات عملکردی
- درصورت فعال بودن cache، پاسخ زیر ۵ ms خواهد بود.
- فهرست فشرده (LightList) در Redis هر ۶۰ دقیقه توسط job
SyncColleaguesLightList بهروزرسانی میشود.
- جستوجوی پایگاه داده با شاخص مرکب روی
office + financial_code انجام میشود.
Dependencies
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Models\Colleague;
- use App\Models\ColleagueAdditional;
- use Illuminate\Http\Request;
کدهای خطا
| کد |
شرح |
منبع |
| 400 |
عبارت جستوجو خالی یا غیرمجاز است |
Validation |
| 401 |
توکن JWT منقضی یا نامعتبر است |
Middleware |
| 429 |
تعداد درخواست بیش از حد مجاز (Rate Limit) |
Throttle |
| 500 |
خطای داخلی SQL یا Redis |
DB/Redis |
پیشنهادهای امنیتی
- اعمال الگوریتم جستوجوی case‑insensitive و safe‑encoding برای جلوگیری از SQL Injection.
- اجرای Rate‑Limit ۵ درخواست در ثانیه برای هر توکن.
- ثبت تمام جستوجوها در
system_logs جهت پایش رفتار کاربران.
پیشنهادهای توسعهای
- افزودن fuzzy‑matching (Persian Similarity) برای خطاهای تایپی رایج.
- پشتیبانی از جستوجوی phonetic (آواشناسی نامها).
- مدیریت cache Scope‑Based برای شرکتهای دارای چند شعبه.
ممیزی و لاگها
- ثبت در
system_logs با event: ColleagueSearch.
- فیلدهای لاگشده:
user_id, query, results_count, cached, timestamp.
- درصورت ۵ بار جستوجوی متوالی بدون نتیجه → هشدار امنیتی.
جمعبندی
تابع searchColleague رابط اصلی جستوجوی سریع همکاران در کل مجموعه است که با تکیه بر Redis و Query بهینه، تجربهی سرعتی و پاسخگویی بلادرنگ را فراهم میکند. این endpoint اساس تمام drop‑down ها و autocomplete های سیستم مدیریت مالی و تجاری است.
