Leads App
=========

**Purpose**: Manage the intake, tracking, and document collection for EV charger installation leads from OEMs.

Responsibilities
----------------

- Lead creation (via OEM API integration or manual entry by Central Ops)
- Source tagging — track which OEM and which channel the lead came from
- Customer document collection — electricity bill, location photos, electrician contact
- Lead status lifecycle tracking (``new`` through ``closed``)
- Introductory call tracking
- Bulk lead import (CSV)
- Lead assignment to Central Ops handlers

Dependencies
------------

- **accounts** — User model (OEM submitter, Central Ops handler, customer)

Key Models
----------

- **Lead** — Core entity representing an installation request. Tracks customer details, location, status, assigned handler, and charger model.
- **LeadSource** — Categorizes where leads originate (e.g., "Tata Motors Portal", "MG Direct API"). Linked to a specific OEM.
- **LeadDocument** — Files uploaded for a lead: electricity bills, location photos, electrician contact details.

Status Lifecycle
----------------

.. code-block:: text

   new → contacted → documents_pending → documents_received →
   survey_scheduled → survey_completed →
   installation_scheduled → installation_completed → closed

   Any state → cancelled
   Any state → on_hold

Business Rules
--------------

- OEMs can only view their own leads.
- Central Ops can view and manage all leads.
- A lead must have at least an electricity bill document before it can move to ``documents_received``.
- Status transitions are validated — you cannot skip from ``new`` to ``survey_scheduled``.
- Lead assignment to a Central Ops handler is required before scheduling a survey.