feat(sms): add doctor appointment notification SMS for paid appointments

2026-07-02 21:11:17 +03:30
parent 10be1728ff
commit 1804b4215d
5 changed files with 162 additions and 1 deletions
@@ -0,0 +1,141 @@
+# پیامک اعلان نوبت جدید به «شمارهٔ اعلان» دکتر (فقط نوبت‌های پرداخت‌شدهٔ سایت)
+
+## پروژه
+
+`clinicpro` (backend / Payment + Sms)
+
+## زمینه
+
+هر دکتر در `/admin/profile` یک «شمارهٔ اعلان نوبت» (`Doctor::notificationMobile`) ست می‌کند («پیامک نوبت جدید به این شماره ارسال می‌شود»). این فیلد و تگ `SmsLog::TAG_NOTIFICATION_MOBILE` وجود دارند، ولی تگ فعلی فقط برای **تأیید ثبت شماره** (کد تأیید در `NotificationMobileController`) استفاده می‌شود — به رویداد «نوبت جدید» وصل نیست.
+
+الان هنگام موفقیت پرداخت نوبت، فقط به **بیمار** پیامک می‌رود (`PaymentManager::handleAppointmentConfirmation` با تگ `TAG_PAYMENT`). هدف: علاوه بر آن، به **شمارهٔ اعلانِ دکتر** هم یک پیامک با قالب مشخص (شامل نام بیمار و ساعت نوبت) ارسال شود.
+
+**فقط نوبت‌های پرداخت‌شده از سایت** باید این پیامک را بدهند — نه نوبت‌هایی که منشی ثبت می‌کند. چون `handleAppointmentConfirmation` **فقط** در مسیر موفقیت پرداخت (`PaymentManager::processCallback` → `runPostAction`) اجرا می‌شود و نوبت‌های ثبت‌شده توسط منشی از این مسیر عبور نمی‌کنند، افزودن کد در همین‌جا به‌طور طبیعی شرط «فقط سایت/پرداخت» را رعایت می‌کند.
+
+## مشکل / هدف
+
+هنگام تأیید پرداختِ یک نوبت، اگر دکترِ آن نوبت `notificationMobile` ست کرده باشد، یک پیامک با تگ/قالب اختصاصی (`TAG_DOCTOR_APPOINTMENT`) شامل `{patient}` و `{date}` و `{time}` به آن شماره ارسال شود.
+
+## فایل‌های مرتبط
+
+| فایل | نقش |
+|------|-----|
+| `clinicpro/src/Sms/Entity/SmsLog.php` | افزودن تگ `TAG_DOCTOR_APPOINTMENT` + به آرایهٔ `TAGS` |
+| `clinicpro/src/Sms/Entity/SmsMessageTemplate.php` | افزودن قالب پیش‌فرض این تگ به `DEFAULTS` |
+| `clinicpro/src/Payment/Service/PaymentManager.php` | ارسال پیامک به `notificationMobile` دکتر در `handleAppointmentConfirmation` |
+| `clinicpro/docs/api/sms.md` | مستندسازی تگ/قالب جدید |
+
+## وضعیت فعلی
+
+### `PaymentManager::handleAppointmentConfirmation` (فقط پیامک بیمار)
+
+```php
+private function handleAppointmentConfirmation(Payment $payment): void
+{
+    $appointment = $payment->getAppointment();
+    if ($appointment === null || !$appointment->canTransitionTo(Appointment::STATUS_CONFIRMED)) {
+        return;
+    }
+
+    $appointment->transitionTo(Appointment::STATUS_CONFIRMED);
+    $this->em->persist($appointment);
+
+    $doctor = $appointment->getDoctor();
+    $this->commissionService->processAppointment(
+        $payment,
+        $doctor->getRepresentationId(),
+        $appointment->getBookingRepresentationId(),
+        $doctor->getId(),
+    );
+
+    $mobile = $appointment->getPatientMobile();
+    if ($mobile) {
+        $when    = $this->jalali->formatDateTime($appointment->getSlotStart());
+        $message = $this->smsText->resolve(SmsLog::TAG_PAYMENT, [
+            'doctor' => $doctor->getName(),
+            'date'   => $when,
+        ]);
+        $this->smsService->dispatchAsync($mobile, $message, tag: SmsLog::TAG_PAYMENT);
+    }
+}
+```
+
+### مقادیر در دسترس
+
+- `Doctor::getNotificationMobile(): ?string` (فیلد `notification_mobile`, nullable)
+- `Doctor::getName()`
+- `Appointment::getPatientName(): ?string`، `getPatientMobile()`، `getSlotStart(): int` (unix)
+- `JalaliDateService::formatDateTime(int $ts, bool $withTime = true): string` — `false` = فقط تاریخ شمسی. متد جدا برای «ساعت» ندارد؛ ساعت را با `date('H:i', $slotStart)` بگیر.
+
+### الگوی تگ‌ها (SmsLog)
+
+```php
+public const TAG_NOTIFICATION_MOBILE = 'notification_mobile';
+public const TAGS = [ self::TAG_GLOBAL, self::TAG_OTP, self::TAG_PAYMENT, /* ... */ self::TAG_SECRETARY ];
+```
+
+### الگوی قالب‌ها (SmsMessageTemplate::DEFAULTS)
+
+```php
+SmsLog::TAG_PAYMENT => [
+    'title'     => 'تأیید پرداخت و نوبت',
+    'body'      => 'نوبت شما با {doctor} در تاریخ {date} ثبت و تأیید شد.',
+    'variables' => ['doctor', 'date'],
+],
+```
+
+## وظایف
+
+### ۱. تگ جدید در `SmsLog`
+
+```php
+public const TAG_DOCTOR_APPOINTMENT = 'doctor_appointment';
+```
+و آن را به آرایهٔ `TAGS` اضافه کن (تا در پنل مدیریت قالب‌ها و seed شناخته شود).
+
+### ۲. قالب پیش‌فرض در `SmsMessageTemplate::DEFAULTS`
+
+```php
+SmsLog::TAG_DOCTOR_APPOINTMENT => [
+    'title'     => 'نوبت جدید (اعلان به پزشک)',
+    'body'      => "نوبت جدید ثبت شد.\nبیمار: {patient}\nتاریخ: {date} ساعت {time}",
+    'variables' => ['patient', 'date', 'time'],
+],
+```
+
+### ۳. ارسال پیامک به شمارهٔ اعلان دکتر در `handleAppointmentConfirmation`
+
+بعد از بلوک پیامک بیمار (داخل همان متد)، اضافه کن:
+
+```php
+$notify = $doctor->getNotificationMobile();
+if ($notify) {
+    $docMessage = $this->smsText->resolve(SmsLog::TAG_DOCTOR_APPOINTMENT, [
+        'patient' => $appointment->getPatientName() ?? '—',
+        'date'    => $this->jalali->formatDateTime($appointment->getSlotStart(), false),
+        'time'    => date('H:i', $appointment->getSlotStart()),
+    ]);
+    $this->smsService->dispatchAsync($notify, $docMessage, tag: SmsLog::TAG_DOCTOR_APPOINTMENT);
+}
+```
+
+### ۴. seed قالب جدید
+
+بعد از افزودن به `DEFAULTS`، دستور موجود را اجرا کن تا رکورد قالب برای تگ جدید ساخته شود (فقط تگ‌های بدون رکورد را می‌سازد):
+```bash
+ddev exec php bin/console app:seed-sms-message-templates
+```
+
+### ۵. مستندسازی
+
+`docs/api/sms.md`: تگ `doctor_appointment`، قالب پیش‌فرض، placeholderها (`patient`/`date`/`time`)، و اینکه فقط برای نوبت‌های **پرداخت‌شدهٔ سایت** (در مسیر verify پرداخت) ارسال می‌شود و به `Doctor.notificationMobile` می‌رود.
+
+## نکات مهم
+
+- **فقط مسیر پرداخت:** کد داخل `handleAppointmentConfirmation` است که تنها از `runPostAction` بعد از verify موفق صدا زده می‌شود؛ نوبت‌های منشی (بدون پرداخت) این‌جا نمی‌آیند — پس شرط «نه نوبت منشی» خودکار برقرار است. کد را جای دیگری (مثل ساخت نوبت) نگذار.
+- اگر `notificationMobile` خالی بود، هیچ پیامکی نرود (شرط `if ($notify)`).
+- `dispatchAsync` مثل پیامک بیمار استفاده شود (صف async، شکست پیامک نباید جریان پرداخت را بشکند — الگوی موجود).
+- ارسال پیامک دکتر **مستقل از** پیامک بیمار است (حتی اگر `patientMobile` خالی باشد، پیامک دکتر باید برود).
+- `title`/`body` قالب فارسی و قابل ویرایش از پنل قالب‌هاست؛ فقط مقدار پیش‌فرض را در `DEFAULTS` بگذار.
+- `Doctor` تغییر Entity ندارد (فیلد موجود است) → migration لازم نیست.
+- هزینهٔ پیامک: این پیامک هم مثل بقیه از کیف‌پول/سهمیهٔ پیامک همان entity کسر می‌شود (اگر `SmsService`/wallet چنین منطقی دارد، خودکار اعمال می‌شود؛ چیزی اضافه نکن مگر لازم شود).