# POST /api/auth/connect/submit

<div id="bkmrk-" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### Route Info

<div id="bkmrk-method-endpoint-cont" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 95%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>Method</td><td>Endpoint</td><td>Controller</td><td>Middleware</td><td>Purpose</td><td>تگ Swagger</td></tr><tr><td style="direction: ltr; text-align: left;">POST</td><td style="direction: ltr; text-align: left;">/api/auth/connect/submit</td><td style="direction: ltr; text-align: left;">UserController@connectSubmit</td><td style="direction: ltr; text-align: left;">domainAccess, ipTrust</td><td style="direction: rtl; text-align: right;">تأیید نهایی اتصال اپراتور به سرویس جانبی پس از دریافت رمز OTP</td><td style="direction: ltr; text-align: left;">tags={"Auth"}</td></tr></tbody></table>

</div>### توضیح عملکرد (Function Logic)

<div id="bkmrk-%D8%A7%DB%8C%D9%86-endpoint-%D8%A8%D8%B1%D8%A7%DB%8C-%D9%81%D8%A7" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"><div style="direction: rtl; text-align: justify;">این Endpoint برای فاز نهایی فرآیند اتصال کاربر به سرویس جانبی (نظیر ربات تلگرام) استفاده می‌شود. پس از ارسال رمز موقت (OTP) از طریق مسیر **POST /api/auth/connect/otp**، اپراتور باید طی ۱۵ دقیقه آن را در این مسیر ثبت کند. در صورت صحت OTP و اعتبار زمانی آن، ارتباط کاربر ثبت و موفق اعلام می‌شود.</div>1. دریافت پارامترهای `personnel_id`، `otp` و `telegram` از درخواست.
2. جست‌وجوی اپراتور فعال در جدول `operators` براساس کد پرسنلی و رمز فعلی OTP.
3. بررسی انقضای OTP با درنظر گرفتن بازه زمانی ۱۵ دقیقه‌ای.
4. در صورت اعتبار، به‌روزرسانی ستون‌های `telegram` و `otp` (پاک کردن OTP).
5. ثبت رویداد در `SystemLog` با نوع `SubmitTelegram` و تاخیر ۱۰ دقیقه‌ای در صف `snailJob`.
6. ارسال پیامک اطلاع‌رسانی موفقیت اتصال با جزئیات IP و زمان شمسی.

</div>### ورودی‌ها (Inputs)

<div id="bkmrk-%D9%BE%D8%A7%D8%B1%D8%A7%D9%85%D8%AA%D8%B1-%D9%86%D9%88%D8%B9-%D8%AF%D8%A7%D8%AF%D9%87-%D8%A7%D9%84%D8%B2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"><table border="1" cellpadding="6" cellspacing="0" style="margin: 15px auto; width: 95%; border-collapse: collapse; text-align: center;"><tbody><tr style="background: #f9f9f9; font-weight: bold;"><td>پارامتر</td><td>نوع داده</td><td>الزامی</td><td>توضیح</td></tr><tr><td>personnel\_id</td><td>string</td><td>بله</td><td style="direction: rtl; text-align: right;">کد پرسنلی اپراتور فعال (status=1).</td></tr><tr><td>otp</td><td>integer</td><td>بله</td><td style="direction: rtl; text-align: right;">رمز یکبار مصرف صادرشده از مرحله‌ی قبلی.</td></tr><tr><td>telegram</td><td>string</td><td>بله</td><td style="direction: rtl; text-align: right;">شناسه یا شماره کاربری تلگرام کاربر برای اتصال.</td></tr><tr><td>branch</td><td>integer</td><td>خیر</td><td style="direction: rtl; text-align: right;">شناسه‌ی شعبه برای ارسال اطلاع‌رسانی از طریق سرویس پیامک.</td></tr></tbody></table>

<div style="direction: rtl; text-align: justify;">نمونه درخواست:</div></div>```
POST /api/auth/connect/submit
Content-Type: application/json

{
  "personnel_id": "P00157",
  "otp": "12345678",
  "telegram": "@aliiranpour",
  "branch": 1
}
```

<div id="bkmrk--1" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### خروجی‌ها (Outputs)

#### تصال موفق

```
{
  "status": true,
  "time": 1731963561,
  "message": "اتصال با موفقیت انجام شد."
}
```

#### رمز منقضی شده

```
{
  "status": false,
  "code": 1204,
  "message": "رمز یکبار مصرف منقضی شده است."
}
```

