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