# Truck Payment Installments Implementation

## Overview

This document describes the implementation of truck payment installments tracking system, similar to the walk-in customer payment system. This solves the issue where multiple payments on different dates were all showing on the last payment date in reports.

## Problem Statement

Previously, truck payments were tracked in a single `truck_payments` table record that accumulated all payment amounts. When a subsequent payment was made, the `payment_date` changed, causing all accumulated amounts to appear on the last payment date in reports.

### Example Issue:
- **2026-02-04**: Truck delivers goods worth GH₵30,000, driver pays GH₵10,000 cash
- **2026-02-06**: Driver pays remaining GH₵20,000 via MoMo
- **Problem**: When generating report for 2026-02-06, it shows BOTH cash (GH₵10,000) and MoMo (GH₵20,000)
- **Result**: Cash balance is incorrect because GH₵10,000 was received on 2026-02-04, not 2026-02-06

## Solution: Truck Payment Installments Table

We implemented a **truck_payment_installments** table to track each individual payment transaction with its actual payment date.

## Files Created/Modified

### 1. New Model
**File**: `app/Models/TruckPaymentInstallment.php`
- Eloquent model for truck payment installments
- Relationships: truckPayment, truck, tenant, branch, user
- Scopes for filtering by date range, truck, tenant/branch

### 2. Migration Files

**File**: `database/migrations/2026_02_08_100000_create_truck_payment_installments_table.php`
- Creates the truck_payment_installments table
- Fields:
  - Payment amounts: cash, momo, bank
  - Expense amounts: fuel_expense, maintenance_expense, other_expense
  - Tracking: payment_date, is_first_payment, installment_number
  - References: truck_payment_id, invoice, truck_id

**File**: `database/migrations/2026_02_08_100001_backfill_truck_payment_installments.php`
- Backfills existing truck payment records into installments table
- Ensures historical data is tracked with proper dates

### 3. Updated Models

**File**: `app/Models/TruckPayment.php`
- Added `installments()` relationship method

### 4. Updated Controller

**File**: `app/Http/Controllers/Tenant/TruckPaymentController.php`

**Key Changes**:
1. Added `use App\Models\TruckPaymentInstallment;`
2. Updated `storePayment()` method:
   - Wrapped in DB transaction
   - Checks if first payment or subsequent payment
   - Creates installment record for each payment
   - **FIXED**: Updates ALL truck sales items for invoice (not just first one)
   - Determines payment status based on outstanding balance
   - Auto-posts to accounting

3. Added `fetchDayReceivedPayments()` method:
   - Fetches truck payment installments for today
   - Shows actual money received today
   - Returns installment details with truck and payment info

### 5. Updated Routes

**File**: `routes/tenant.php`
- Added route: `GET /truck_payments/fetch-day-received`

### 6. Updated Report Controller

**File**: `app/Http/Controllers/Tenant/TruckReportController.php`

**Changes in `generateSalesReport()`**:
- Added calculation for unprinted invoices (status = 'confirmed')
- Added calculation for printed invoices (status != 'confirmed')
- Returns `unprinted_total` and `printed_total` in response

### 7. Updated Report View

**File**: `resources/views/tenant/truck_details/report.blade.php`

**Changes in `displaySalesReport()`**:
- Added display cards for unprinted and printed invoice totals
- Shows breakdown of confirmed sales vs invoices with payment records

## Database Schema

