# Complete Flow: Lead Creation → Assignment → Doctor

This document describes how a **lead** is created, assigned (to hospital and agent), qualified, and then **converted to a patient with a doctor** in the Hospital ERP + CRM app.

---

## 1. Lead creation (3 entry points)

### A. Public form (no login)

| Step | What happens |
|------|----------------------|
| **URL** | Public route, e.g. `/leads/public` or similar |
| **Controller** | `LeadController::publicForm()` → `LeadController::storePublic()` |
| **Data** | Name, phone, email, enquiry_type, source, notes |
| **Result** | Lead created with: `hospital_id = null`, `agent_id = null`, `status = 'New'` |
| **Next** | Lead must be **assigned to a hospital** and optionally **to a CRM agent** by staff |

### B. CRM agent creates lead (logged in as CRM Agent)

| Step | What happens |
|------|----------------------|
| **URL** | `GET /crm/leads/create` → `LeadController::crmCreate()` |
| **Form** | `resources/views/crm/leads/create.blade.php` (no hospital/agent dropdown) |
| **Submit** | `POST /crm/leads` → `LeadController::crmStore()` |
| **Result** | Lead created with: `hospital_id = current user's hospital`, `agent_id = current user's id`, `status = 'New'` |
| **Next** | Lead is already assigned to **hospital** and **agent** (the CRM agent who created it) |

### C. Super Admin / Hospital Admin creates lead (general create)

| Step | What happens |
|------|----------------------|
| **URL** | `GET /leads/create` → `LeadController::create()` |
| **Form** | `resources/views/leads/create.blade.php` — has **Assign to Agent** dropdown; Super Admin also chooses **Hospital** |
| **Submit** | `POST /leads` → `LeadController::store()` |
| **Result** | Lead created with: `hospital_id` from form (or current user’s hospital for non–Super Admin), `agent_id` from “Assign to Agent” (optional), `status = 'New'` |
| **Next** | Lead may need **hospital/agent assignment** via Edit if not set at creation |

---

## 2. Lead assignment (hospital and agent)

Assignments can be done from the **Edit Lead** page or via bulk actions.

### Assign to hospital

| Who can do it | How |
|----------------|-----|
| Super Admin / CRM Agent | Edit Lead → **Assign to Hospital** dropdown → Save, or `POST /leads/{lead}/assign-hospital` |
| Hospital Admin | Can only assign to their own hospital |
| **Effect** | `lead.hospital_id` set; status can be set to `Contacted` |

- **Bulk:** `POST /leads/bulk-assign-hospital` with `lead_ids[]` and `hospital_id` (only leads with `hospital_id = null` are updated).

### Assign to agent (CRM agent)

| Who can do it | How |
|----------------|-----|
| Super Admin / CRM Agent / Hospital Admin | Edit Lead → **Assign to Agent** dropdown (lists CRM agents for the lead’s hospital or current context) → Save, or `POST /leads/{lead}/assign-agent` |
| **Effect** | `lead.agent_id` set; status can be set to `Contacted` |

- **Bulk:** `POST /leads/bulk-assign-agents` with `lead_ids[]` and `assignments[]` (agent user ids).

**Important:** The **Assign to Agent** dropdown is filled from the **lead’s hospital** (or, for CRM agent, from their hospital if the lead has no hospital). So the lead must have a hospital (or the CRM agent must have a hospital) for the list to show agents. See `LeadController::edit()` and API `GET /api/hospitals/{hospital}/agents`.

---

## 3. Lead status flow (before conversion)

Allowed statuses (see `Lead::getStatuses()`):

1. **New** — initial state after creation  
2. **Contacted** — after contact / assignment  
3. **Qualified** — ready to convert to patient  
4. **Closed – Lost** — not interested  
5. **Converted** — already converted to patient (set by system)

Typical progression:

```
New → Contacted (after assignment / first contact)
Contacted → Qualified   (lead is interested)
Contacted → Closed – Lost (lead is not interested)
Qualified → Converted    (after conversion to patient)
```

Status is updated:

- On **Edit Lead** (Status dropdown) — `PUT /leads/{lead}` (or hospital/crm variant).
- When **assigning to hospital or agent** — can set status to `Contacted`.
- When **converting to patient** — system sets status to `Converted`.

**Business rule:** Only a lead with status **Qualified** can be converted to a patient.

---

## 4. Convert lead to patient (where the doctor is assigned)

The **doctor is not assigned to the lead**; the doctor is chosen **when converting the lead to a patient**. The new patient record gets a `doctor_id`.

### Step 1: Open convert page

