# تسک ۱۸: ماژول تسویه نماینده (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 واریز شود