# Phase 52 — Professional Loan Pricing, Fees, Charges & Customer Disclosure Governance

## Purpose
Phase 52 moves new loan origination away from editable product-rate defaults and into an effective-dated, maker-checker controlled pricing workflow. The accepted customer disclosure becomes the immutable origination pricing snapshot used by disbursement, repayment scheduling and professional loan statements.

## Upgrade
1. Back up the Phase 51 database and application.
2. Import `sql/migration_052_loan_pricing_governance.sql`.
3. Replace the application files with the Phase 52 package.
4. Sign in and open `/loan-pricing`.
5. Create pricing policies and have a different authorized user approve them before originating new staff-entered loans.

## Professional workspace
Route: `/loan-pricing`

Tabs:
- Overview
- Policies
- Disclosures
- Charges
- Waivers
- Reviews

Navigation: Core Operations → Lending → Loan Pricing & Disclosures.

## Pricing policy governance
`loan_pricing_policies` stores effective-dated product/branch/amount-band pricing. Each policy freezes:
- product and branch scope;
- minimum/maximum principal;
- nominal annual interest rate;
- flat/reducing method;
- duration in months;
- grace period in days;
- processing fee rate;
- insurance fee rate;
- penalty rate;
- fee treatment (`separate` or `deduct_at_disbursement`);
- quote-validity days;
- effective start/end dates.

Policies are created as `pending_approval`; the maker cannot approve their own policy. Approved policies with overlapping branch/product/amount/effective ranges are blocked. Branch-specific policies take precedence over institution-wide policies when both are otherwise eligible.

Combined processing + insurance charges must remain below 100% of principal. This guard applies to both fee-treatment methods so economic net proceeds remain positive and the customer-cost estimate remains meaningful.

## Customer pricing disclosure
Every new staff-originated loan now starts with a pricing disclosure rather than a direct loan record.

Flow:

`New Loan → Pricing Disclosure → Customer Acceptance → Loan Application → Independent Loan Approval → Fee Settlement/Waiver Evidence → Disbursement`

The disclosure freezes:
- customer/product/branch;
- approved policy reference;
- principal;
- nominal rate;
- interest method;
- term;
- grace period;
- processing and insurance fee rates/amounts;
- penalty rate;
- estimated interest and installment;
- scheduled repayment total;
- total customer cost;
- economic net proceeds;
- effective annual cost estimate;
- fee treatment;
- validity period;
- SHA-256 integrity checksum.

Customer acceptance evidence can be recorded as signed form, in-person acknowledgement, digital acceptance or OTP evidence. An expired disclosure cannot be accepted. The accepted disclosure must pass checksum verification before conversion to a loan.

## Grace-period integrity
Phase 52 freezes `grace_period_days` in both the approved policy and accepted disclosure. Disbursement uses the disclosure value for governed loans rather than the current product master, and loan statements show the frozen value. This prevents later product edits from silently changing the repayment start date of an already accepted facility.

The effective annual cost estimate also considers the disclosed grace period when discounting the installment stream.

## Effective annual cost
The system estimates an annualized effective customer cost from economic net proceeds, installment amount, term and grace timing. Upfront processing/insurance charges reduce the economic proceeds used in that estimate regardless of whether the fees are collected separately or deducted at disbursement.

This is an internal system estimate. Institutions must validate statutory APR/effective-rate methodology, terminology, rounding and disclosure wording for their current licence and applicable rules before using it as a formal regulatory APR.

## Immutable origination terms
After customer acceptance and conversion, the loan is created from the disclosure snapshot. Disbursement and schedule generation use the accepted disclosure rate, method, term and grace period, not a later-edited product master.

Professional loan statements also prefer the disclosure snapshot for rate, method, duration, grace period and fee rates.

Existing historical loans that do not have a Phase 52 disclosure remain operational through a legacy fallback to their existing product terms. This avoids breaking pre-upgrade loans.

## Upfront fee accounting
### Separate collection
For policies with `fee_treatment = separate`, the loan must first be independently approved. Staff then record processing/insurance fee receipts, each requiring maker-checker approval.

Approved receipt accounting:
- Dr selected Cash/Bank account (`1000` or `1010`)
- Cr `4010 Processing Fee Income`, or
- Cr `4020 Insurance Fee Income`.

Disbursement is blocked until approved separate receipts cover the current processing and insurance fee amounts.

### Deduct at disbursement
For policies with `fee_treatment = deduct_at_disbursement`, disbursement posts:
- Dr `1100 Loan Principal Receivable` — full principal;
- Cr cash — net amount paid to customer;
- Cr `4010 Processing Fee Income` — current processing fee;
- Cr `4020 Insurance Fee Income` — current insurance fee.

The cash register movement uses the actual net cash paid to the customer.

## Pricing waivers / concessions
Processing-fee and insurance-fee waivers are separately controlled:
- request before disbursement;
- independent approval required;
- maker cannot approve own waiver;
- approved waiver updates the loan's current charge;
- waiver cannot reduce a separately collected charge below receipts already approved;
- customer notification/acknowledgement evidence is mandatory before disbursement.

This means an approved concession cannot remain hidden from the customer while the loan is disbursed.

## Disbursement guard
For governed loans, `LoanPricingService::assertDisbursementReady()` validates:
- disclosure integrity checksum;
- accepted/converted pricing evidence;
- fee treatment;
- required separate fee receipts;
- approved waivers;
- customer notification of approved waivers.

Legacy loans without Phase 52 pricing records continue through the existing disbursement path.

## Pricing governance reviews
`loan_pricing_reviews` provides frozen periodic compliance evidence for:
- governed vs legacy/ungoverned loans;
- pending waivers;
- approved waiver value;
- review period and branch scope;
- maker/checker decisions;
- review checksum.

## Customer self-service
The existing customer portal remains a pre-application channel. It no longer presents the product master rate as though it were the customer's final approved price. Final price and charges are presented through the controlled Phase 52 disclosure workflow.

## Database objects
Migration creates five tables:
1. `loan_pricing_policies`
2. `loan_pricing_disclosures`
3. `loan_pricing_waivers`
4. `loan_upfront_charge_receipts`
5. `loan_pricing_reviews`

All Phase 52 foreign-key names use the `fk_pg52_` prefix.

## Files added/updated
Key files:
- `src/LoanPricingService.php`
- `src/LoanService.php`
- `src/LoanStatementService.php`
- `public/index.php`
- `views/loan_pricing.php`
- `views/loan_pricing_disclosure_print.php`
- `views/loans.php`
- `views/portal_dashboard.php`
- `views/layout_top.php`
- `public/assets/app.css`
- `sql/migration_052_loan_pricing_governance.sql`
- `sql/schema.sql`

## Operational note
Do not treat the seeded/current loan product table as the approved price catalogue for new loans after Phase 52. Establish approved effective-dated pricing policies first. The product master remains useful for product identity and legacy fallback, while the accepted disclosure is the contractual pricing snapshot for governed originations.