| Step | What happens |
|------|----------------------|
| **Who** | User with permission to convert (e.g. CRM Agent, Hospital Admin, Super Admin) |
| **URL** | `GET /leads/{lead}/convert` (or `/crm/leads/{lead}/convert`, `/hospital/leads/{lead}/convert`) |
| **Controller** | `LeadController::convertToPatient($lead)` |
| **Checks** | Lead status must be **Qualified**; lead must not already be converted; for CRM Agent, lead must be from their hospital (or have no hospital so agent’s hospital is used) |
| **Data** | Doctors for the lead’s hospital (or CRM agent’s hospital if lead has no hospital) are loaded |
| **View** | `resources/views/leads/convert.blade.php` — shows lead details and **Convert to Patient** form |

### Step 2: Submit conversion form

| Step | What happens |
|------|----------------------|
| **URL** | `POST /leads/{lead}/convert` (or crm/hospital variant) |
| **Controller** | `LeadController::convert($request, $lead)` |
| **Validated input** | `age`, `gender`, `address`, `medical_history`, `allergies`, **`doctor_id`** (required) |
| **Logic** | In a DB transaction: 1) If lead has no hospital, set `lead.hospital_id` to the hospital used for conversion (lead’s or CRM agent’s). 2) Create **Patient** with `hospital_id`, `doctor_id`, name, phone, email, age, gender, address, medical_history, allergies. 3) Create **LeadPatientMapping** (lead_id, patient_id, conversion_date, converted_by). 4) Update lead: `status = 'Converted'`, `converted_at = now()`. |
| **Result** | New **patient** with **doctor_id** set; lead marked **Converted**; redirect to patient show page |

So:

- **Doctor assignment** = choosing **Assign Doctor** on the **Convert Lead to Patient** form (`doctor_id` in the form).
- That `doctor_id` is stored on the **Patient** (`patients.doctor_id`), not on the lead.

---

## 5. End-to-end flow summary (creation → doctor)

```
1. CREATE LEAD
   • Public form        → lead (no hospital, no agent) — OR —
   • CRM create         → lead (hospital + agent = current user) — OR —
   • Staff create       → lead (hospital + optional agent from dropdown)

2. ASSIGN (if needed)
   • Edit Lead → Assign to Hospital → Save
   • Edit Lead → Assign to Agent   → Save
   (Status can become Contacted here.)

3. QUALIFY
   • Edit Lead → Status: New → Contacted → Qualified (or Closed – Lost)

4. CONVERT TO PATIENT (only if Qualified)
   • Lead show → “Convert to Patient”
   • Convert page: fill Age, Gender, Address, Medical history, Allergies
   • Choose “Assign Doctor” (doctor_id) from dropdown (doctors of lead’s/agent’s hospital)
   • Submit → Patient created with doctor_id; lead status = Converted

5. AFTER CONVERSION
   • Patient record has doctor_id (the chosen doctor).
   • Appointments for this patient are booked with a doctor (can be same or different).
   • Billing is per visit/appointment.
```

---

## 6. Important code references

| Action | Controller method | Route name (example) |
|--------|-------------------|----------------------|
| Public lead form | `LeadController::publicForm` | (public) |
| Public lead submit | `LeadController::storePublic` | (public) |
| CRM create lead form | `LeadController::crmCreate` | `crm.leads.create` |
| CRM create lead submit | `LeadController::crmStore` | `crm.leads.store` |
| General create form | `LeadController::create` | `leads.create` |
| General create submit | `LeadController::store` | (POST to leads) |
| Edit lead (hospital + agent) | `LeadController::edit` | `leads.edit` / `crm.leads.edit` / `hospital.leads.edit` |
| Update lead | `LeadController::update` | `leads.update` / etc. |
| Assign to hospital | `LeadController::assignToHospital` | `leads.assign.hospital` |
| Assign to agent | `LeadController::assignToAgent` | `leads.assign.agent` |
| Convert form (choose doctor) | `LeadController::convertToPatient` | `leads.convertToPatient` / `crm.leads.convertToPatient` |
| Convert submit (create patient with doctor) | `LeadController::convert` | `leads.convert` / `crm.leads.convert` |
| API: agents by hospital | Closure in `routes/web.php` | `GET /api/hospitals/{hospital}/agents` |

---

## 7. Clarification: “Assign to Doctor”

- **Leads** are not “assigned to a doctor.” Leads have `hospital_id` and `agent_id` (CRM agent).
- The **doctor** is selected at **Convert to Patient** time and stored on the **Patient** as `doctor_id`.
- So: **Lead → (assign to hospital & agent) → qualify → Convert to Patient (choose doctor) → Patient with doctor_id.**

If you need a separate “assign lead to doctor” (e.g. for scheduling an appointment before conversion), that would be a new feature (e.g. an appointment or “preferred doctor” field on the lead); currently the only doctor assignment is via the convert form’s **Assign Doctor** dropdown.
