feat(settlement): add receipt handling and detail view for settlements

2026-06-25 17:34:39 +03:30
parent 71edc772c8
commit 694ee28787
11 changed files with 484 additions and 3 deletions
@@ -258,3 +258,39 @@ Updated settlement object with `status: "rejected"`.
 ## FinancialBreakdown (لاگ مالی)

 علاوه بر تسویه‌حساب دستی، کیف‌پول نماینده به‌صورت خودکار از طریق `CommissionService` هنگام پرداخت موفقِ نوبت/اشتراک شارژ می‌شود (`WalletTransaction` credit). هر واریز یک ردیف `FinancialBreakdown` ثبت می‌کند که تفکیک کامل تراکنش (ناخالص، هزینه پیامک، مالیات، خالص، درصد و سهم پورسانت، سهم سیستم) را نگه می‌دارد. ثبت idempotent است (بر اساس `payment_id`). گزارش‌ها از طریق `GET /api/v1/admin/financial-breakdowns` و `GET /api/v1/admin/financial-summary` در دسترس‌اند — جزئیات در `docs/api/admin.md`.
+
+---
+
+## رسید پرداخت و ثبت پرداخت نهایی (ROLE_ADMIN)
+
+> منطق کیف‌پول: مبلغ هنگام **ثبت درخواست** از کیف‌پول نماینده کسر (reserve/debit) می‌شود؛ **رد** آن را برمی‌گرداند (credit). تأیید و پرداختِ نهایی کیف‌پول را دوباره دست نمی‌زنند (جلوگیری از double-debit).
+
+### POST `/file/upload/clinic_pro/settlement/receipt`
+
+آپلود تصویر رسید پرداخت. بدنه = محتوای خام فایل؛ هدر `Content-Disposition: filename="..."`. **Permission:** `ROLE_ADMIN`
+
+**Response `200`:**
+```json
+{ "success": true, "data": { "uuid": "...", "url": "/uploads/settlements/receipts/2026-06/...", "filename": "...", "filemime": "image/jpeg" } }
+```
+
+### POST `/api/v1/settlement/{uuid}/paid`
+
+ثبت پرداخت نهایی با رسید. فقط روی تسویه‌ی **approved**. وضعیت → `paid` و `receipt` ذخیره می‌شود. کیف‌پول تغییر نمی‌کند. **Permission:** `ROLE_ADMIN`
+
+**Request Body:**
+```json
+{ "receipt": "/uploads/settlements/receipts/2026-06/..." }
+```
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `receipt` | string | ✅ | URL رسیدِ آپلودشده |
+
+**Response `200`:** آبجکت تسویه (شامل `receipt` و `status: "paid"`).
+
+**Errors:**
+| Code | HTTP | Description |
+|------|------|-------------|
+| `ERR_NOT_FOUND_001` | 404 | درخواست یافت نشد |
+| `ERR_VALIDATION_001` | 422 | تسویه approved نیست |
+| `ERR_VALIDATION_002` | 422 | `receipt` خالی (`field: receipt`) |