GSB-Construction/docs/PLAN.md

Implementation Plan: Retention Invoice & Ledger Export Feature

Goal: Provide full export capabilities (CSV, Spreadsheet, and Printable PDF) for both the overall Retention Management Ledger (/finance/retention) and individual Retention Invoices & Penalty Statements (/finance/{invoice}).

---

User Review Required

Note

Executive roles (Super Admin, Admin, Project Manager) and Contractor Admin will have access to export retention ledgers and invoice statements matching their authorized scope.

---

Proposed Changes

Backend Component (Modules/FinancialManagement)

[MODIFY] FinanceController.php

• Add exportRetentionCsv(Request $request): Exports retention entries, project balances, and overdue penalty summaries to a formatted CSV/Excel stream.
• Add exportRetentionInvoicePdf(FinancialInvoice $invoice): Generates and streams a formatted PDF / Printable Retention Statement for an individual invoice (including base retention 10%, penalty surcharge rate & reason, payment proof details, and approval audit timestamps).

[MODIFY] routes/web.php

• Register GET /finance/retention/export-csv route (route('retention.export-csv')).
• Register GET /finance/{invoice}/export-pdf route (route('finance.export-pdf')).

---

Frontend Component (Modules/FinancialManagement/resources/js)

[MODIFY] Retention/Index.tsx

• Add Export Retention Report button in header toolbar with CSV / PDF options.

[MODIFY] Invoices/Show.tsx

• Add Download Retention Statement (PDF) button in invoice header actions.

---

Verification Plan

Automated Tests

• php artisan test Modules/FinancialManagement/tests/Feature/RevisedRetentionFlowTest.php

Manual Verification

• Test downloading Retention Ledger CSV from /finance/retention.
• Test downloading Retention Statement PDF from /finance/{invoice}.