#P1522
GET /colleague/user
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| GET |
/api/v2/colleague/user |
V2ColleaguesController@indexColleagueUser |
authWithJwt |
نمایش فهرست کاربران تعریفشده برای یک همکار مشخص |
منطق عملکرد تابع
تابع indexColleagueUser تمام کاربران ثبتشده تحت یک colleague (یا شرکت/شعبه شریک) را بازیابی میکند. هر کاربر به واسطهٔ شناسهٔ همکار و نوع نقش داخلی در جدول colleague_users نگهداری میشود. تابع از جدول colleague_users و جدول users برای تجمیع اطلاعات استفاده میکند.
- دریافت شناسهٔ همکار از Query String (
colleague_id).
- خواندن رکوردهای فعال از جدول
colleague_users.
- اتصال با جدول کاربران برای دریافت نام، ایمیل، وضعیت و نقش.
- بازگرداندن آرایهای از کاربران در ساختار سبک جهت نمایش UI.
پارامترهای ورودی
| نام |
نوع |
محل |
الزامی |
توضیح |
| colleague_id |
integer |
query |
بله |
شناسه همکار |
| status |
integer |
query |
خیر |
فیلتر بر اساس وضعیت کاربر (۱:فعال، ۰:غیرفعال) |
| role |
string |
query |
خیر |
نام نقش یا سطح دسترسی کاربر در چارچوب آن همکار |
ساختار خروجی
{
"status": true,
"colleague_id": 52,
"users": [
{
"id": 410,
"name": "Sara Azimi",
"email": "s.azimi@example.com",
"mobile": "09131234567",
"role": "accountant",
"active": true,
"created_at": "2025‑05‑04 12:21:55"
},
...
]
}
نکات امنیتی
- دسترسی صرفاً برای کاربران با نقش
finance.admin یا colleague.manager.
- درخواست شامل توکن JWT صادرشده در domain شرکت اصلی است؛ توکنهای مشتری مجاز نیستند.
- فقط کاربران با وضعیت فعال (در صورت عدم ارسال پارامتر status) نمایش داده میشوند.
نکات عملکردی
- جدول
colleague_users دارای index ترکیبی (colleague_id, status) است برای lookup سریع.
- کش Redis با کلید
colleague:{id}:users تا ۱۵ دقیقه نگهداری میشود.
- درصورت تغییر، job
SyncColleagueUsers کش را تازهسازی میکند.
Dependencies
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use App\Models\ColleagueUser;
- use App\Models\User;
کدهای خطا
| کد |
شرح |
منبع |
| 400 |
پارامتر colleague_id ارسال نشده یا نامعتبر است |
Validation |
| 401 |
توکن احراز هویت فاقد مجوز دسترسی به این منبع است |
Middleware |
| 404 |
هیچ کاربری برای همکار مشخص یافت نشد |
DB Query |
| 500 |
خطای پایگاه داده یا Redis |
Exception |
پیشنهادهای امنیتی
- رمزنگاری ایمیل و شماره موبایل حساس در خروجی برای کاربران غیراختصاصی.
- اعمال policy
CanViewColleagueUser برای سطحبندی دسترسی هیأت حسابرسی.
- بهروزرسانی لاگ دسترسی برای هر فراخوانی موفق با IP کاربر.
پیشنهادهای توسعهای
ممیزی و لاگها
- Event ممیزی:
ColleagueUserListed
- فیلدهای ثبت:
user_id, colleague_id, count, ip, timestamp
- ثبت در
system_logs با نوع read_colleague_user
جمعبندی
تابع indexColleagueUser نمای کلی تمامی کاربران وابسته به یک همکار را بر میگرداند و بهعنوان منبع اصلی نمایش استاندارد در ماژول مدیریت همکاران است. پاسخ JSON آن بهطور بهینه و با حفظ امنیت اطلاعات تعریف شده است.
