feat: Implement SMS sending functionality with KavehNegar and Rangineh providers

- 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.
2026-06-09 22:00:34 +03:30
commit de1a78a235
222 changed files with 36388 additions and 0 deletions
@@ -0,0 +1,117 @@
+# تسک ۱۸: ماژول تسویه نماینده (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 واریز شود