clinicpro/docs/phase2_taskes/task-14-sms-panel/user_flow.md

جریان کاربری — تسک ۱۴: پنل پیامکی

جریان شارژ کیف پول پیامک

کاربر وارد صفحه تنظیمات → تب «پیامک» می‌شود
          │
          ▼
GET /api/v1/sms/wallet/balance
  → موجودی: ۱۵۰,۰۰۰ ریال (≈ ۶۰۰ پیامک)
          │
          ▼
کاربر روی «شارژ کیف پول» کلیک می‌کند
فرم: مبلغ شارژ + انتخاب gateway
          │
          ▼
POST /api/v1/sms/wallet/charge { gateway: 'mellat', amount_rials: 500000 }
          │
          ▼
PaymentController → ایجاد Payment با type='sms_wallet'
          │
          ▼
redirect به gateway بانک
          │
          ▼
callback → SmsWalletService::charge()
  → balance_rials += 500000
  → ثبت credit transaction
          │
          ▼
redirect به /admin/sms-settings?charged=1

جریان تنظیمات یادآوری خودکار

GET /api/v1/sms/settings → فرم پر می‌شود
          │
          ▼
┌─────────────────────────────────────────────┐
│  تنظیمات پیامک                              │
├─────────────────────────────────────────────┤
│ یادآوری نوبت                                │
│  [✅] فعال                                  │
│  چند ساعت قبل: [3 ساعت ▼]                  │
├─────────────────────────────────────────────┤
│ پیامک بعد از ویزیت                          │
│  [☐] فعال                                  │
│  متن پیامک: [______________________________]│
└─────────────────────────────────────────────┘
│ [ذخیره تنظیمات]                             │
          │
          ▼
PATCH /api/v1/sms/settings
  { reminder_enabled: true, reminder_hours_before: 3,
    post_visit_enabled: false, post_visit_text: null }

جریان کسر خودکار هنگام ارسال یادآوری

Scheduler/Cronjob اجرا می‌شود (هر ساعت)
          │
          ▼
نوبت‌هایی که در X ساعت آینده هستند پیدا می‌شوند
          │
          ▼
برای هر نوبت:
  entity_type/entity_id پیدا می‌شود
          │
          ▼
SmsWallet پیدا می‌شود
          │
          ├─► balance < sms_price_rials:
          │   لاگ خطا: «موجودی ناکافی» — پیامک ارسال نشد
          │
          └─► balance کافی:
              SmsService::send(phone, message, entityType, entityId)
              → ارسال پیامک
              → deduct balance
              → ثبت debit transaction با description='یادآوری نوبت'

نمایش در Frontend

┌─────────────────────────────────────────────────┐
│  تنظیمات پیامک                                  │
├──────────────────────┬──────────────────────────┤
│ کیف پول پیامک        │ تنظیمات ارسال            │
│                      │                          │
│ موجودی:              │ یادآوری: ✅ ۳ ساعت قبل   │
│ ۱۵۰,۰۰۰ ریال        │                          │
│ ≈ ۶۰۰ پیامک         │ پس از ویزیت: ☐ غیرفعال  │
│                      │                          │
│ [شارژ کیف پول]       │ [ذخیره تنظیمات]          │
├──────────────────────┴──────────────────────────┤
│ تاریخچه تراکنش‌ها                               │
│ ✅ +۵۰۰,۰۰۰ ریال — شارژ  — ۱۴۰۵/۰۳/۱۰        │
│ ⬇️  -۲۵۰ ریال    — یادآوری نوبت — ۱۴۰۵/۰۳/۱۱ │
└─────────────────────────────────────────────────┘