Finance Models
==============

VendorPayment
-------------

Payment to a vendor for locally procured materials.

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

   * - Field
     - Type
     - Constraints
     - Description
   * - id
     - UUIDField
     - PK, default=uuid4
     - Primary key
   * - procurement_request
     - OneToOneField(ProcurementRequest)
     - not null, on_delete=PROTECT
     - Linked procurement request
   * - vendor
     - ForeignKey(Vendor)
     - not null, on_delete=PROTECT
     - Payee vendor
   * - amount
     - DecimalField(10,2)
     - not null
     - Payment amount
   * - payment_method
     - CharField(20)
     - choices: ``upi``, ``bank_transfer``, ``cash``
     - How payment was made
   * - transaction_ref
     - CharField(100)
     - nullable
     - External transaction reference
   * - status
     - CharField(20)
     - choices: ``pending``, ``processing``, ``completed``, ``failed``
     - Payment state
   * - paid_by
     - ForeignKey(User)
     - not null, on_delete=PROTECT, limit_choices_to={role=finance}
     - Finance user who processed payment
   * - paid_at
     - DateTimeField
     - nullable
     - When payment was executed
   * - created_at
     - DateTimeField
     - auto_now_add
     - Record creation timestamp

**Indexes**: ``status``, ``vendor``, ``paid_at``

JobPayout
---------

Payment to a field team for a completed installation.

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

   * - Field
     - Type
     - Constraints
     - Description
   * - id
     - UUIDField
     - PK, default=uuid4
     - Primary key
   * - installation
     - ForeignKey(Installation)
     - not null, on_delete=PROTECT
     - Completed installation
   * - team
     - ForeignKey(Team)
     - not null, on_delete=PROTECT
     - Payee field team
   * - amount
     - DecimalField(10,2)
     - not null
     - Payout amount
   * - payout_type
     - CharField(20)
     - choices: ``per_job``, ``fortnightly``, ``monthly``
     - Payout schedule type
   * - status
     - CharField(20)
     - choices: ``pending``, ``marked_payable``, ``processing``, ``paid``
     - Payout lifecycle state
   * - marked_payable_by
     - ForeignKey(User)
     - nullable, on_delete=SET_NULL
     - Central Ops who approved
   * - marked_payable_at
     - DateTimeField
     - nullable
     - When marked as payable
   * - paid_by
     - ForeignKey(User)
     - nullable, on_delete=SET_NULL
     - Finance user who released payment
   * - paid_at
     - DateTimeField
     - nullable
     - Payment release timestamp
   * - transaction_ref
     - CharField(100)
     - nullable
     - External transaction reference
   * - created_at
     - DateTimeField
     - auto_now_add
     - Record creation timestamp

**Indexes**: ``status``, ``team``, ``payout_type``

PaymentSchedule
---------------

Defines the payout frequency for each field team.

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

   * - Field
     - Type
     - Constraints
     - Description
   * - id
     - AutoField
     - PK
     - Primary key
   * - team
     - ForeignKey(Team)
     - not null, on_delete=CASCADE
     - Which team
   * - schedule_type
     - CharField(20)
     - choices: ``per_job``, ``fortnightly``, ``monthly``
     - Payment frequency
   * - next_payout_date
     - DateField
     - nullable
     - Next scheduled payout date
   * - is_active
     - BooleanField
     - default=True
     - Whether schedule is currently active