Implement SMS panel user flow and patient records system; add wallet charging, automatic reminders, and patient session management with detailed database schema and user flows.

2026-06-14 21:15:40 +03:30
parent a72a6da621
commit b58aacc37f
28 changed files with 3169 additions and 0 deletions
@@ -0,0 +1,102 @@
+# جریان کاربری — تسک ۱۴: پنل پیامکی
+
+## جریان شارژ کیف پول پیامک
+
+```
+کاربر وارد صفحه تنظیمات → تب «پیامک» می‌شود
+          │
+          ▼
+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
+
+```
+┌─────────────────────────────────────────────────┐
+│  تنظیمات پیامک                                  │
+├──────────────────────┬──────────────────────────┤
+│ کیف پول پیامک        │ تنظیمات ارسال            │
+│                      │                          │
+│ موجودی:              │ یادآوری: ✅ ۳ ساعت قبل   │
+│ ۱۵۰,۰۰۰ ریال        │                          │
+│ ≈ ۶۰۰ پیامک         │ پس از ویزیت: ☐ غیرفعال  │
+│                      │                          │
+│ [شارژ کیف پول]       │ [ذخیره تنظیمات]          │
+├──────────────────────┴──────────────────────────┤
+│ تاریخچه تراکنش‌ها                               │
+│ ✅ +۵۰۰,۰۰۰ ریال — شارژ  — ۱۴۰۵/۰۳/۱۰        │
+│ ⬇️  -۲۵۰ ریال    — یادآوری نوبت — ۱۴۰۵/۰۳/۱۱ │
+└─────────────────────────────────────────────────┘
+```