#P1388
POST /api/auth/forgot/otp
Route Info
| Method | Endpoint | Controller | Middleware | Purpose | تگ Swagger |
| POST | /api/auth/forgot/otp | UserController@forgotOtp | domainAccess, ipTrust | ارسال OTP برای بازیابی کلمه عبور اپراتور | tags={"Auth"} |
توضیح عملکرد (Function Logic)
این مسیر جهت ارسال رمز موقت (OTP) به کاربرانی است که قصد دارند کلمه عبور خود را بازیابی کنند. پس از بررسی شماره موبایل و کد پرسنلی کاربر، سیستم رمز یکبار مصرف ۶ رقمی تولید کرده و آن را از طریق پیامک به شماره کاربر ارسال میکند. همچنین محدودیت ارسال (Throttle) برای جلوگیری از اسپم به کمک لاگ داخلی
Visa::showSystemLogs کنترل میشود.- یافتن اپراتور فعال با مشخصات دریافتی در جدول
operators. - بررسی آخرین ۵ ساعت لاگ برای نوع
SendOtp(حداکثر ۳ تلاش در ۵ ساعت). - در صورت مجاز بودن، ساخت رمز یکبار مصرف با طول ۶ رقم.
- ذخیره OTP و زمان صدور (
otp_issuing) در پایگاه داده. - ارسال پیامک حاوی OTP با تابع
StaticController::sendNotification. - در صورت موفقیت، ثبت لاگ در صف snailJob با تاخیر ۱۰ دقیقهای.
- بازگشت خروجی استاندارد شامل وضعیت، زمان، و پیام نتیجه.
ورودیها (Inputs)
| پارامتر | نوع داده | الزامی | توضیح |
| personnel_id | string | بله | شناسه پرسنلی کاربر دارای وضعیت فعال (status=1) |
| mobile | string (11 digits) | بله | شماره موبایل اصلی یا جایگزین اپراتور (mobile یا mobile1) |
| branch | integer | خیر | شناسه شعبه جهت ارجاع ارسال پیامک از شاخه مربوطه |
نمونه درخواست:
POST /api/auth/forgot/otp
Content-Type: application/json
{
"personnel_id": "P00123",
"mobile": "09131234567",
"branch": 1
}
خروجیها (Outputs)
ارسال موفق OTP
{
"status": true,
"time": 1731958300,
"message": "OTP با موفقیت ارسال گردید."
}
موبایل یا پرسنلی اشتباه
{
"status": false,
"code": 1201,
"message": "اطلاعات وارد شده با هیچ کاربری همخوانی ندارد"
}
پیامک ارسال نشد
{
"status": false,
"code": 1202,
"message": "پیامک OTP ارسال نشد. مشکلی رخ داده است. لطفا دوباره تلاش کنید",
"trace": { ... }
}
تعداد درخواست بیش از حد مجاز
{
"status": false,
"code": 1203,
"message": "تعداد درخواست های کاربر بیش از حد مجاز بوده است. لطفا 5 ساعت دیگر اقدام نمائید."
}
منطق محدودسازی درخواستها (Throttle)
برای جلوگیری از ارسال مکرر OTP، سیستم لاگهای نوع
SendOtp را بررسی کرده و فقط تا ۳ بار ارسال در بازه ۵ ساعته مجاز میباشد. در صورت تجاوز از این حد، پاسخ خطا با کد 1203 بازگردانده میشود.محتوای پیامک ارسالی (SMS Template)
code: 123456
این رمز جهت تغییر کلمه عبور صادر شده است.
از در اختیار قراردادن آن به دیگران جدا خودداری فرمائید.
مدت اعتبار: 15 دقیقه
example.domain
ثبت لاگ سیستمی (SystemLog Dispatch)
در صورت ارسال موفق پیامک، رویداد زیر با تأخیر ۱۰ دقیقه در صف
snailJob ثبت میشود:SystemLog::dispatch([
"type" => "SendOtp",
"goal" => operator_id,
"by" => operator_id,
"agent" => $_SERVER['HTTP_USER_AGENT'],
"ip" => getIP(),
"datetime" => now()
])->delay(now()->addMinutes(10))->onQueue('snailJob');
وابستگیها (Dependencies)
- use Illuminate\Http\Request;
- use Illuminate\Support\Facades\DB;
- use Carbon\Carbon;
- use App\Http\Controllers\StaticController;
- use App\Jobs\SystemLog;
- use App\Services\Visa;
نمونه تست (Postman Example)
POST https://console.service01.ir/api/auth/forgot/otp
Content-Type: application/json
{
"personnel_id": "P00999",
"mobile": "09138889999",
"branch": 3
}
تحلیل امنیتی
- رمز موقت (OTP) فقط ۱۵ دقیقه اعتبار دارد.
- در صورت سه تلاش ناموفق در ۵ ساعت، سیستم ارسال را قفل میکند.
- محدودسازی IP و domain در سطح middleware اعمال میشود.
- هیچ جزئی از OTP یا توکن در پاسخ لو نمیرود.
نتیجه عملکرد (Summary Result)
این Endpoint فرآیند صدور و ارسال OTP را برای بازنشانی رمز عبور مدیریت میکند. در کنار ارسال پیامک، با بررسی سوابق در
SystemLog از ارسالهای مکرر جلوگیری میشود.پیوست نگهداری و توسعه آتی
- افزودن قابلیت ارسال از طریق ایمیل در هزینههای آینده.
- ثبت بازه زمانی آخرین
otp_issuingبه عنوان معیاری برای مسیر /auth/forgot/submit. - پیشنهاد: استفاده از سرویس OTP متمرکز با لایه Redis برای اطمینان بیشتر.
`