Surveys App
===========

**Purpose**: Manage survey scheduling, field team assignment, survey execution, report submission, and post-survey review.

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

- Create surveys from leads that have received customer documents
- Generate human-readable Survey IDs (e.g., ``SRV-2026-00123``)
- Schedule survey date and time slot
- Assign field teams to surveys
- Track survey day confirmation calls
- Capture survey reports (site readiness, electrical assessment, civil work needs)
- Capture survey media (photos, videos)
- Post-survey review workflow (Central Ops approves or rejects)

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

- **leads** — Survey is linked to a Lead (OneToOne)
- **accounts** — Field team assignment, Central Ops reviewer
- **emergency** — Triggered when assigned team is unavailable
- **notifications** — Confirmation call and reminder triggers

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

- **Survey** — Scheduled survey linked to a lead. Tracks date, time slot, status, and customer confirmation.
- **SurveyAssignment** — Links a survey to a field team. Supports primary and emergency backup assignments.
- **SurveyReport** — Detailed site assessment: load adequacy, earthing, civil work needs. Includes review status from Central Ops.
- **SurveyMedia** — Photos and videos captured during the survey.

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

.. code-block:: text

   scheduled → confirmed → in_progress → completed →
   report_submitted → reviewed_approved
                    → reviewed_rejected → (back to scheduled as reschedule)

   Any state → rescheduled
   Any state → cancelled

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

- Only one active survey per lead at a time.
- A survey cannot proceed to ``in_progress`` without customer confirmation.
- Survey report must include site readiness assessment (load, earthing, civil work).
- Central Ops must review every report — auto-approval is not supported.
- If a report is rejected, a new survey may be scheduled.
- Media upload is required — at least 3 photos per survey report.