#P1524
POST /colleague/user
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/colleague/user |
V2ColleaguesController@storeColleagueUser |
authWithJwt |
افزودن کاربر جدید به زیرمجموعه یک همکار در سیستم مالی/سازمانی |
منطق عملکرد تابع
تابع storeColleagueUser برای ایجاد یک کاربر جدید در زیرمجموعه همکار استفاده میشود. این تابع در ماژول مدیریت همکاران مورد استفاده مدیران مالی و مدیران همکار قرار میگیرد تا بتوانند کارمندان یا مسئولین دسترسی را تعریف کنند.
- اعتبارسنجی فیلدهای ورودی (نام، ایمیل، شماره تماس، رمز عبور، همکار ID و نقش).
- بررسی وجود ایمیل یا موبایل تکراری در جدول
users.
- ثبت کاربر در جدول
users و ایجاد رکورد متناظر در جدول colleague_users با شناسه همکار.
- تخصیص نقش و سطح دسترسی (RoleAssignment) مطابق policy داخلی.
- پاک کردن کش Redis (
colleague:{id}:users) برای بهروزرسانی لیست کاربران فعال.
- بازگرداندن پاسخ حاوی اطلاعات کاربر تازه ایجاد شده.
پارامترهای ورودی
| نام |
نوع |
محل |
الزامی |
توضیح |
| colleague_id |
integer |
body |
بله |
شناسه همکار مادر |
| name |
string |
body |
بله |
نام کامل کاربر |
| email |
string |
body |
بله |
ایمیل منحصربهفرد در سطح سامانه |
| mobile |
string |
body |
خیر |
شماره موبایل (به فرمت ۹۸+ یا ۰۹) |
| password |
string |
body |
بله |
رمز عبور تصادفی یا تعیینشده توسط مدیر |
| role |
string |
body |
بله |
نقش کاربر در چارچوب همکار (مثل accountant، viewer و...) |
| active |
boolean |
body |
خیر |
وضعیت فعال (پیشفرض true) |
ساختار خروجی
{
"status": true,
"message": "Colleague user created successfully",
"user": {
"id": 615,
"colleague_id": 52,
"name": "Ali Rahmani",
"email": "a.rahmani@example.com",
"mobile": "09130000000",
"role": "accountant",
"active": true,
"created_at": "2025‑11‑23 08:55:00"
}
}
نکات امنیتی
- فقط کاربران با نقش
finance.admin یا colleague.manager حق ایجاد کاربر دارند.
- رمز عبور بهصورت bcrypt در DB ذخیره میشود.
- در صورت تعریف اولیه، ایمیل فعالسازی برای کاربر ارسال میشود.
- در موارد حساس، ثبت در لاگ مدیریتی
system_logs انجام میشود.
نکات عملکردی
- کل فرآیند در یک تراکنش DB واحد (
transaction()) انجام میشود.
- زمان میانگین پاسخ زیر ۵۰ میلیثانیه در شبکه داخلی.
- دادههای کش کاربران همکار با TTL ۱۵ دقیقهای در Redis نگهداری میشود.
Dependencies
- use App\Models\User;
- use App\Models\ColleagueUser;
- use Illuminate\Support\Facades\DB;
- use Illuminate\Support\Facades\Redis;
- use Illuminate\Support\Facades\Hash;
کدهای خطا
| کد |
شرح |
منبع |
| 400 |
دادهٔ ورودی ناقص یا نامعتبر |
Validation |
| 401 |
توکن احراز هویت نامعتبر یا پایانیافته |
Middleware |
| 403 |
کاربر حق ایجاد کاربران همکار ندارد |
Policy |
| 409 |
ایمیل یا موبایل تکراری است |
DB Unique |
| 500 |
خطای عمومی در ثبت کاربر یا تراکنش Rollback |
Exception |
پیشنهادهای امنیتی
- فعالسازی مکانیزم ورود دو مرحلهای پس از ایجاد کاربر.
- ارسال رمز عبور موقت به ایمیل و مجبور کردن به تغییر در اولین ورود.
- جلوگیری از ایجاد نقشهای مدیریتی بدون تأیید Manual Admin.
پیشنهادهای توسعهای
- افزودن event تخصیص نقش زنده (Real‑Time Broadcast) برای refresh پنل.
- پشتیبانی از batch creation کاربران از فایل Excel.
- افزودن endpoint preview برای بررسی قبل از ثبت نهایی.
ممیزی و لاگها
- Event:
ColleagueUserCreated
- فیلدهای ثبت:
creator_id, colleague_id, user_id, ip, agent, timestamp
- ثبت در
system_logs با نوع create_colleague_user
جمعبندی
تابع storeColleagueUser امکان ایجاد، مدیریت و اتصال کاربران به بخش مالی همکاران را به شکل ایمن فراهم میکند. این endpoint پس از اجرای موفق، مبنای تخصیص نقشها و سطوح دسترسی در زیرسیستم Colleague است.
