# Step 19 — Financial Reports — Implementation Report

**Status:** COMPLETED  
**Verified:** 12 August 2026  
**Pull request:** #31

## Reports implemented

Step 19 adds eight read-only financial reports built from permanent financial/accounting data:

1. Profit & Loss
2. Cash Flow
3. Account Statement
4. Capital Report
5. Expense Report
6. Payroll Report
7. Collection Report
8. Disbursement Report

No reporting-only financial balances or duplicated accounting records are stored.

## Profit & Loss

P&L is generated from `accounting_entries`.

Income sections:

- Interest income
- Fee income
- Penalty income
- Written-off loan recovery income
- Service income
- Other actual income

Expense sections:

- Operating expenses
- Payroll expense
- Bad-debt / write-off expense
- Settlement adjustments / other expenses

Loan principal activity is explicitly excluded from revenue.

`AccountingEntry::CATEGORIES` now includes the reporting categories for service income, other income, settlement adjustments and other expenses so ledger filtering and report semantics remain aligned.

## Cash Flow

Cash Flow is generated directly from `financial_account_transactions`.

It reports:

- Total money in
- Total money out
- Net cash flow
- Collections inflow
- Operating expense/payroll outflow
- Loan disbursement/top-up outflow
- Capital inflow
- Net transfers
- Detailed movement totals grouped by transaction type

Totals reconcile exactly to the selected transaction rows.

## Account Statement

Supports all selected accounts as summary rows and a single-account drill-down.

For each account the system calculates:

- Opening balance before the report start date
- Money in during the period
- Money out during the period
- Closing balance

Historical balances are mathematically reconstructed from permanent transactions instead of relying on the account's current mutable balance.

Single-account statements show each transaction with a report-period running balance.

## Capital Report

Generated from permanent financial transactions classified as:

- Opening balance
- Capital injection

Reports opening funds, capital injections and total capital movements for the selected scope.

## Expense Report

Generated from approved expense records and includes:

- Expense date/number
- Branch
- Category
- Description
- Supplier
- Paid-from account
- Amount

Only financially approved expenses are included.

## Payroll Report

Generated from paid payroll entries and includes:

- Payment date
- Payslip
- Employee snapshot
- Branch
- Payroll period
- Gross pay
- Deductions
- Net paid

Totals report gross payroll, deductions and actual net payroll paid.

## Collection Report

Generated from financial-account transactions for:

- Loan payments
- Early settlements
- Written-off loan recoveries

Collections are also grouped by receiving account channel such as cash, mobile money and bank.

## Disbursement Report

Generated from financial-account transactions for:

- Normal loan disbursements
- Loan top-up net cash disbursements

The report provides total disbursements and transaction-type reconciliation.

## Scope and filters

All eight reports support:

- Date range
- One branch
- Several branches
- All accessible company branches

Account Statement additionally supports a single financial-account drill-down.

Branch selections are validated against the authenticated user's assigned branch scope on the backend.

## Permissions and security

Step 19 reuses the existing `reports.view` permission.

Users without this permission cannot access report routes.

All report queries remain branch-scoped even if a user manually changes query parameters.

## User interface

Added Finance → **Financial Reports** navigation.

The report workspace contains:

- Eight report tabs
- Date filters
- Multi-branch selector
- Account selector for account statements
- Compact summary cards
- Standardized transaction/detail tables
- Print-friendly output

The UI follows the application's existing compact finance patterns.

## Verification

GitHub Actions Foundation CI on pull request #31:

- Fresh migrations: PASS
- Seeders: PASS
- Full Laravel test suite: **142 passed**
- Assertions: **1,390**
- Existing Step 1–18 regression tests: PASS
- Step 19 financial report feature tests: **6 passed**

Step 19 tests cover:

1. P&L actual-income/expense calculation and explicit principal-revenue exclusion.
2. Cash-flow and account-statement reconciliation from permanent transactions rather than mutable account balances.
3. Capital, approved-expense and paid-payroll reconciliation to their source records.
4. Collection channel and disbursement transaction-type reconciliation.
5. Date, single-branch, multi-branch and accessible-company scopes with backend branch isolation.
6. `reports.view` authorization, Finance navigation and successful rendering of all eight report endpoints.

## Remaining Step 19 work

None.

## Next roadmap module

**Step 20 — Loan and Branch Reports**.