```sql
CREATE TABLE truck_payment_installments (
    id BIGINT PRIMARY KEY,
    truck_payment_id BIGINT,        -- Links to main payment record
    invoice VARCHAR,                 -- Invoice number
    truck_id BIGINT,                -- Truck associated with payment
    
    -- Payment method amounts for THIS installment
    cash DECIMAL(10,2) DEFAULT 0,
    momo DECIMAL(10,2) DEFAULT 0,
    bank DECIMAL(10,2) DEFAULT 0,
    
    -- Expense amounts for THIS installment
    fuel_expense DECIMAL(10,2) DEFAULT 0,
    maintenance_expense DECIMAL(10,2) DEFAULT 0,
    other_expense DECIMAL(10,2) DEFAULT 0,
    
    -- Installment details
    installment_amount DECIMAL(10,2),  -- Total for this installment
    payment_mode VARCHAR,               -- cash, momo, combo, etc.
    remarks TEXT,
    
    -- Critical: Actual payment date
    payment_date DATE,                  -- When payment was ACTUALLY received
    is_first_payment BOOLEAN,
    installment_number INT,
    
    -- Tracking
    tenant_id BIGINT,
    branch_id BIGINT,
    user_id BIGINT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    
    FOREIGN KEY (truck_payment_id) REFERENCES truck_payments(id) ON DELETE CASCADE
);
```

## How It Works

### 1. First Payment (2026-02-04)
```php
// Main payment record (accumulates totals)
TruckPayment {
    invoice: 'TRK-001',
    goods_sold_amount: 30000,
    cash: 10000,      // Accumulated
    momo: 0,
    total_payment: 10000,
    outstanding_balance: 20000,
}

// Installment record (tracks THIS payment)
TruckPaymentInstallment {
    truck_payment_id: 1,
    invoice: 'TRK-001',
    cash: 10000,      // Only this installment
    momo: 0,
    installment_amount: 10000,
    payment_date: '2026-02-04',  // Actual date received
    is_first_payment: true,
    installment_number: 1
}

// ALL truck sales items updated
TruckSales (all items with invoice 'TRK-001') {
    status: 'part_payment'  // Updated for ALL items
}
```

### 2. Second Payment (2026-02-06)
```php
// Main payment record (updated totals)
TruckPayment {
    invoice: 'TRK-001',
    goods_sold_amount: 30000,
    cash: 10000,      // Accumulated (unchanged)
    momo: 20000,      // Accumulated (new)
    total_payment: 30000,
    outstanding_balance: 0,
    payment_date: '2026-02-06'  // Changed, but we don't use this for reports
}

// NEW Installment record (tracks THIS payment)
TruckPaymentInstallment {
    truck_payment_id: 1,
    invoice: 'TRK-001',
    cash: 0,          // Only this installment
    momo: 20000,      // Only this installment
    installment_amount: 20000,
    payment_date: '2026-02-06',  // Actual date received
    is_first_payment: false,
    installment_number: 2
}

// ALL truck sales items updated
TruckSales (all items with invoice 'TRK-001') {
    status: 'paid'  // Updated for ALL items
}
```

### 3. Report Generation (Accurate Date-Based)

**Report for 2026-02-04:**
```php
$installments = TruckPaymentInstallment::whereDate('payment_date', '2026-02-04')->get();
// Returns:
// Cash: GH₵10,000
// MoMo: GH₵0
// Total: GH₵10,000
```

**Report for 2026-02-06:**
```php
$installments = TruckPaymentInstallment::whereDate('payment_date', '2026-02-06')->get();
// Returns:
// Cash: GH₵0
// MoMo: GH₵20,000
// Total: GH₵20,000
```

## Key Fixes Implemented

### 1. Invoice Status Update Fix
**Problem**: Only the first item in an invoice was being updated when payment was made.

**Solution**: 
```php
// OLD CODE (Wrong):
$sale = TruckSales::where('invoice', $invoice)->first();
$sale->status = $newStatus;
$sale->save();

// NEW CODE (Correct):
TruckSales::where('invoice', $invoice)
    ->where('tenant_id', $tenantId)
    ->where('branch_id', $branchId)
    ->update(['status' => $newStatus]);  // Updates ALL items
```

### 2. Printed/Unprinted Invoices Tracking
**Added to Truck Sales Report**:
- **Unprinted Invoices**: Sales with status = 'confirmed' (not yet printed)
- **Printed Invoices**: Sales with status != 'confirmed' (payment record created)

