hamed/clinicpro
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: update OTP flow documentation and responses in AuthController

Browse Source
This commit is contained in:
hamed
2026-06-10 11:35:01 +03:30
parent e9075e8c92
commit 16ae439675
1 changed files with 27 additions and 60 deletions
Download Patch File Download Diff File Expand all files Collapse all files
src/Auth/Controller/AuthController.php
+26 -59
View File
@@ -89,48 +89,30 @@ class AuthController extends BaseController
#[OA\Post(
path: '/api/v1/user/send-code',
summary: 'Send OTP code to mobile number',
summary: 'مرحله ۱ — ارسال کد OTP به موبایل',
description: "**جریان لاگین با موبایل (OTP):**\n\n**مرحله ۱:** ارسال کد → **مرحله ۲:** تأیید کد (`/api/v1/user/verify-code`) → **مرحله ۳:** دریافت JWT (`/oauth/token`)\n\n> ⚠️ در محیط **dev** پیامکی ارسال نمی‌شود و کد همیشه `12345` است.",
requestBody: new OA\RequestBody(
required: true,
content: new OA\JsonContent(
required: ['mobile'],
properties: [
new OA\Property(property: 'mobile', type: 'string', example: '09123456789'),
new OA\Property(property: 'mobile', type: 'string', example: '09120671713', description: 'شماره موبایل ۱۱ رقمی'),
]
)
),
responses: [
new OA\Response(
response: 200,
description: 'OTP sent successfully',
description: 'کد OTP ارسال شد — uuid را برای مرحله بعد نگه دارید',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'uuid', type: 'string', format: 'uuid'),
new OA\Property(property: 'uuid', type: 'string', format: 'uuid', description: 'شناسه یکتا برای verify-code و oauth/token'),
new OA\Property(property: 'message', type: 'string', example: 'کد تایید با موفقیت ارسال شد.'),
]
)
),
new OA\Response(
response: 422,
description: 'Invalid mobile format',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: false),
new OA\Property(
property: 'errors',
type: 'array',
items: new OA\Items(
properties: [
new OA\Property(property: 'code', type: 'string'),
new OA\Property(property: 'message', type: 'string'),
],
type: 'object'
)
),
]
)
),
new OA\Response(response: 429, description: 'Rate limit exceeded'),
new OA\Response(response: 422, description: 'فرمت موبایل نادرست'),
new OA\Response(response: 429, description: 'تعداد درخواست از حد مجاز گذشت (۳ بار در ۵ دقیقه)'),
]
)]
#[Route('/api/v1/user/send-code', methods: ['POST'])]
@@ -155,55 +137,35 @@ class AuthController extends BaseController
#[OA\Post(
path: '/api/v1/user/verify-code',
summary: 'Verify OTP code',
summary: 'مرحله ۲ — تأیید کد OTP',
description: "uuid را از مرحله ۱ (`/api/v1/user/send-code`) وارد کنید.\n\n> در محیط **dev** کد همیشه `12345` است.\n\nپس از تأیید موفق، به مرحله ۳ (`/oauth/token`) بروید.",
requestBody: new OA\RequestBody(
required: true,
content: new OA\JsonContent(
required: ['uuid', 'code'],
properties: [
new OA\Property(property: 'uuid', type: 'string', format: 'uuid'),
new OA\Property(property: 'code', type: 'string', example: '12345'),
new OA\Property(property: 'uuid', type: 'string', format: 'uuid', description: 'uuid دریافت‌شده از send-code'),
new OA\Property(property: 'code', type: 'string', example: '12345', description: 'کد ۵ رقمی — در dev همیشه 12345'),
]
)
),
responses: [
new OA\Response(
response: 200,
description: 'Code verified successfully',
description: 'کد تأیید شد — به مرحله ۳ بروید',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: true),
new OA\Property(
property: 'data',
properties: [
new OA\Property(property: 'data', properties: [
new OA\Property(property: 'message', type: 'string', example: 'کد با موفقیت تایید شد.'),
],
type: 'object'
),
new OA\Property(property: 'errors', type: 'array', items: new OA\Items()),
]
)
),
new OA\Response(
response: 422,
description: 'Missing or invalid uuid/code',
content: new OA\JsonContent(
properties: [
new OA\Property(property: 'success', type: 'boolean', example: false),
new OA\Property(
property: 'errors',
type: 'array',
items: new OA\Items(
properties: [
new OA\Property(property: 'code', type: 'string'),
new OA\Property(property: 'message', type: 'string'),
],
type: 'object'
)
),
new OA\Property(property: 'is_new_user', type: 'boolean', example: false, description: 'اگر true باشد کاربر جدید است و باید ثبت‌نام کند (`/api/v1/user/register`)'),
], type: 'object'),
]
)
),
new OA\Response(response: 400, description: 'کد نادرست یا uuid منقضی'),
new OA\Response(response: 422, description: 'uuid یا code ارسال نشده'),
new OA\Response(response: 429, description: 'تعداد تلاش از حد مجاز گذشت (۵ بار)'),
]
)]
#[Route('/api/v1/user/verify-code', methods: ['POST'])]
@@ -217,9 +179,13 @@ class AuthController extends BaseController
return $this->error(ErrorCodes::ERR_VALIDATION_002, 'uuid و code الزامی است', 422);
}
$this->otpService->verifyCode($uuid, $code);
$otpData = $this->otpService->verifyCode($uuid, $code);
$isNewUser = $this->userRepo->findByMobile($otpData['mobile']) === null;
return $this->success(['message' => 'کد با موفقیت تایید شد.']);
return $this->success([
'message' => 'کد با موفقیت تایید شد.',
'is_new_user' => $isNewUser,
]);
}
#[OA\Post(
@@ -303,7 +269,8 @@ class AuthController extends BaseController
#[OA\Post(
path: '/oauth/token',
summary: 'Issue access and refresh tokens using OTP-verified UUID',
summary: 'مرحله ۳ — دریافت JWT با uuid تأییدشده',
description: 'uuid را از مرحله ۱ (`/api/v1/user/send-code`) وارد کنید — **بعد از** اینکه در مرحله ۲ (`/api/v1/user/verify-code`) تأیید شد. access_token را در header درخواست‌های بعدی استفاده کنید: `Authorization: Bearer <access_token>`',
requestBody: new OA\RequestBody(
required: true,
content: new OA\JsonContent(