Reporting Models
================

ClosurePack
-----------

Bundles all artifacts for a completed installation into a single package for OEM submission.

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

   * - Field
     - Type
     - Constraints
     - Description
   * - id
     - UUIDField
     - PK, default=uuid4
     - Primary key
   * - installation
     - OneToOneField(Installation)
     - not null, on_delete=PROTECT
     - Linked installation
   * - lead
     - ForeignKey(Lead)
     - not null, on_delete=PROTECT
     - Back-reference to lead
   * - survey_report
     - ForeignKey(SurveyReport)
     - not null, on_delete=PROTECT
     - Included survey report
   * - installation_report
     - ForeignKey(InstallationReport)
     - not null, on_delete=PROTECT
     - Included installation report
   * - compiled_by
     - ForeignKey(User)
     - not null, on_delete=PROTECT
     - OEM Reporting staff who compiled
   * - confirmation_call_completed
     - BooleanField
     - default=False
     - Post-installation confirmation call done
   * - status
     - CharField(20)
     - choices: ``draft``, ``compiled``, ``submitted``, ``accepted``, ``rejected``
     - Pack lifecycle state
   * - submitted_to_oem_at
     - DateTimeField
     - nullable
     - When submitted to OEM
   * - oem_response
     - CharField(20)
     - choices: ``pending``, ``accepted``, ``revision_needed``, default='pending'
     - OEM feedback status
   * - created_at
     - DateTimeField
     - auto_now_add
     - Creation timestamp

WeeklyReport
------------

Aggregate report for a specific OEM covering one week.

.. 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
     - Target OEM
   * - week_start
     - DateField
     - not null
     - Report period start (Monday)
   * - week_end
     - DateField
     - not null
     - Report period end (Sunday)
   * - total_leads
     - IntegerField
     - not null
     - Leads received in period
   * - surveys_completed
     - IntegerField
     - not null
     - Surveys completed in period
   * - installations_completed
     - IntegerField
     - not null
     - Installations completed in period
   * - closure_packs_submitted
     - IntegerField
     - not null
     - Closure packs submitted in period
   * - report_file
     - FileField
     - nullable, upload_to='reports/weekly/'
     - Generated report file (PDF)
   * - submitted_at
     - DateTimeField
     - nullable
     - When submitted to OEM
   * - created_at
     - DateTimeField
     - auto_now_add
     - Generation timestamp

**Unique constraint**: ``(oem, week_start)``

MonthlyReport
-------------

Extended monthly aggregate with financial and performance metrics.

.. 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
     - Target OEM
   * - month
     - DateField
     - not null
     - First day of the report month
   * - total_leads
     - IntegerField
     - not null
     - Leads received in month
   * - surveys_completed
     - IntegerField
     - not null
     - Surveys completed
   * - installations_completed
     - IntegerField
     - not null
     - Installations completed
   * - closure_packs_submitted
     - IntegerField
     - not null
     - Closure packs submitted
   * - total_revenue
     - DecimalField(12,2)
     - nullable
     - Total revenue for the month
   * - average_installation_time_days
     - DecimalField(5,1)
     - nullable
     - Avg days from lead to installation
   * - sla_compliance_rate
     - DecimalField(5,2)
     - nullable
     - Percentage of jobs meeting SLA
   * - report_file
     - FileField
     - nullable, upload_to='reports/monthly/'
     - Generated report file (PDF)
   * - submitted_at
     - DateTimeField
     - nullable
     - When submitted to OEM
   * - created_at
     - DateTimeField
     - auto_now_add
     - Generation timestamp

**Unique constraint**: ``(oem, month)``

ReportSubmission
----------------

Tracks the act of submitting any report type to an OEM.

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

   * - Field
     - Type
     - Constraints
     - Description
   * - id
     - UUIDField
     - PK, default=uuid4
     - Primary key
   * - report_type
     - CharField(20)
     - choices: ``weekly``, ``monthly``, ``closure_pack``
     - What was submitted
   * - report_id
     - UUIDField
     - not null
     - ID of the report object (polymorphic reference)
   * - submitted_by
     - ForeignKey(User)
     - not null, on_delete=PROTECT
     - OEM Reporting staff
   * - oem
     - ForeignKey(User)
     - not null, on_delete=PROTECT
     - Target OEM
   * - submitted_at
     - DateTimeField
     - auto_now_add
     - Submission timestamp
   * - acknowledged
     - BooleanField
     - default=False
     - OEM acknowledged receipt

**Indexes**: ``report_type``, ``oem``, ``submitted_at``