# How the Patient Is Handled (After Lead Conversion)

After a lead is converted to a patient, the **patient** is the main record. This document describes who can do what and the main workflows.

---

## Who Can Access Patients

| Role | Access | Notes |
|------|--------|------|
| **Super Admin** | Full (all hospitals) | See all patients, create, edit, delete, book appointments, billing, medical history |
| **Hospital Admin** | Full (own hospital) | Same actions, limited to their hospital’s patients |
| **Doctor** | Full (own hospital) | Same, for their hospital; often via Doctor dashboard |
| **Billing Executive** | Full (own hospital) | Same, for their hospital; focus on billing |
| **CRM Agent** | View & list (own hospital) | After conversion, can open patient and patient list for their hospital |

Patients are filtered by **hospital**: non–Super Admin users see only patients for their `hospital_id`. CRM agents now have access so they can open the patient page after converting a lead.

---

## 1. Patient List

- **Route:** `GET /patients` (or `/hospital/patients`, `/doctor/patients` by role)
- **View:** `patients.index`
- **Actions:** Search/filter by name, phone, email, gender, age. Open patient, Book Appointment, Billing History.

---

## 2. Patient Detail (Show)

- **Route:** `GET /patients/{patient}`
- **View:** `patients.show`
- **Shows:**
  - Demographics: name, age, gender, phone, email, address
  - Hospital, link to original lead (if converted from lead)
  - Medical history, allergies
  - **Upcoming appointments** (scheduled, future)
  - **Recent invoices** (last 5)
- **Typical next actions (by role):** Edit Patient, Book Appointment, Medical History, Billing History (and Delete if allowed).

---

## 3. Edit Patient

- **Route:** `GET /patients/{patient}/edit`, `PUT /patients/{patient}`
- **Use:** Update name, age, gender, phone, email, address, medical history, allergies.
- **Rule:** Duplicate phone number for the same hospital is blocked (except for the current patient).

---

## 4. Book Appointment

- **Route:** `GET /patients/{patient}/book-appointment`, `POST /patients/{patient}/book-appointment`
- **Use:** Choose **doctor**, **date**, **time slot**, optional notes/symptoms. Creates an appointment with status **Scheduled**.
- **Rule:** Same doctor + date + time cannot be double-booked.
- **After submit:** Redirect to **Appointment detail** (`appointments.show`). From there, appointment can be marked Completed / No-show / Cancelled; completed visits can be billed.

---

## 5. Medical History

- **Route:** `GET /patients/{patient}/medical-history`
- **View:** `patients.medical-history`
- **Use:** See appointments and invoices for this patient (visits over time).

---

## 6. Billing History

- **Route:** `GET /patients/{patient}/billing-history`
- **View:** `patients.billing-history`
- **Use:** List invoices for the patient, totals, paid vs pending. Link to invoice detail and to record payment (for Billing Executive / allowed roles).

Invoices are created from the **Invoices** module (e.g. for a completed visit/appointment), not from the patient screen itself. Billing flow: **Appointment completed** → Create invoice (linked to patient/visit) → Record payments here or from invoice list.

---

## 7. Delete Patient

- **Route:** `DELETE /patients/{patient}`
- **Rule:** Not allowed if the patient has any **appointments** or **invoices** (must be no visits/bills).

---

## End-to-End Flow (After Conversion)

```
Lead converted to Patient
    ↓
Patient record exists (hospital_id, doctor_id from conversion)
    ↓
Staff opens Patients → select patient (or land on patient page after conversion)
    ↓
From patient: Book Appointment → choose doctor, date, time → Appointment created
    ↓
After visit: update Appointment to Completed (from Appointments module)
    ↓
Billing: create Invoice for that visit (Invoices module), link to patient/appointment
    ↓
Record payment on invoice → Patient’s Billing History reflects it
```

So the patient is handled by: **viewing/editing the record**, **booking and managing appointments**, and **viewing/recording billing** via invoices linked to the patient.

---

## Quick Reference – Patient Routes

| Action | Method | Route |
|--------|--------|--------|
| List patients | GET | `/patients` |
| View patient | GET | `/patients/{patient}` |
| Edit patient | GET/PUT | `/patients/{patient}/edit`, `PUT /patients/{patient}` |
| Book appointment | GET/POST | `/patients/{patient}/book-appointment` |
| Medical history | GET | `/patients/{patient}/medical-history` |
| Billing history | GET | `/patients/{patient}/billing-history` |
| Delete patient | DELETE | `/patients/{patient}` |

Hospital Admin and Doctor may use the same routes under `/hospital/` or `/doctor/` prefix; behavior is the same, with hospital scoping applied in the controller.
