feat(auth): add optional domain parameter to send OTP code for site personalization

2026-07-04 11:01:54 +03:30
parent 8df7b2f2e0
commit 1bb9cedd22
6 changed files with 177 additions and 6 deletions
@@ -0,0 +1,149 @@
+# افزودن اسم سایت شهر به پیامک کد تأیید (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 به‌روز کن (قانون استاندینگ پروژه).