hamed
de1a78a235
- Add SendSmsMessage class for encapsulating SMS message data. - Create KavehNegarProvider and RanginehProvider classes implementing SmsProviderInterface for sending SMS. - Implement SmsLogRepository and SmsTemplateRepository for managing SMS logs and templates. - Develop SendSmsHandler for handling SMS sending messages. - Create SmsService to manage SMS dispatching and logging. - Add UserProfileController for managing user profiles with CRUD operations. - Implement UserProfile entity and repository for user profile data management. - Update symfony.lock and bootstrap.php for project dependencies and environment setup.
118 lines
4.0 KiB
Markdown
118 lines
4.0 KiB
Markdown
# تسک ۱۸: ماژول تسویه نماینده (Settlement)
|
||
|
||
## توضیح
|
||
سیستم تسویهحساب نمایندگان — هر بار که از طریق دامنه یک نماینده نوبت پرداخت میشود،
|
||
کمیسیون مشخصی (طبق `commission_percent`) به کیف پول نماینده واریز میشود.
|
||
نماینده میتواند درخواست تسویه (برداشت) بدهد و ادمین آن را تأیید/رد میکند.
|
||
|
||
## فلوی کمیسیون (از مستند)
|
||
|
||
```
|
||
بیمار → پرداخت نوبت از دامنه نماینده
|
||
→ commission = amount × (commission_percent / 100)
|
||
→ واریز به کیف پول نماینده (wallet_transactions)
|
||
|
||
دکتر → خرید اشتراک از طریق نماینده
|
||
→ کمیسیون اشتراک → واریز به کیف پول نماینده
|
||
```
|
||
|
||
## Endpoint ها
|
||
|
||
| متد | مسیر | توضیح | نیاز به Auth |
|
||
|-----|------|-------|-------------|
|
||
| GET | `/api/v1/representation/{id}/wallet` | موجودی کیف پول نماینده | بله (Admin / Owner) |
|
||
| GET | `/api/v1/representation/{id}/wallet/transactions` | تاریخچه تراکنشهای کیف پول | بله (Admin / Owner) |
|
||
| POST | `/api/v1/representation/{id}/settlement` | درخواست تسویه توسط نماینده | بله (Owner) |
|
||
| GET | `/api/v1/settlements` | لیست همه درخواستهای تسویه | بله (Admin) |
|
||
| GET | `/api/v1/settlement/{uuid}` | جزئیات یک درخواست تسویه | بله (Admin / Owner) |
|
||
| PATCH | `/api/v1/settlement/{uuid}/approve` | تأیید تسویه توسط ادمین | بله (Admin) |
|
||
| PATCH | `/api/v1/settlement/{uuid}/reject` | رد تسویه توسط ادمین | بله (Admin) |
|
||
|
||
## پیشنیازها
|
||
- تسک ۰۱، ۰۲، ۱۵ (Payment)، ۱۶ (Representation)
|
||
|
||
## زمان تخمینی
|
||
۸ تا ۱۰ ساعت
|
||
|
||
---
|
||
|
||
## نمونه Request — POST /api/v1/representation/{id}/settlement
|
||
|
||
```json
|
||
{
|
||
"amount": 5000000,
|
||
"card_number": "6037-9999-1234-5678",
|
||
"bank_name": "ملت",
|
||
"description": "تسویه اسفندماه ۱۴۰۳"
|
||
}
|
||
```
|
||
|
||
## نمونه Response — GET /api/v1/representation/{id}/wallet
|
||
|
||
```json
|
||
{
|
||
"representation_id": 3,
|
||
"balance": 12500000,
|
||
"total_earned": 35000000,
|
||
"total_settled": 22500000,
|
||
"pending_settlement": 0
|
||
}
|
||
```
|
||
|
||
## نمونه Response — GET /api/v1/representation/{id}/wallet/transactions
|
||
|
||
```json
|
||
{
|
||
"data": [
|
||
{
|
||
"uuid": "...",
|
||
"type": "credit",
|
||
"amount": 50000,
|
||
"source": "appointment",
|
||
"source_id": 142,
|
||
"description": "کمیسیون نوبت #142",
|
||
"created_at": 1748000000
|
||
},
|
||
{
|
||
"uuid": "...",
|
||
"type": "debit",
|
||
"amount": 5000000,
|
||
"source": "settlement",
|
||
"source_id": 7,
|
||
"description": "تسویه #7",
|
||
"created_at": 1747000000
|
||
}
|
||
],
|
||
"page": {
|
||
"totalRecords": 48,
|
||
"totalPages": 5,
|
||
"currentPage": 1
|
||
}
|
||
}
|
||
```
|
||
|
||
## نمونه Response — GET /api/v1/settlement/{uuid}
|
||
|
||
```json
|
||
{
|
||
"uuid": "...",
|
||
"representation": { "id": 3, "uuid": "...", "label": "نمایندگی یاسوج" },
|
||
"amount": 5000000,
|
||
"card_number": "6037-9999-1234-5678",
|
||
"bank_name": "ملت",
|
||
"status": "pending",
|
||
"description": "تسویه اسفندماه ۱۴۰۳",
|
||
"admin_note": null,
|
||
"requested_at": 1748000000,
|
||
"resolved_at": null
|
||
}
|
||
```
|
||
|
||
## نکات مهم
|
||
|
||
- **موجودی کافی:** قبل از ثبت درخواست تسویه، موجودی کیف پول نماینده بررسی شود
|
||
- **یک درخواست pending:** نماینده نمیتواند همزمان دو درخواست `pending` داشته باشد
|
||
- **کارت بانکی:** شماره کارت از لیست `bank_account` نماینده باشد (نه کارت دلخواه)
|
||
- **مبلغ حداقل:** حداقل مبلغ تسویه باید تعریف شود (مثلاً ۱۰۰,۰۰۰ ریال)
|
||
- **واریز کمیسیون:** هنگام `payments.status = 'received'` → کمیسیون محاسبه و به wallet واریز شود
|