hamedandClaude Opus 4.8
89191eee57
Multi-tenant insurance contracts, service coverage, versioned tariffs, invoice calculation, and insurance claims with debt reporting. - TenantInsurance: per-tenant insurance contracts (coverage/franchise/ceiling, versioning, soft-deactivate) + active guard - ServiceItem.insuranceCovered + TenantServiceCoverage per-service overrides - Tariff: versioned yearly tariffs with fallback to ServiceItem price - Billing domain: Money/ShareBreakdown VOs, BillingCalculator (unit-tested), Invoice/InvoiceItem aggregate, InvoiceService.createFromSession - Claim/ClaimItem with state machine (pending->submitted->approved/rejected->paid), ClaimService, insurance-debt report - ClaimSubmitterInterface + ManualClaimSubmitter (future insurance API ready) - Admin UI: insurance-pricing page, claims page, service tariff modal, service insurance toggle; routes + sidebar entries - Architecture doc + billing/insurance/clinic-services API docs Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
144 lines
5.9 KiB
Markdown
144 lines
5.9 KiB
Markdown
# Billing API — صورتحساب (فاز ۴ سیستم صورتحساب/بیمه)
|
|
|
|
> **Prefix:** `/api/v1/billing`
|
|
> دامنه: `App\Billing`. مرجع معماری: `docs/architecture/insurance-billing-system.md`.
|
|
> tenant از `#[CurrentUser]` resolve میشود (`ROLE_DOCTOR`→doctor، `ROLE_CLINIC`→clinic).
|
|
|
|
صورتحساب (`Invoice`) از یک Encounter (`PatientSession`) ساخته میشود. برای هر آیتم سهم بیمهی پایه، بیمهی مکمل و بیمار با `BillingCalculator` محاسبه میشود:
|
|
|
|
- تعرفهی خدمت از `Tariff` سال جاری (با fallback به `ServiceItem.priceRials`).
|
|
- قانون پوشش از قرارداد بیمهی tenant (`TenantInsurance`) + override خدمت (`TenantServiceCoverage`).
|
|
- ترتیب محاسبه: کل → پوشش پایه (با سقف) → باقیمانده → پوشش مکمل → فرانشیز سهم بیمار.
|
|
|
|
نمونه: کل ۶۰۰٬۰۰۰ · پایه ۷۰٪ → ۴۲۰٬۰۰۰ · مکمل روی باقیمانده → ۱۲۰٬۰۰۰ · بیمار ۶۰٬۰۰۰.
|
|
|
|
---
|
|
|
|
## POST /api/v1/billing/invoices
|
|
|
|
ساخت صورتحساب از یک مراجعه. اگر صورتحساب برای آن مراجعه قبلاً ساخته شده، همان برگردانده میشود (idempotent).
|
|
|
|
**Permission:** `AUTH` (مالک مراجعه)
|
|
|
|
**Body:**
|
|
```json
|
|
{ "session_uuid": "…" }
|
|
```
|
|
|
|
**Response 201:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"data": {
|
|
"uuid": "…",
|
|
"entity_type": "doctor",
|
|
"entity_id": 7,
|
|
"patient_session_id": 33,
|
|
"base_insurance_id": 3,
|
|
"supplementary_insurance_id": 9,
|
|
"total_rials": 600000,
|
|
"base_insurance_rials": 420000,
|
|
"supplementary_rials": 120000,
|
|
"patient_rials": 60000,
|
|
"status": "draft",
|
|
"issued_at": 1718900000,
|
|
"items": [
|
|
{
|
|
"uuid": "…",
|
|
"service_item_id": 12,
|
|
"title": "ویزیت",
|
|
"tariff_rials": 600000,
|
|
"quantity": 1,
|
|
"total_rials": 600000,
|
|
"base_insurance_rials": 420000,
|
|
"supplementary_rials": 120000,
|
|
"patient_rials": 60000
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Errors:** `422 ERR_VALIDATION_001` session_uuid الزامی · `404 ERR_NOT_FOUND_001` مراجعه یافت نشد · `403 ERR_FORBIDDEN_001` پروفایل یافت نشد.
|
|
|
|
---
|
|
|
|
## GET /api/v1/billing/invoices/{uuid}
|
|
|
|
دریافت صورتحساب (فقط مالک tenant).
|
|
|
|
**Response 200:** همان ساختار بالا.
|
|
**Errors:** `404 ERR_NOT_FOUND_001`.
|
|
|
|
---
|
|
|
|
## POST /api/v1/billing/invoices/{uuid}/finalize
|
|
|
|
نهاییسازی صورتحساب (`draft` → `finalized`). صورتحساب نهاییشده مبنای ساخت Claim (فاز ۵) است.
|
|
|
|
**Response 200:** صورتحساب با `status: "finalized"`.
|
|
**Errors:** `404 ERR_NOT_FOUND_001`.
|
|
|
|
---
|
|
|
|
## وضعیتهای Invoice
|
|
`draft` (پیشنویس، قابل بازسازی) → `finalized` (نهایی) → `paid` (پرداختشده) · `void` (باطل).
|
|
|
|
## نکات
|
|
- پول: integer ریال. تاریخ: Unix timestamp.
|
|
- `BillingCalculator` خالص و واحد-تستشده است (`tests/Billing/BillingCalculatorTest.php`).
|
|
- این فاز جایگزین تدریجی `PatientService::calculateFinalPrice` است؛ آن متد فعلاً برای سازگاری باقی مانده.
|
|
|
|
---
|
|
|
|
# Claims — مطالبات بیمه (فاز ۵)
|
|
|
|
مطالبه (`Claim`) از یک صورتحساب **نهاییشده** ساخته میشود: یک Claim برای بیمهی پایه و یک Claim برای بیمهی مکمل (فقط اگر سهم بیمه > ۰). هر `ClaimItem` به یک `InvoiceItem` ارجاع میدهد. چرخهی وضعیت با state machine.
|
|
|
|
**وضعیتها:** `pending → submitted → {approved → paid | rejected}`. از `paid`/`rejected` خروجی ندارد.
|
|
|
|
## POST /api/v1/billing/claims
|
|
ساخت مطالبات از یک صورتحساب نهاییشده.
|
|
|
|
**Body:** `{ "invoice_uuid": "…" }`
|
|
**Response 201:** `{ success, data: [ …claims ] }` (یک یا دو مطالبه: پایه/مکمل).
|
|
**Errors:** `422` صورتحساب نهایی نشده / سهم بیمه ندارد · `404` صورتحساب یافت نشد.
|
|
|
|
## GET /api/v1/billing/claims?status=
|
|
لیست مطالبات tenant. فیلتر اختیاری `status` (`pending|submitted|approved|rejected|paid`).
|
|
|
|
## POST /api/v1/billing/claims/{uuid}/{action}
|
|
انتقال وضعیت. `action` ∈ `submit|approve|reject|pay`.
|
|
|
|
| action | body اختیاری | اثر |
|
|
|--------|--------------|-----|
|
|
| submit | — | pending → submitted |
|
|
| approve | `approved_rials` | submitted → approved (پیشفرض = کل ادعا) |
|
|
| reject | `reason` (الزامی) | submitted → rejected |
|
|
| pay | `paid_rials` | approved → paid (پیشفرض = approved) |
|
|
|
|
**Errors:** `422` انتقال نامعتبر یا دلیل رد خالی · `404` مطالبه یافت نشد.
|
|
|
|
## GET /api/v1/billing/reports/insurance-debt
|
|
گزارش بدهی بیمهها برای tenant (group بر اساس بیمه).
|
|
|
|
**Response 200:**
|
|
```json
|
|
{
|
|
"success": true,
|
|
"data": {
|
|
"data": [
|
|
{ "insurance_id": 3, "claimed": 840000, "approved": 800000, "paid": 500000, "debt": 340000 }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
`debt = claimed - paid` (حداقل صفر).
|
|
|
|
---
|
|
|
|
## ارسال مطالبه (ClaimSubmitter)
|
|
|
|
عملِ `submit` از طریق interface `App\Billing\Contract\ClaimSubmitterInterface` انجام میشود. پیادهسازی پیشفرض `ManualClaimSubmitter` است (ارسال دستی/آفلاین — همیشه موفق). برای اتصال آینده به API شرکتهای بیمهی ایران کافی است یک پیادهسازی جدید از این interface ساخته و در `config/services.yaml` bind شود؛ `ClaimService` تغییر نمیکند (Dependency Inversion). اگر `submit` ناموفق باشد، انتقال وضعیت با `422` متوقف میشود. |