#P1385
POST /api/auth/sign-in
Route Info
| Method | Endpoint | Controller | Middleware | Purpose | تگ Swagger |
| POST | /api/auth/sign-in | UserController@signIn | domainAccess, ipTrust | ورود اپراتور با شناسه پرسنلی و رمز عبور | tags={“Auth”} |
توضیح عملکرد (Function Logic)
تابع
signIn() مسئول احراز هویت اپراتور بر اساس شناسهٔ پرسنلی و رمز عبور است. این فرایند شامل مراحل زیر میباشد:
- اعتبارسنجی ورودی
branch(شعبه) و دادهٔdataکه شاملpersonnelIdوpasswordاست. - جستجوی اپراتور در جدول
operators، بررسی انطباق شعبه (مقدار[0]یا شامل branch در JSON). - بررسی وضعیت مسدودی اکانت (حوزه فیلد
blocked_up). - بررسی رمز عبور با
Hash::check(). - در صورت معتبر بودن و فعال بودن حساب (
status == 1): تولید JWT Token، ثبت لاگ با تأخیر ۱۰ دقیقه، ذخیره Shortcutها و ارسال نوتیفیکیشن تلگرام. - در صورت وضعیت غیرفعال یا خطای رمز، بازگرداندن پیام خطا مطابق Swagger.
- در بخش
catch، بازگرداندن خطای Exception با پیام و Trace.
ورودیها (Inputs)
| پارامتر | نوع داده | الزامی | توضیح |
| branch | integer | بله | شناسه شعبهای که اپراتور به آن وارد میشود. |
| data.personnelId | string | بله | شناسه پرسنلی اپراتور برای ورود. |
| data.password | string | بله | رمز عبور اپراتور (hash شده در دیتابیس). |
نمونه درخواست:
POST /api/auth/sign-in
Content-Type: application/json
{
“branch”: 1,
“data”: {
“personnelId”: “101234”,
“password”: “12345678”
}
}
خروجیها (Outputs)
پاسخ موفق (HTTP 200)
{
“user”: {
“uuid”: 1,
“from”: “users”,
“role”: “admin”,
“isAirPlusAdmin”: true,
“group”: “IT”,
“data”: {
“displayName”: “علی شاکرچکی”,
“personnelId”: “101234”,
“branch”: “[0]”,
“telegram”: true,
“position”: “مدیر فناوری اطلاعات”,
“access”: […],
“shortcuts”: […]
}
},
“access_token”: “jwt.token.value”
}
خطا در احراز هویت (HTTP 401)
{
“error”: [
{
“type”: “personnelId”,
“message”: “اطلاعات کاربری همخوانی ندارد.”
}
]
}
حساب کاربری مسدود
{
“error”: [
{
“type”: “personnelId”,
“message”: “حساب کاربری شما مسدود شده است.”
}
]
}
منطق تولید JWT Token
توکن JWT شامل فیلدهای کلیدی زیر است:
{
“typ”: “base”,
“iss”: “{DomainHeader}”,
“aud”: “{DomainHeader}”,
“iat”: 1731927000,
“exp”: 1732531800,
“uuid”: “{OperatorId}”,
“brn”: “{Branch}”,
“uip”: “{ClientIP}”,
“brw”: “{UserAgentClient}”
}
سیستم لاگ و اعلانها
- ثبت لاگ با تأخیر ۱۰ دقیقهای از نوع
SystemLog::dispatch(type=‘Login’) - در صورت فعال بودن فیلد
telegram، ارسال پیام ورود موفق به اکانت تلگرام اپراتور با دکمه «اتمام جلسه» - توکن موقت برای لینک مسدودی ۱۵ دقیقهای ساخته و در DB ذخیره میشود.
مدیریت اعلان (Push & Telegram)
در صورت وجود شناسهٔ تلگرام در درجۀ
Operator->telegram، Dispatcher پیام مارکدان را ارسال میکند شامل:
- نام و آیدی پرسنلی
- شعبه و دامنه
- IP و مرورگر دستگاه
- دکمه مسدودی موقت
موارد خطا (Error Cases)
- رمز عبور اشتباه یا عدم تطابق شناسه پرسنلی
- حساب کاربری غیرفعال (
status != 1) - حساب مسدود تا زمان مشخصشده در
blocked_up - Exception هنگام تولید JWT یا ثبت در Redis/DB
وابستگیها (Dependencies)
use Firebase\JWT\JWT;use Jenssegers\Agent\DeviceDetector;use Illuminate\Support\Facades\Hash;use Illuminate\Support\Facades\DB;use Carbon\Carbon, Morilog\Jalali\Jalalian;use Redis, Str, SendNotification, SystemLog;
نمونه تست واقعی (Postman Example)
POST https://console.service01.ir/api/auth/sign-in
Headers:
Domain: service01.ir
Content-Type: application/json
Body:
{
“branch”: 2,
“data”: {
“personnelId”: “104512”,
“password”: “test@1234”
}
}
نتیجه عملکرد (Result Summary)
در صورت موفقیت، JWT توکن برای ۷ روز معتبر ایجاد میشود و اپراتور احراز هویتشده به همراه تنظیمات رابط کاربری از Redis و دسترسیها برگردانده میشود. مسیر در Swagger با Security نوع
bearerAuth ثبت میگردد.پیوست: نکات امنیتی
- تمام درخواستها باید از دامنهی معتبر (Header:
Domain) ارسال شوند. - فیلد
passwordباید باHash::checkمطابقت یابد؛ رمزها هیچگاه در plain text ذخیره نشوند. - از Env Key
JWT_SECRET_KEYبرای encode استفاده گردد. - فرآیند Telegram notification در صف
fastJobایزوله شود. - برای لاگ ورود از صف
snailJobجهت تأخیر بارگذاری استفاده گردد.