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,127 @@
+# تسک ۱۴: پنل پیامکی — کیف پول + تنظیمات (SMS Panel)
+
+## توضیح
+زیرساخت SMS موجود است (`src/Sms/` — SmsLog, SmsTemplate, SmsProvider).
+این تسک **کیف پول پیامک** اختصاصی و **تنظیمات** ارسال خودکار را اضافه می‌کند.
+کیف پول پیامک مستقل از کیف پول مالی (`src/Settlement/`) است.
+
+## Endpoint ها (همه جدید)
+
+| متد | مسیر | Permission | توضیح |
+|-----|------|-----------|-------|
+| GET | `/api/v1/sms/wallet/balance` | doctor/clinic | موجودی کیف پول پیامک |
+| POST | `/api/v1/sms/wallet/charge` | doctor/clinic | شارژ کیف پول |
+| GET | `/api/v1/sms/wallet/logs` | doctor/clinic | تاریخچه کسر/شارژ |
+| GET | `/api/v1/sms/settings` | doctor/clinic | دریافت تنظیمات |
+| PATCH | `/api/v1/sms/settings` | doctor/clinic | ذخیره تنظیمات |
+| GET | `/api/v1/admin/sms/wallet-report` | ROLE_ADMIN | گزارش مصرف و درآمد |
+
+## پیش‌نیازها
+- تسک ۱۷ (SMS infrastructure — موجود)
+- تسک ۱۵-payment (Payment gateway — موجود)
+
+## زمان تخمینی
+۱۰ تا ۱۲ ساعت
+
+## نمونه Request
+
+### POST /api/v1/sms/wallet/charge
+```json
+{
+  "gateway": "mellat",
+  "amount_rials": 500000
+}
+```
+→ redirect به gateway (مثل payment نوبت، اما `Payment.type = 'sms_wallet'`)
+
+### PATCH /api/v1/sms/settings
+```json
+{
+  "reminder_enabled": true,
+  "reminder_hours_before": 3,
+  "post_visit_enabled": false,
+  "post_visit_text": null
+}
+```
+
+## نمونه Response
+
+### GET /api/v1/sms/wallet/balance
+```json
+{
+  "success": true,
+  "data": {
+    "balance_rials": 150000,
+    "sms_price_rials": 250,
+    "estimated_sms_count": 600
+  }
+}
+```
+
+### GET /api/v1/sms/wallet/logs
+```json
+{
+  "success": true,
+  "data": [
+    {
+      "uuid": "...",
+      "type": "credit",
+      "amount_rials": 500000,
+      "description": "شارژ کیف پول پیامک",
+      "created_at": 1718000000
+    },
+    {
+      "uuid": "...",
+      "type": "debit",
+      "amount_rials": 250,
+      "description": "ارسال پیامک یادآوری — نوبت ۱۴۰۵/۰۳/۱۵",
+      "created_at": 1718001000
+    }
+  ],
+  "meta": { "totalRecords": 45, "totalPages": 5, "currentPage": 1 }
+}
+```
+
+### GET /api/v1/sms/settings
+```json
+{
+  "success": true,
+  "data": {
+    "reminder_enabled": true,
+    "reminder_hours_before": 3,
+    "post_visit_enabled": false,
+    "post_visit_text": null
+  }
+}
+```
+
+### GET /api/v1/admin/sms/wallet-report
+```json
+{
+  "success": true,
+  "data": {
+    "total_charged_rials": 12500000,
+    "total_deducted_rials": 8750000,
+    "total_sms_sent": 35000,
+    "revenue_rials": 8750000,
+    "by_entity": [
+      { "entity_type": "clinic", "entity_id": 5, "name": "کلینیک سلامت", "spent_rials": 1500000 }
+    ]
+  }
+}
+```
+
+## SiteConfig key های مرتبط
+
+| کلید | توضیح |
+|------|-------|
+| `sms_price_rials` | قیمت هر پیامک — ادمین تنظیم می‌کند (مثلاً ۲۵۰ ریال) |
+
+## کسر خودکار هنگام ارسال پیامک
+
+```
+هر بار که SmsService::send() صدا زده می‌شود:
+  1. SmsWallet پیدا شود
+  2. اگر موجودی کافی نبود → پیامک ارسال نشود + لاگ خطا
+  3. اگر کافی بود → ارسال + کسر balance_rials + ثبت sms_wallet_transactions
+```