# How the Billing Portal Works After the Doctor Completes the Process

This document describes the flow from **doctor completing a visit** to **billing** in the Hospital ERP + CRM app.

---

## 1. Doctor side: completing the visit

1. **Appointment is created** (e.g. from Patients → Book Appointment) with status **Scheduled**.
2. **Doctor (or staff) marks the appointment as Completed**:
   - Go to **Appointments** (e.g. `/doctor/appointments` or `/appointments`).
   - Open the appointment.
   - Use the **Complete** / **Mark as Completed** action.
3. **Result:** The appointment’s status is set to **Completed**. The system does **not** create an invoice automatically.

So: **Doctor “completing” = appointment status becomes “Completed”.** Billing starts only when someone creates an invoice.

---

## 2. Billing side: when the doctor process is “complete”

After the appointment is **Completed**, the **Billing Executive** (billing agent) uses the **Billing Portal** to create and manage invoices.

### Step 1: Log in as Billing Executive

- Login → role **Billing Executive** → redirect to **Billing Dashboard** (`/billing/dashboard`).

### Step 2: Billing Dashboard

- **URL:** `/billing/dashboard`
- **Shows:**  
  - Total / paid / pending / overdue invoices  
  - Total revenue, pending amount  
  - Monthly and yearly revenue  
  - Recent invoices  
  - Overdue invoices  
  - Revenue chart (e.g. last 12 months)  
- **Sidebar:** Billing Dashboard, Invoices, New Invoice, Reports, Settings, Logout (no Appointments link).

### Step 3: Create an invoice for a completed visit

- **Go to:** **New Invoice** (sidebar) → `/billing/invoices/create`.
- **Backend rule (BR-28):** Invoices can be created only for **completed** visits.
- **In the form you:**
  1. Select **Patient** (required).
  2. Optionally select **Appointment** (if the system supports it on the create form).  
     - If an **appointment** is linked:
       - **BR-34:** Cancelled or No-show appointments **cannot** be billed (validation error).
       - **BR-28:** Only **Completed** appointments can be billed (validation error if status ≠ Completed).
  3. Add **services** (name, quantity, price), subtotal, tax, total, due date, notes.
  4. Submit.

- **Result:** A new **Invoice** is created with status **Pending**, linked to the patient (and optionally to the completed appointment).

So **after the doctor process is complete**, the billing agent **explicitly creates** an invoice from “New Invoice” and can link it to the **completed** appointment when the create flow supports it.

### Step 4: Invoice list and details

- **Invoices** (sidebar) → `/billing/invoices`  
  - List of all invoices (filter by status, date, search).
- Open an invoice → **Invoice detail** (`/billing/invoices/{id}`):  
  - Patient, appointment (if any), services, amounts, status (Pending / Paid / Overdue / Cancelled).

### Step 5: Record payment

- On the **invoice detail** page (or via **Record Payment**):
  - **Route:** `POST /billing/invoices/{invoice}/payment`
  - Enter **payment mode** and optional **payment notes**.
- **Result:** Invoice status is set to **Paid**, `paid_date` and payment info are stored.

### Step 6: Reports

- **Reports** (sidebar) → `/billing/reports`  
  - Billing/revenue reports (e.g. by period, status) for the same hospital.

---

## 3. End-to-end flow (doctor complete → billing)

```
1. Patient has an appointment (status: Scheduled).
2. Doctor (or staff) marks appointment as Completed.
   → Appointment status = Completed.
3. Billing Executive logs in → Billing Dashboard.
4. Billing Executive goes to New Invoice.
5. Selects Patient (and optionally the completed Appointment, if the form allows).
6. Adds services, amounts, due date → Creates invoice (status: Pending).
7. When patient pays → Record Payment on that invoice.
8. Invoice status → Paid; revenue appears in dashboard and reports.
```

---

## 4. Important business rules (from code)

| Rule   | Meaning |
|--------|--------|
| **BR-28** | Billing can be created only for **completed** visits. If an appointment is linked, it must be **Completed**. |
| **BR-34** | Cancelled or No-show appointments **cannot** generate bills. |
| **BR-33** | A completed/paid bill cannot be edited without admin rights (invoice `canEdit()`). |

---

## 5. Billing portal quick reference (Billing Executive)

| Action           | Where                          | Route / URL (under billing)   |
|-----------------|---------------------------------|---------------------------------|
| Dashboard       | Sidebar → Billing Dashboard     | `GET /billing/dashboard`        |
| List invoices   | Sidebar → Invoices              | `GET /billing/invoices`         |
| Create invoice  | Sidebar → New Invoice           | `GET /billing/invoices/create` |
| View invoice    | From list or after create        | `GET /billing/invoices/{id}`    |
| Record payment  | On invoice detail               | `POST /billing/invoices/{id}/payment` |
| Reports         | Sidebar → Reports               | `GET /billing/reports`          |

---

## 6. Note on “Create Invoice” form

The current **Create Invoice** view may still be a simplified form (e.g. only patient, amount, due date). The **InvoiceController::store()** expects:

- `patient_id`, optional `appointment_id`, optional `consultation_id`
- `services` (array: name, quantity, price, etc.)
- `subtotal`, `tax_rate`, `tax_amount`, `total_amount`, `due_date`, `notes`

If the create form does not send these, the submit may fail or show “Coming soon”. To fully use the billing flow **after the doctor process**, the **New Invoice** page should be updated to:

1. Load patients (and optionally **completed** appointments for the selected patient).
2. Allow selecting a **completed** appointment to link to the invoice.
3. Collect service lines and totals as required by `InvoiceController::store()`.

Once that form matches the controller, the flow above (doctor complete → billing agent creates invoice → record payment → reports) works as described.
