# Phase 45 - Interest Accrual, Non-Accrual & Suspense Management

## Purpose
Phase 45 adds controlled accrual accounting for loan interest while preserving the existing operational loan schedule and repayment balances.

## Main workspace
`/interest-accrual`

Tabs:
- Control Centre
- Policies
- Accrual Runs
- Non-Accrual Monitor
- Interest Ledger

## Policy model
Policies can be scoped to:
- all branches / all products
- one branch / all products
- all branches / one product
- one branch / one product

Policy scope precedence is branch+product, then branch, then product, then global. The first effective approved policy at the highest matching scope is selected for each loan. Policy approval is maker-checker controlled. Exact-scope policies with overlapping effective dates are blocked.

Configurable controls include:
- daily or monthly operating cadence
- non-accrual threshold in days
- cure/resume threshold in days
- whether previously accrued unpaid interest is reversed on entry to non-accrual
- effective-from / effective-to dates

No regulatory threshold is hard-coded. The institution must configure and approve its current policy.

## Accrual calculation
The service calculates contractual interest earned to the current date by prorating each scheduled installment's interest over its schedule period. Approved interest repayments to date are deducted before determining earned-unpaid interest.

For performing loans, the required recognized interest receivable is compared with the loan-level interest ledger. Only the delta is posted.

Accrual:
- Dr 1110 Interest Receivable
- Cr 4000 Interest Income

Reversal:
- Dr 4000 Interest Income
- Cr 1110 Interest Receivable

## Non-accrual and suspense
When a loan reaches the configured non-accrual threshold, income accrual stops. If the policy requires reversal, previously recognized unpaid interest is reversed from income and moved to the memorandum suspense ledger.

Suspended interest is tracked outside the GL so it is not treated as recognized income. Cure/resumption uses a separate lower threshold to prevent immediate oscillation between accrual and non-accrual states.

## Repayment integration
`LoanService::postRepayment()` now checks the interest ledger before posting interest collections:
- interest already accrued: Cr 1110 Interest Receivable
- suspended interest collected: Cr 4000 Interest Income on collection, and reduce suspense memo balance
- unaccrued interest collected early: Cr 4000 Interest Income on collection

This prevents interest income from being recognized twice. The Control Centre also reconciles the loan-level recognized-interest ledger to GL account 1110 and surfaces any variance, including manual GL entries.

If the Phase 45 migration has not yet been installed, the repayment service safely falls back to the original cash-basis interest posting behavior.

## Run controls
- Runs use today's live loan/repayment position; historical backdating is blocked.
- One active/approved run per branch/date.
- Draft run freezes loan-level calculation lines.
- Maker submits; independent checker approves/rejects.
- Approval rechecks loan-level recognized/suspended balances to detect changes after draft preparation.
- Financial-period posting locks are enforced on approval.
- Approved runs create the GL journal and loan-level interest ledger movements in the same database transaction.

## Database
Upgrade from Phase 44 by importing:
`sql/migration_045_interest_accrual_suspense.sql`

New tables:
- `interest_accrual_policies`
- `interest_accrual_runs`
- `interest_accrual_lines`
- `interest_accrual_ledger`

No new GL account is required. Existing accounts are used:
- 1110 Interest Receivable
- 4000 Interest Income

## Navigation
Finance & Control -> Accounting -> Interest Accrual & Suspense