# تسک ۱۵: پرونده بیمار (Patient Records)

## توضیح
پیاده‌سازی سیستم پرونده الکترونیک بیمار. هر بیمار یک پرونده در هر کلینیک/مطب دارد.
هر مراجعه یک سشن است که شامل اطلاعات بیمه، مبلغ ویزیت و سرویس‌های انجام‌شده است.
دسترسی فقط در پنل **Basic+** — gate: `hasFeature('patient_records')`.

## Endpoint ها

| متد | مسیر | Gate | توضیح |
|-----|------|------|-------|
| GET | `/api/v1/patients` | Basic+ | لیست بیماران — `?search=name/phone` |
| POST | `/api/v1/patient` | Basic+ | ایجاد پرونده دستی |
| GET | `/api/v1/patient/{uuid}` | Basic+ | جزئیات پرونده |
| GET | `/api/v1/patient/{uuid}/sessions` | Basic+ | لیست مراجعات |
| POST | `/api/v1/patient/{uuid}/session` | Basic+ | ثبت مراجعه جدید |
| PATCH | `/api/v1/session/{uuid}` | Basic+ | ویرایش مراجعه |

## پیش‌نیازها
- **تسک ۱۰** (ClinicStaff — برای staff_id در SessionService)
- **تسک ۱۱** (Subscription — gate check)
- **تسک ۱۳** (ClinicService — ServiceItem در session)

## زمان تخمینی
۱۶ تا ۲۰ ساعت

## نمونه Request

### POST /api/v1/patient (ایجاد دستی)
```json
{
  "user_uuid": "uuid-of-user"
}
```

### POST /api/v1/patient/{uuid}/session
```json
{
  "appointment_uuid": null,
  "insurance_base_uuid": "category-uuid-insurance-type",
  "insurance_supplementary_uuid": null,
  "visit_price_rials": 500000,
  "base_insurance_discount_percent": 30,
  "supplementary_discount_percent": 0,
  "payment_method": "cash",
  "notes": "بیمار شکایت از کمردرد داشت",
  "services": [
    { "service_item_uuid": "uuid-of-service-item", "staff_uuid": "uuid-of-staff" },
    { "service_item_uuid": "uuid-of-another-item", "staff_uuid": null }
  ]
}
```

### PATCH /api/v1/session/{uuid}
```json
{
  "notes": "ویرایش یادداشت",
  "payment_method": "card"
}
```

## فرمول محاسبه final_price

```
after_base    = visit_price_rials × (1 - base_insurance_discount_percent / 100)
after_supp    = after_base × (1 - supplementary_discount_percent / 100)
services_total = Σ service_item.price_rials (قیمت در زمان ثبت — نه قیمت فعلی)
final_price   = round(after_supp) + services_total
```

مثال عددی:
```
visit_price  = 500,000
base_disc    = 30% → after_base = 350,000
supp_disc    = 10% → after_supp = 315,000
services     = [85,000 + 45,000] = 130,000
final        = 315,000 + 130,000 = 445,000
```

## نمونه Response

### GET /api/v1/patients?search=علی
```json
{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "user": { "uuid": "...", "name": "علی محمدی", "phone": "09121234567" },
      "sessions_count": 5,
      "last_session_at": 1718000000,
      "created_at": 1710000000
    }
  ],
  "meta": { "totalRecords": 12, "totalPages": 2, "currentPage": 1 }
}
```

### GET /api/v1/patient/{uuid}
```json
{
  "success": true,
  "data": {
    "uuid": "...",
    "user": { "uuid": "...", "name": "علی محمدی", "phone": "09121234567" },
    "sessions_count": 5,
    "total_paid_rials": 2250000,
    "created_at": 1710000000
  }
}
```

### GET /api/v1/patient/{uuid}/sessions
```json
{
  "success": true,
  "data": [
    {
      "uuid": "...",
      "appointment_uuid": null,
      "visit_price_rials": 500000,
      "base_insurance_discount_percent": 30,
      "services_total_rials": 130000,
      "final_price_rials": 445000,
      "payment_method": "cash",
      "notes": "...",
      "services": [
        { "name": "سرم ۵۰۰cc", "price_rials": 85000, "staff_name": "علی رضایی" }
      ],
      "created_at": 1718000000
    }
  ],
  "meta": { "totalRecords": 5, "totalPages": 1, "currentPage": 1 }
}
```

## ایجاد خودکار پرونده هنگام تأیید نوبت

```
AppointmentController::updateStatus(uuid, 'confirmed')
  → اگر entityType/entityId پنل Basic+ دارد:
    → PatientService::autoCreateOnAppointmentConfirm(appointment)
      → PatientRecord.findOrCreate(entityType, entityId, userId)
      → PatientSession جدید با appointment_id و visit_price پیش‌فرض (0)
      → کاربر بعداً در پرونده می‌تواند اطلاعات بیمه و قیمت را تکمیل کند
```

## کدهای خطا

| کد | HTTP | توضیح |
|----|------|-------|
| `ERR_SUBSCRIPTION_REQUIRED` | 403 | Basic+ لازم است |
| `ERR_PATIENT_NOT_FOUND` | 404 | پرونده پیدا نشد |
| `ERR_SESSION_NOT_FOUND` | 404 | مراجعه پیدا نشد |
| `ERR_SERVICE_ITEM_NOT_FOUND` | 404 | زیربخش سرویس پیدا نشد |