This matches the walk-in customer sales report functionality.

## Benefits

1. **Accurate Date Tracking**: Each payment is recorded with its actual receipt date
2. **Correct Daily Reports**: Cash received on Day 1 shows on Day 1, not Day 2
3. **Complete Audit Trail**: Full history of all payment installments
4. **Backward Compatible**: Main `truck_payments` table still maintains accumulated totals
5. **Flexible Reporting**: Can generate reports by any date range with accuracy
6. **Fixed Invoice Updates**: ALL items in an invoice are updated, not just the first one
7. **Printed/Unprinted Tracking**: Better visibility into invoice processing status

## Migration Steps

### 1. Run the Migrations
```bash
php artisan migrate
```

This will:
- Create the `truck_payment_installments` table
- Backfill existing truck payment data

### 2. Test with New Payments
1. Create a new truck sale
2. Print invoice (creates payment record)
3. Make partial payment (e.g., cash)
4. Wait a day or change system date
5. Make second payment (e.g., MoMo)
6. Verify reports show correct amounts on correct dates
7. Verify ALL items in invoice have updated status

### 3. Verify Reports
- Check truck sales report shows unprinted/printed totals
- Check payment reports use installment dates
- Verify daily cash flow reports are accurate

## API Endpoints

### Fetch Day Received Payments
```
GET /tenant/{domain}/truck_payments/fetch-day-received
```

Returns truck payment installments for today with actual payment dates.

**Response**:
```json
{
    "data": [
        {
            "id": 1,
            "invoice": "TRK-001",
            "truck": {...},
            "amount": 10000,
            "cash": 10000,
            "momo": 0,
            "payment_date": "2026-02-04",
            "installment_number": 1,
            "is_first_payment": true,
            "status": "part_payment"
        }
    ]
}
```

## Testing Scenarios

### Scenario 1: Single Payment
- Create truck sale for GH₵10,000
- Pay full amount in cash on Day 1
- **Expected**: Day 1 report shows GH₵10,000 cash
- **Expected**: All items in invoice have status 'paid'

### Scenario 2: Two Payments (Different Dates)
- Create truck sale for GH₵30,000 on Day 1
- Pay GH₵10,000 cash on Day 1
- Pay GH₵20,000 MoMo on Day 3
- **Expected**: 
  - Day 1 report: GH₵10,000 cash, GH₵0 MoMo
  - Day 3 report: GH₵0 cash, GH₵20,000 MoMo
  - All items have status 'part_payment' after Day 1
  - All items have status 'paid' after Day 3

### Scenario 3: Multiple Items in Invoice
- Create truck sale with 5 different products
- Make partial payment
- **Expected**: ALL 5 items have status 'part_payment'
- Make final payment
- **Expected**: ALL 5 items have status 'paid'

### Scenario 4: Printed/Unprinted Tracking
- Create truck sales (status = 'confirmed')
- Check report shows unprinted total
- Print invoice (creates payment record, status changes)
- Check report shows printed total

## Troubleshooting

### Issue: Installments not created
**Check**: Verify TruckPaymentController::storePayment() creates installments

### Issue: Wrong dates in reports
**Check**: Ensure payment_date is set to current date, not updated_at

### Issue: Only first item updated
**Check**: Verify using `update()` method, not `first()->save()`

### Issue: Unprinted/printed totals not showing
**Check**: Verify TruckReportController returns these values

## Conclusion

This implementation provides accurate, date-based truck payment tracking that solves the accounting imbalance issue. Each payment is now recorded with its actual receipt date, ensuring daily reports reflect the true cash flow for that specific day. Additionally, all items in an invoice are properly updated when payments are made, and the system tracks printed vs unprinted invoices for better visibility.

---

**Implementation Date**: 2026-02-08  
**Status**: Complete  
**Tested**: Ready for production use