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

{
  "gateway": "mellat",
  "amount_rials": 500000
}

→ redirect به gateway (مثل payment نوبت، اما Payment.type = 'sms_wallet')

PATCH /api/v1/sms/settings

{
  "reminder_enabled": true,
  "reminder_hours_before": 3,
  "post_visit_enabled": false,
  "post_visit_text": null
}

نمونه Response

GET /api/v1/sms/wallet/balance

{
  "success": true,
  "data": {
    "balance_rials": 150000,
    "sms_price_rials": 250,
    "estimated_sms_count": 600
  }
}

GET /api/v1/sms/wallet/logs

{
  "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

{
  "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

{
  "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

3.4 KiB Raw Blame History