# Collections, reports, notifications and generated codes

Run `php yii migrate` after pulling this update. Migrations add immutable follow-up records, per-user notification read receipts, external-reference fields and a transaction-reference registry. Existing references remain unchanged; their provider/document references are retained separately. New record codes are assigned by the server. Clients, collateral, applications, loans, reloan requests, custody requests, recovery sales and follow-ups use their existing generated record identifiers; new payout, repayment, intake, handover and client-return receipts get unique prefixed codes. New branch codes are generated too. Users still enter real identity/serial numbers and provider transaction IDs; the system never invents those.

## Collections

Collections offers overdue, due-within-seven-days and approved-next-action queues, filtered by permitted branch and as-of date. Scheduled principal and interest are reduced by verified allocations, recoveries, approved reductions and debt transfers, oldest instalment first. Only instalments before the selected day are overdue; future payments are excluded. Final maturity debt and late fees remain separately visible.

Loan officers and branch managers record actual contact, method, outcome, optional payment promise, assigned officer and next action. The assigned officer must be active and have collection access to the original loan branch. A separate CEO reviews the immutable record. Pending promises do not enter the official action queue; rejected records retain the reason. No SMS/email is sent when a contact log is recorded.

## Reports

Reports includes portfolio balances, verified repayment cash, verified recovery sales, client surplus payables and custody. Position reports use the as-of date; collection/recovery reports use an inclusive date range. Screens and CSV exports share branch permissions and definitions. Browser printing can save the displayed report as PDF. Exported text is guarded against spreadsheet-formula injection.

Ordinary repayment cash excludes pending/rejected/reversed records, recoveries and non-cash transfers. Recovery net proceeds reconcile to debt applied plus surplus. Surplus reconciles to verified client returns and the outstanding payable, with pending returns shown separately. Original loan branches retain historical attribution. Custody follows physical events and remains at the source while in transit. Legacy intake snapshots retain their known branch basis; descriptions and appraisals are current registry values. Historical reports show effective dates using currently known approvals and reversals; they are not snapshots of what was known at a past publication time.

Client statements are available from client/loan pages and show scoped loans, balances and activity. Replacement principal and debt transfers are labelled as non-cash events. Activity cash amounts are individual events, not a net cash-flow total. Dashboard figures link to reports and collection work queues.

## In-app notifications

The header includes Notifications and an unread badge refreshed every minute while the page is visible. The inbox is derived from live actionable records: new events appear automatically and resolved events leave it. Read receipts are stored per user and event; marking an alert read does not approve or dismiss the underlying action. Resubmitted applications receive a new version-specific alert.

CEO alerts cover application and payout decisions, repayment verification, reloan approval, custody decisions, recovery sale/proceeds decisions, client surplus-return verification and follow-up review. Preparation roles receive approved payouts and their own returned applications. Custody staff receive intake, source handover, destination receipt, sale payment/buyer collection and unreserved client-surplus actions. Loan officers and branch managers receive upcoming (seven-day window), due-today and overdue loan-payment alerts within their current branches. The assigned officer receives the latest approved follow-up when its next action is due. Access changes immediately change the visible inbox; technical administrators receive no business approval authority. A preparer still cannot self-approve where that workflow forbids it.

These are in-app alerts, not email/SMS/push delivery. Sending through an external provider remains a separate configured feature. Future modules must add their approval and preparation stages to this action catalogue.

External electronic payment references remain required for bank/mobile transactions and are reserved atomically by direction across incoming repayment/recovery records and outgoing payout/return records. Cash system receipt codes and custody handover codes do not require a manually supplied reference. Existing financial records and signed evidence are preserved.

Checks cover arrears versus future obligations, reviewed promises, branch-safe reports and alerts, reconciliation, role/self-approval guards, read persistence, generated references and actual HTTP form/export paths. Workbook import remains a separate reviewed mapping and validation step; no production data import runs in this update.