Leads Models
============

Lead
----

Core entity representing an EV charger installation request. This is the root object that drives the entire workflow — every survey, installation, and closure pack traces back to a lead.

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Field
     - Type
     - Constraints
     - Description
   * - id
     - UUIDField
     - PK, default=uuid4
     - Primary key
   * - oem
     - ForeignKey(User)
     - not null, on_delete=PROTECT, limit_choices_to={role=oem}
     - OEM who shared the lead
   * - customer_name
     - CharField(200)
     - not null
     - Customer full name
   * - customer_phone
     - CharField(15)
     - not null
     - Customer primary phone
   * - customer_email
     - EmailField
     - nullable
     - Customer email (optional)
   * - address_line1
     - CharField(255)
     - not null
     - Installation address line 1
   * - address_line2
     - CharField(255)
     - blank
     - Installation address line 2
   * - city
     - CharField(100)
     - not null
     - City
   * - state
     - CharField(100)
     - not null
     - State
   * - pincode
     - CharField(10)
     - not null
     - Postal code
   * - latitude
     - DecimalField(9,6)
     - nullable
     - GPS latitude for mapping
   * - longitude
     - DecimalField(9,6)
     - nullable
     - GPS longitude for mapping
   * - source
     - ForeignKey(LeadSource)
     - not null, on_delete=PROTECT
     - How the lead was acquired
   * - status
     - CharField(20)
     - choices, default='new'
     - Current lifecycle state
   * - charger_model
     - CharField(100)
     - nullable
     - Requested charger model
   * - assigned_to
     - ForeignKey(User)
     - nullable, on_delete=SET_NULL, limit_choices_to={role=central_ops}
     - Central Ops handler
   * - intro_call_completed
     - BooleanField
     - default=False
     - Whether introductory call was made
   * - created_at
     - DateTimeField
     - auto_now_add
     - Lead creation timestamp
   * - updated_at
     - DateTimeField
     - auto_now
     - Last modification timestamp

**Status choices**: ``new``, ``contacted``, ``documents_pending``, ``documents_received``, ``survey_scheduled``, ``survey_completed``, ``installation_scheduled``, ``installation_completed``, ``closed``, ``cancelled``, ``on_hold``

**Indexes**: ``status``, ``oem``, ``assigned_to``, ``created_at``, ``city``, ``state``

LeadSource
----------

Categorizes the origin of leads for analytics and OEM tracking.

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Field
     - Type
     - Constraints
     - Description
   * - id
     - AutoField
     - PK
     - Primary key
   * - name
     - CharField(100)
     - unique, not null
     - Source name (e.g., "Tata Motors Portal", "MG Direct API")
   * - oem
     - ForeignKey(User)
     - nullable, on_delete=SET_NULL
     - Associated OEM, if applicable
   * - source_type
     - CharField(20)
     - choices: ``api``, ``manual``, ``portal``
     - How leads arrive from this source

LeadDocument
------------

Files uploaded by the customer or Central Ops for a lead.

.. list-table::
   :header-rows: 1
   :widths: 20 20 20 40

   * - Field
     - Type
     - Constraints
     - Description
   * - id
     - UUIDField
     - PK, default=uuid4
     - Primary key
   * - lead
     - ForeignKey(Lead)
     - not null, on_delete=CASCADE
     - Parent lead
   * - document_type
     - CharField(30)
     - choices: ``electricity_bill``, ``location_photo``, ``electrician_contact``, ``other``
     - Document category
   * - file
     - FileField
     - not null, upload_to='lead_documents/'
     - Uploaded file
   * - uploaded_by
     - ForeignKey(User)
     - not null, on_delete=PROTECT
     - Who uploaded the document
   * - uploaded_at
     - DateTimeField
     - auto_now_add
     - Upload timestamp
   * - notes
     - TextField
     - blank
     - Optional notes about the document