[Payments]: implement payments options on invoice list

[nielsdrost7]

SMART Plan — [Payments] Implement payments options on invoice list

Specific

Add an "Enter Payment" inline table action to InvoicesTable that opens a Filament modal pre-filled with the invoice's ID and its outstanding balance (total minus already-recorded payments). Submitting the modal creates a new Payment record linked to the invoice.

Measurable

• An "Enter Payment" action appears in the row action group for each invoice in InvoicesTable.
• Triggering the action opens a modal with the invoice_id fixed and the amount field defaulting to the invoice's outstanding balance.
• Submitting the modal creates a new Payment record with the correct invoice_id and amount.
• After payment entry, the invoice's status is updated (e.g. paid if fully settled, partial otherwise).
• The action is hidden or disabled for invoices that are already fully paid.

Achievable

1. Add Action::make('enter_payment') with a form([TextInput::make('amount')->default(fn (Invoice $record) => $record->outstanding_balance)]) and a modal to Modules/Invoices/Filament/Company/Resources/Invoices/Tables/InvoicesTable.php.
2. In the action's action() callback, delegate to Modules/Payments/Services/PaymentService.php to create the payment and update the invoice status.
3. Add an outstanding_balance accessor to Modules/Invoices/Models/Invoice.php if not already present.
4. Add PHPUnit tests in Modules/Invoices/Tests/Feature/InvoicesTest.php.

Relevant

Entering payments is one of the most frequent tasks in an invoicing app. Forcing users to navigate away from the invoice list to a separate Payment creation form interrupts the workflow. An inline modal keeps the user in context and reduces clicks.

Time-bound

Sprint 5.

---

Arrange · Act · Assert

// Modules/Invoices/Tests/Feature/InvoicesTest.php

#[Test]
public function it_opens_enter_payment_modal_with_outstanding_balance_prefilled(): void
{
    /* Arrange */
    $invoice = Invoice::factory()->for($this->company)->create([
        'total'  => 200.00,
        'status' => 'sent',
    ]);
    // No payments yet — outstanding = 200.00

    /* Act */
    $component = Livewire::actingAs($this->user)
        ->test(ListInvoices::class, ['tenant' => Str::lower($this->company->search_code)])
        ->mountTableAction('enter_payment', $invoice);

    /* Assert */
    $component->assertSuccessful();
    $component->assertTableActionDataSet([
        'amount' => 200.00,
    ]);
}

#[Test]
public function it_creates_a_payment_record_when_enter_payment_is_submitted(): void
{
    /* Arrange */
    $invoice = Invoice::factory()->for($this->company)->create([
        'total'  => 150.00,
        'status' => 'sent',
    ]);

    /* Act */
    $component = Livewire::actingAs($this->user)
        ->test(ListInvoices::class, ['tenant' => Str::lower($this->company->search_code)])
        ->mountTableAction('enter_payment', $invoice)
        ->setTableActionData(['amount' => 150.00])
        ->callMountedTableAction();

    /* Assert */
    $component->assertSuccessful();
    $this->assertDatabaseHas('payments', [
        'invoice_id' => $invoice->id,
        'amount'     => 150.00,
    ]);
    $this->assertDatabaseHas('invoices', [
        'id'     => $invoice->id,
        'status' => 'paid',
    ]);
}

[nielsdrost7]

@coderabbitai make pull-request with AAA test Scenario's: Arrange, Act, Assert. And also make sure you test edge cases

[coderabbitai]

Coding Plan

Approach

Add the ability to record payments directly from the invoice list view by implementing a row action that opens a modal form, validates payment amounts, creates payment records, and updates invoice status appropriately.

Observations

The project uses Filament for admin panel UI with a modular structure. Invoices and Payments are separate modules with established HasMany/BelongsTo relationships. Invoice list functionality is centralized in InvoicesTable.php which defines columns, filters, and row actions. The Payments module has a PaymentService for business logic and a PaymentForm schema for UI. Testing follows PHPUnit with explicit AAA pattern comments and uses Livewire action testing helpers. The codebase currently has no payment recording integration on the invoice list - payments must be created separately and linked to invoices.

Assumptions

Assumption 1: Payment Amount Validation Strategy

Options Considered:

• Validate only at form level using dynamic max rules
• Add validation in PaymentService for all payment creation flows
• Add validation in the action's form submission hook

Chosen Option: 3

Rationale: This keeps invoice-specific payment validation localized to the invoice context without affecting general payment creation flows elsewhere. The validation will calculate remaining balance and ensure the payment amount doesn't exceed it.

Assumption 2: Invoice Status Update Mechanism

Options Considered:

