150 lines
8.9 KiB
Markdown
150 lines
8.9 KiB
Markdown
# افزودن اسم سایت شهر به پیامک کد تأیید (OTP) — بهصورت اختیاری
|
||
|
||
## پروژه
|
||
|
||
`clinicpro` (Backend) — **cross-repo**؛ پرامپت همتای frontend: `nobat724_front/.claude/prompt/otp-sms-site-name.md`
|
||
|
||
## زمینه
|
||
|
||
سایت عمومی چند-دامنهای است (هر شهر یک دامنه: `yasuj-nobat.ir`، `ahvaz-nobat.ir`، ...). هر شهر در جدول `cities` فیلد `site_name` دارد (مثل «یاسوج نوبت»). الان پیامک کد تأیید ورود ثابت است: `کد تأیید شما: {code}` و اسم سایت شهر ندارد.
|
||
|
||
هدف: بتوان **اختیاری** اسم سایتِ شهرِ درخواستکننده را در پیامک OTP نمایش داد — مثلاً «کد تأیید شما در یاسوج نوبت: ۱۲۳۴۵». اختیاریبودن از طریق **قالب قابلویرایش پنل SMS** کنترل میشود: اگر ادمین `{site}` را در متن قالب بگذارد نمایش داده میشود، نگذارد نمیشود.
|
||
|
||
## مشکل / هدف
|
||
|
||
- درخواست `send-code` از دامنهی شهر به API (`api.clinic-pro.ir`) میرسد → `Host` = دامنهی API، نه شهر. پس backend خودش شهر را نمیفهمد.
|
||
- **راهحل:** frontend دامنهی خودش را در body میفرستد؛ backend از روی `domain` در جدول `cities` → `site_name` را پیدا میکند و بهعنوان متغیر `{site}` به قالب پیامک تزریق میکند. اگر شهری پیدا نشد یا `domain` نیامد → fallback به برند پیشفرض «نوبت ۷۲۴».
|
||
- متغیر `{site}` همیشه مقداردهی میشود؛ استفاده یا عدماستفادهاش به قالب بستگی دارد (اختیاری).
|
||
|
||
## فایلهای مرتبط
|
||
|
||
| فایل | نقش |
|
||
|------|-----|
|
||
| `src/Auth/Controller/AuthController.php` | endpoint `POST /api/v1/user/send-code` — خواندن `domain` اختیاری از body |
|
||
| `src/Auth/Service/OtpService.php` | ساخت و ارسال پیامک OTP — resolve اسم سایت و تزریق `{site}` |
|
||
| `src/Location/Repository/CityRepository.php` | lookup شهر بر اساس `domain` |
|
||
| `src/Location/Entity/City.php` | دارای `getDomain()` و `getSiteName()` (آماده، تغییر نمیخواهد) |
|
||
| `src/Sms/Entity/SmsMessageTemplate.php` | ثبت `{site}` بهعنوان متغیر مجاز قالب OTP |
|
||
| `docs/api/auth.md`, `docs/api/sms.md` | مستندسازی |
|
||
|
||
## وضعیت فعلی
|
||
|
||
`OtpService::sendCode` (src/Auth/Service/OtpService.php):
|
||
|
||
```php
|
||
public function sendCode(string $mobile): string
|
||
{
|
||
$uuid = Uuid::v4()->toRfc4122();
|
||
$code = $this->appEnv === 'dev' ? '12345' : str_pad((string) random_int(10000, 99999), 5, '0', STR_PAD_LEFT);
|
||
// ... cache set ...
|
||
if ($this->appEnv !== 'dev') {
|
||
$message = $this->smsText->resolve(SmsLog::TAG_OTP, ['code' => $code]);
|
||
$this->sms->dispatchAsync($mobile, $message, tag: SmsLog::TAG_OTP);
|
||
}
|
||
return $uuid;
|
||
}
|
||
```
|
||
|
||
`AuthController::sendCode` (src/Auth/Controller/AuthController.php:136):
|
||
|
||
```php
|
||
$data = json_decode($request->getContent(), true) ?? [];
|
||
$mobile = trim($data['mobile'] ?? '');
|
||
// ... validation + rate limit ...
|
||
$uuid = $this->otpService->sendCode($mobile);
|
||
```
|
||
|
||
قالب پیشفرض OTP (src/Sms/Entity/SmsMessageTemplate.php):
|
||
|
||
```php
|
||
SmsLog::TAG_OTP => [
|
||
'title' => 'کد تأیید ورود',
|
||
'body' => 'کد تأیید شما: {code}',
|
||
'variables' => ['code'],
|
||
],
|
||
```
|
||
|
||
resolver (src/Sms/Service/SmsTextResolver.php) هر `{key}` را با str_replace جایگزین میکند — پس `{site}` بدون تغییر resolver کار میکند.
|
||
|
||
## وظایف
|
||
|
||
### ۱. `OtpService` — resolve اسم سایت و تزریق `{site}`
|
||
|
||
- `CityRepository` را به constructor تزریق کن.
|
||
- امضای متد را به `sendCode(string $mobile, ?string $domain = null)` تغییر بده (پارامتر اختیاری → سازگاری عقبرو).
|
||
- اسم سایت را resolve کن و به متغیرهای قالب اضافه کن:
|
||
|
||
```php
|
||
public function sendCode(string $mobile, ?string $domain = null): string
|
||
{
|
||
// ... code + cache بدون تغییر ...
|
||
if ($this->appEnv !== 'dev') {
|
||
$site = $this->resolveSiteName($domain);
|
||
$message = $this->smsText->resolve(SmsLog::TAG_OTP, ['code' => $code, 'site' => $site]);
|
||
$this->sms->dispatchAsync($mobile, $message, tag: SmsLog::TAG_OTP);
|
||
}
|
||
return $uuid;
|
||
}
|
||
|
||
private function resolveSiteName(?string $domain): string
|
||
{
|
||
$default = 'نوبت ۷۲۴';
|
||
if (!$domain) {
|
||
return $default;
|
||
}
|
||
$domain = strtolower(trim(preg_replace('#^https?://#', '', $domain)));
|
||
$domain = preg_replace('#/.*$#', '', $domain); // strip path
|
||
$city = $this->cityRepo->findOneBy(['domain' => $domain]);
|
||
return $city?->getSiteName() ?: $default;
|
||
}
|
||
```
|
||
|
||
- **نکته:** `{site}` همیشه مقدار دارد؛ اگر قالب فعلی `{site}` نداشته باشد، این متغیر بیاثر است (اختیاریبودن حفظ میشود).
|
||
|
||
### ۲. `AuthController::sendCode` — خواندن `domain` اختیاری از body
|
||
|
||
```php
|
||
$mobile = trim($data['mobile'] ?? '');
|
||
$domain = isset($data['domain']) ? trim((string) $data['domain']) : null;
|
||
// ... validation + rate limit بدون تغییر ...
|
||
$uuid = $this->otpService->sendCode($mobile, $domain ?: null);
|
||
```
|
||
|
||
- `domain` اختیاری است؛ اگر نیامد، رفتار قبلی حفظ میشود.
|
||
- روی `domain` **validation سختگیرانه لازم نیست** (فقط برای lookup استفاده میشود، نه اجرا)، اما trim و طول محدود (مثلاً حداکثر ۲۵۳ کاراکتر) اعمال کن.
|
||
|
||
### ۳. `SmsMessageTemplate` — ثبت `{site}` بهعنوان متغیر مجاز OTP
|
||
|
||
قالب پیشفرض را **بدون** `{site}` نگه دار (opt-in)، اما `site` را به لیست `variables` اضافه کن تا در پنل ویرایش قالب بهعنوان متغیر قابلاستفاده نمایش داده شود:
|
||
|
||
```php
|
||
SmsLog::TAG_OTP => [
|
||
'title' => 'کد تأیید ورود',
|
||
'body' => 'کد تأیید شما: {code}', // پیشفرض بدون site
|
||
'variables' => ['code', 'site'], // site بهعنوان متغیر اختیاری در پنل
|
||
],
|
||
```
|
||
|
||
- اینطوری ادمین در پنل SMS میتواند body را به `کد تأیید شما در {site}: {code}` تغییر دهد تا اسم سایت نمایش داده شود — یا ندهد.
|
||
|
||
### ۴. مستندسازی
|
||
|
||
- `docs/api/auth.md`: در `POST /api/v1/user/send-code`، فیلد **اختیاری** `domain` را به request body اضافه کن (نوع string، توضیح: دامنهی شهرِ درخواستکننده برای شخصیسازی متن پیامک؛ اگر نیامد از برند پیشفرض استفاده میشود). نمونه request/response را بهروز کن.
|
||
- `docs/api/sms.md`: متغیر جدید `{site}` را برای قالب `OTP` مستند کن (مقدار = `site_name` شهرِ دامنه یا «نوبت ۷۲۴»).
|
||
|
||
## نکات مهم
|
||
|
||
- **backward-compatible**: هر دو `domain` (body) و پارامتر `sendCode` اختیاریاند؛ کلاینتهای فعلی (پنل ادمین clinicpro، لاگین بدون domain) بدون تغییر کار میکنند و برند پیشفرض را میگیرند.
|
||
- محیط `dev`: پیامک ارسال نمیشود (کد ثابت `12345`) — این مسیر دستنخورده بماند.
|
||
- `{site}` هرگز خالی نباشد (fallback «نوبت ۷۲۴») تا اگر ادمین `{site}` را در قالب گذاشت، متن ناقص «... در : ...» تولید نشود.
|
||
- lookup دامنه: مقدار ارسالی frontend ممکن است `yasuj-nobat.ir` یا با `www.`/`https://` باشد — در `resolveSiteName` normalize کن (حذف پروتکل و path). اگر لازم شد `www.` را هم strip کن، اما مقادیر `cities.domain` بدون `www` ذخیره شدهاند (مثل `yasuj-nobat.ir`).
|
||
- **پیامک OTP با پترن اپراتور:** provider پترن `{site}` را پشتیبانی میکند (تأییدشده). مطمئن شو ترتیب/نام متغیرها با پترن مصوب سامانهی پیامکی هماهنگ است.
|
||
- تست:
|
||
```bash
|
||
ddev exec php -l src/Auth/Service/OtpService.php
|
||
ddev exec php -l src/Auth/Controller/AuthController.php
|
||
ddev exec php bin/console cache:clear
|
||
# ارسال با domain و بدون domain را در محیط staging بررسی کن (dev پیامک نمیفرستد)
|
||
```
|
||
- بعد از تغییر API، `docs/api/auth.md` و `docs/api/sms.md` را در همین session بهروز کن (قانون استاندینگ پروژه).
|