#### رمز اشتباه یا نامعتبر

```
{
  "status": false,
  "code": 1205,
  "message": "رمز یکبار مصرف وارد شده معتبر نمی باشد."
}
```

<div id="bkmrk--2" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### فرآیند بررسی زمان OTP

<div id="bkmrk-carbon%3A%3Anow%28%29-%3Eaddmi" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"><div style="direction: ltr; text-align: left; background: #fafafa; padding: 10px; border-radius: 6px; font-family: monospace;">Carbon::now()-&gt;addMinutes(-15) &lt;= $operator-&gt;otp_issuing</div><div style="direction: rtl; text-align: justify;">این شرط بررسی می‌کند که OTP مورد استفاده حداکثر ۱۵ دقیقه قبل صادر شده باشد. در صورت گذشتن بیش از ۱۵ دقیقه، سیستم خطای Expired Code با کد 1204 برمی‌گرداند.</div></div>### به‌روزرسانی جدول Operators

```
UPDATE operators
SET
  telegram = {request.telegram},
  otp = NULL
WHERE id = {operator.id};
```

<div id="bkmrk--3" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### ثبت رویداد در SystemLog

```
SystemLog::dispatch([
  "type" => "SubmitTelegram",
  "data" => null,
  "goal" => $request->personnel_id,
  "by" => $operator->id,
  "agent" => $_SERVER['HTTP_USER_AGENT'],
  "ip" => getIP(),
  "datetime" => Carbon::now()
])->delay(now()->addMinutes(10))->onQueue('snailJob');
```

<div id="bkmrk--4" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### پیامک موفقیت اتصال

```
پیامک:
اتصال شما به سرویس مورد نظر موفقیت آمیز بود.
زمان: شنبه، ۲۷ آبان ۱۴۰۳ | ۱۲:۴۵:۱۰
📍 IP: 192.168.1.24
🌐 example.domain
```

<div id="bkmrk-%D8%A7%D8%B1%D8%B3%D8%A7%D9%84-%D8%A7%D8%B2-%D8%B7%D8%B1%DB%8C%D9%82%3A" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;">ارسال از طریق:</div>```
StaticController::sendNotification($operator->mobile, $tempBody, $request->get('branch'));
```

<div id="bkmrk--5" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### وابستگی‌ها (Dependencies)

<div id="bkmrk-use-illuminate%5Chttp%5C" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;">- use Illuminate\\Http\\Request;
- use Illuminate\\Support\\Facades\\DB;
- use Carbon\\Carbon;
- use Morilog\\Jalali\\Jalalian;
- use App\\Jobs\\SystemLog;
- use App\\Http\\Controllers\\StaticController;

</div>### نمونه تست Postman

```
POST https://console.service01.ir/api/auth/connect/submit
Content-Type: application/json

{
  "personnel_id": "P00442",
  "otp": "55667788",
  "telegram": "@operator_test"
}
```

<div id="bkmrk--6" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;"></div>### تحلیل امنیتی

<div id="bkmrk-otp-%D9%81%D9%82%D8%B7-%DB%B1%DB%B5-%D8%AF%D9%82%DB%8C%D9%82%D9%87-%D8%A7%D8%B9%D8%AA" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;">- OTP فقط ۱۵ دقیقه اعتبار دارد.
- پس از تأیید موفق، مقدار آن از پایگاه‌داده حذف می‌شود (null).
- اطلاعات IP و User Agent در `SystemLog` ذخیره می‌گردند.
- ارسال پیامک از طریق سرویس داخلی شرکت انجام می‌شود و حاوی اطلاعات حساس نیست.
- وجود middleware‌ های `domainAccess` و `ipTrust` مانع ارسال از منابع غیرمجاز می‌گردد.

</div>### پیوست نگهداری و توسعه بعدی

<div id="bkmrk-%D8%A7%D8%AA%D8%B5%D8%A7%D9%84-%D8%A8%D9%87-%D8%B3%D8%B1%D9%88%DB%8C%D8%B3-webho" style="font-family: Vazir, Tahoma; direction: rtl; text-align: justify; line-height: 1.8;">- اتصال به سرویس `Webhook Telegram` برای تأیید دوطرفه.
- ثبت زمان دقیق اتصال در جدول پیشرفته audit\_log.
- افزودن محدودیت IP برای کاربران خاص در مرحله Submit.
- نمایش هشدار برای IPهای ناشناس محیط کاربری.

</div>`