# تسک ۱۴: پنل پیامکی — کیف پول + تنظیمات (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
```