• Update status manually in the action after payment creation
• Activate PaymentObserver to automatically handle status updates
• Create a dedicated event/listener system

Chosen Option: 1

Rationale: The existing PaymentObserver is commented out, suggesting it's not actively used. For this focused requirement, explicitly updating the invoice status in the action keeps the behavior clear and testable without requiring observer infrastructure. We'll add a helper method to Invoice model to calculate and set the appropriate status, which can be called from the action.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Add Payment Calculation Methods to Invoice Model

Enhance the Invoice model with helper methods to support payment tracking and validation. These methods provide the foundation for determining remaining balances and updating invoice payment status.

Task 1: Add Payment Calculation Helpers

Add methods to calculate total paid amount and remaining balance on invoices

• Create getTotalPaid() method in Modules/Invoices/Models/Invoice.php that sums payment_amount from all related payments with COMPLETED status
• Create getRemainingBalance() method that returns invoice_total - getTotalPaid()
• Create isFullyPaid() helper method that returns true when remaining balance is zero or negative
• Create isPartiallyPaid() helper method that returns true when total paid is greater than zero but less than invoice total

Task 2: Add Invoice Status Update Logic

Implement automated status calculation based on payment state

• Create updatePaymentStatus() method in Modules/Invoices/Models/Invoice.php that evaluates payment state and sets appropriate invoice_status
• Logic: if isFullyPaid() → set status to InvoiceStatus::PAID, else if isPartiallyPaid() → set status to InvoiceStatus::PARTIALLY_PAID, else leave status unchanged
• Method should save the model after status change
• Consider edge case: only update status if invoice is currently in SENT, VIEWED, PARTIALLY_PAID, or OVERDUE status (don't override DRAFT)

🤖 Prompt for AI agents

Implement payment calculation and status update methods on the Invoice model.

Add the following helper methods to `Modules/Invoices/Models/Invoice.php`:
- `getTotalPaid()`: Sum payment_amount from related payments with COMPLETED
status
- `getRemainingBalance()`: Calculate invoice_total minus getTotalPaid()
- `isFullyPaid()`: Return true when remaining balance is zero or negative
- `isPartiallyPaid()`: Return true when total paid > 0 but < invoice total
- `updatePaymentStatus()`: Evaluate payment state and update invoice_status
accordingly (PAID if fully paid, PARTIALLY_PAID if partially paid, unchanged
otherwise). Only update status for SENT, VIEWED, PARTIALLY_PAID, or OVERDUE
invoices. Save the model after status change.

Phase 2: Implement Record Payment Row Action

Create a Filament table action that allows recording payments directly from the invoice list with proper validation and status updates.

Task 1: Add Record Payment Action to InvoicesTable

Define the row action with modal form in the invoice table configuration

• Add new Action::make('record_payment') to the actions array in Modules/Invoices/Filament/Company/Resources/Invoices/Tables/InvoicesTable.php
• Position action in the existing ActionGroup alongside send email, send_to_peppol, etc.
• Configure action with icon (e.g., 'heroicon-o-currency-dollar'), label, and primary button color
• Set modal heading to "Record Payment for Invoice #{invoice_number}"

Task 2: Define Payment Form Schema

Build the form fields for payment data entry with invoice context

• Define form schema in the action's form() method with fields:
  • Hidden field for invoice_id with value from $record->id
  • Numeric input for payment_amount with required, min(0.01), and dynamic max rule (set to $record->getRemainingBalance())
  • Date picker for paid_at defaulting to today
  • Select dropdown for payment_method using PaymentMethod enum cases
  • Select dropdown for payment_status defaulting to PaymentStatus::COMPLETED
  • Textarea for notes (optional)
• Add helper text to amount field showing remaining balance: "Remaining balance: {formatted_amount}"
• Make form use 2-column grid layout for better UX

Task 3: Add Validation and Payment Creation Logic

Implement form submission handling with validation and business logic

• Add validation in action's mutateFormDataUsing() hook to verify payment amount doesn't exceed remaining balance (defensive validation)
• Call PaymentService::createPayment($data) in the action's action() callback to create payment record
• After successful payment creation, call $record->fresh()->updatePaymentStatus() to update invoice status
• Add success notification showing: "Payment recorded. Remaining balance: {formatted_amount}"
• Add error handling for payment creation failures with appropriate error notifications

Task 4: Add Display Logic and Visibility Rules

Configure when the action should be available

• Add visible() condition to hide action when invoice status is DRAFT or PAID
• Add disabled() condition with explanation when remaining balance is zero
• Optionally add badge to action showing remaining balance amount for quick reference

🤖 Prompt for AI agents

Create a record payment row action in the invoice table that opens a modal form.

In
`Modules/Invoices/Filament/Company/Resources/Invoices/Tables/InvoicesTable.php`:
Add `Action::make('record_payment')` to the actions array with:
- Icon (heroicon-o-currency-dollar), label, and primary color
- Modal heading displaying invoice number
- Form schema with fields: hidden invoice_id, payment_amount (numeric, required,
min 0.01, max remaining balance with helper text), paid_at (date, default
today), payment_method (select from enum), payment_status (select, default
COMPLETED), notes (textarea, optional)
- Use 2-column grid layout
- Validation in mutateFormDataUsing() to prevent overpayment
- Action callback that calls PaymentService::createPayment(), then refreshes
record and calls updatePaymentStatus()
- Success notification with remaining balance
- Error handling with notifications
- Visible only when status is not DRAFT or PAID
- Disabled when remaining balance is zero

Phase 3: Comprehensive Test Coverage with AAA Pattern

Write feature and unit tests following the established AAA pattern with edge case coverage.

Task 1: Create Feature Test for Recording Payments

Test the complete payment recording flow from the invoice list

• Create test file Modules/Invoices/Tests/Feature/RecordPaymentFromInvoiceListTest.php extending AbstractCompanyPanelTestCase
• Write test it_can_record_full_payment_on_invoice():
  • Arrange: Create invoice with status SENT, total 1000
  • Act: Mount 'record_payment' action, fillForm with payment_amount 1000, call action
  • Assert: Payment exists in database, invoice status is PAID, invoice balance is 0
• Write test it_can_record_partial_payment_on_invoice():
  • Arrange: Create invoice with status SENT, total 1000
  • Act: Record payment of 400
  • Assert: Payment exists, invoice status is PARTIALLY_PAID, remaining balance is 600
• Write test it_can_record_multiple_payments_on_same_invoice():
  • Arrange: Create invoice, record first payment of 300
  • Act: Record second payment of 400, then third payment of 300
  • Assert: Three payments exist, total paid is 1000, invoice status is PAID

Task 2: Create Validation Edge Case Tests

Test boundary conditions and validation rules

• Write test it_prevents_overpayment_on_invoice():
  • Arrange: Create invoice with total 1000
  • Act: Attempt to record payment of 1500
  • Assert: Validation fails, no payment created, invoice status unchanged
• Write test it_prevents_negative_payment_amounts():
  • Arrange: Create invoice
  • Act: Attempt to record payment with negative amount
  • Assert: Validation fails, no payment created
• Write test it_prevents_zero_payment_amounts():
  • Arrange: Create invoice
  • Act: Attempt to record payment of 0
  • Assert: Validation fails with appropriate error message
• Write test it_handles_overpayment_with_existing_partial_payment():
  • Arrange: Create invoice with total 1000, record payment of 600
  • Act: Attempt to record second payment of 600
  • Assert: Validation fails because total would exceed invoice total

Task 3: Create Invoice Status Transition Tests

Test status changes based on payment state

• Write test it_updates_status_from_sent_to_partially_paid():
  • Arrange: Invoice with status SENT, total 1000
  • Act: Record payment of 500
  • Assert: Status changes to PARTIALLY_PAID
• Write test it_updates_status_from_partially_paid_to_paid():
  • Arrange: Invoice with status PARTIALLY_PAID, 500 already paid, total 1000
  • Act: Record payment of 500
  • Assert: Status changes to PAID
• Write test it_updates_overdue_invoice_to_paid_when_fully_paid():
  • Arrange: Invoice with status OVERDUE
  • Act: Record full payment
  • Assert: Status changes to PAID
• Write test it_does_not_change_draft_status_when_payment_recorded():
  • Arrange: Invoice with status DRAFT
  • Act: Record payment (if action is visible for drafts)
  • Assert: Status remains DRAFT (or verify action is not visible)

Task 4: Create Unit Tests for Invoice Payment Helpers

Test the Invoice model payment calculation methods

• Create test file Modules/Invoices/Tests/Unit/InvoicePaymentCalculationsTest.php extending AbstractTestCase
• Write test it_calculates_total_paid_from_completed_payments():
  • Arrange: Create invoice with three payments (two COMPLETED, one PENDING)
  • Act: Call getTotalPaid()
  • Assert: Returns sum of only COMPLETED payments
• Write test it_calculates_remaining_balance_correctly():
  • Arrange: Invoice with total 1000, payments totaling 600
  • Act: Call getRemainingBalance()
  • Assert: Returns 400
• Write test it_identifies_fully_paid_invoices():
  • Arrange: Invoice with total 1000, payments totaling 1000
  • Act: Call isFullyPaid()
  • Assert: Returns true
• Write test it_identifies_partially_paid_invoices():
  • Arrange: Invoice with total 1000, payments totaling 500
  • Act: Call isPartiallyPaid()
  • Assert: Returns true

Task 5: Test Action Visibility and Authorization

Verify action availability logic and permissions

• Write test it_hides_record_payment_action_on_draft_invoices():
  • Arrange: Create invoice with status DRAFT
  • Act: Check action visibility
  • Assert: Action is not visible or disabled
• Write test it_hides_record_payment_action_on_fully_paid_invoices():
  • Arrange: Create invoice with status PAID
  • Act: Check action visibility
  • Assert: Action is not visible or disabled
• Write test it_shows_record_payment_action_on_sent_invoices():
  • Arrange: Create invoice with status SENT
  • Act: Check action visibility
  • Assert: Action is visible and enabled

🤖 Prompt for AI agents

Write comprehensive tests for payment recording functionality using AAA pattern.

Create `Modules/Invoices/Tests/Feature/RecordPaymentFromInvoiceListTest.php`:
Test full payment recording, partial payments, multiple payments on same
invoice, overpayment prevention, negative/zero amount validation, and
overpayment with existing partial payments

Test invoice status transitions: SENT→PARTIALLY_PAID, PARTIALLY_PAID→PAID,
OVERDUE→PAID, and DRAFT status preservation

Create `Modules/Invoices/Tests/Unit/InvoicePaymentCalculationsTest.php`:
Test getTotalPaid() with mixed payment statuses, getRemainingBalance()
calculation, isFullyPaid() and isPartiallyPaid() identification

Test action visibility: hidden on DRAFT and PAID invoices, visible on SENT
invoices

Use Livewire action testing helpers (mountAction, fillForm, callAction) and
follow AAA pattern with explicit comments

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Implement payment calculation and status update methods on the Invoice model.

Add the following helper methods to `Modules/Invoices/Models/Invoice.php`:
- `getTotalPaid()`: Sum payment_amount from related payments with COMPLETED
status
- `getRemainingBalance()`: Calculate invoice_total minus getTotalPaid()
- `isFullyPaid()`: Return true when remaining balance is zero or negative
- `isPartiallyPaid()`: Return true when total paid > 0 but < invoice total
- `updatePaymentStatus()`: Evaluate payment state and update invoice_status
accordingly (PAID if fully paid, PARTIALLY_PAID if partially paid, unchanged
otherwise). Only update status for SENT, VIEWED, PARTIALLY_PAID, or OVERDUE
invoices. Save the model after status change.
===============================================================================

Task: 2

Create a record payment row action in the invoice table that opens a modal form.

In
`Modules/Invoices/Filament/Company/Resources/Invoices/Tables/InvoicesTable.php`:
Add `Action::make('record_payment')` to the actions array with:
- Icon (heroicon-o-currency-dollar), label, and primary color
- Modal heading displaying invoice number
- Form schema with fields: hidden invoice_id, payment_amount (numeric, required,
min 0.01, max remaining balance with helper text), paid_at (date, default
today), payment_method (select from enum), payment_status (select, default
COMPLETED), notes (textarea, optional)
- Use 2-column grid layout
- Validation in mutateFormDataUsing() to prevent overpayment
- Action callback that calls PaymentService::createPayment(), then refreshes
record and calls updatePaymentStatus()
- Success notification with remaining balance
- Error handling with notifications
- Visible only when status is not DRAFT or PAID
- Disabled when remaining balance is zero
===============================================================================

Task: 3

Write comprehensive tests for payment recording functionality using AAA pattern.

Create `Modules/Invoices/Tests/Feature/RecordPaymentFromInvoiceListTest.php`:
Test full payment recording, partial payments, multiple payments on same
invoice, overpayment prevention, negative/zero amount validation, and
overpayment with existing partial payments

Test invoice status transitions: SENT→PARTIALLY_PAID, PARTIALLY_PAID→PAID,
OVERDUE→PAID, and DRAFT status preservation

Create `Modules/Invoices/Tests/Unit/InvoicePaymentCalculationsTest.php`:
Test getTotalPaid() with mixed payment statuses, getRemainingBalance()
calculation, isFullyPaid() and isPartiallyPaid() identification

Test action visibility: hidden on DRAFT and PAID invoices, visible on SENT
invoices

Use Livewire action testing helpers (mountAction, fillForm, callAction) and
follow AAA pattern with explicit comments

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!

[nielsdrost7]

Already In Progress

This is covered by open PR #684, not yet merged. No new plan needed — track progress via that PR.