# Step 14 — Early Settlement & Restructuring — Implementation Report

**Status:** COMPLETED  
**Verified:** 12 August 2026

## Early settlement

- Added a complete early-settlement workflow for active loans.
- The settlement quote is calculated on the backend from the current:
  - outstanding principal
  - outstanding interest
  - outstanding fees
  - penalties due through the settlement date
  - authorized settlement adjustment
  - final settlement amount
- Penalties are assessed through the selected settlement date before the final amount is posted.
- Final posting recalculates all balances inside a database transaction under locks instead of trusting a stale preview.
- A permanent `loan_early_settlements` record stores the component breakdown, adjustment, final cash amount, account, date, reference, notes and employee.
- The final amount is received into the selected active financial account in the same branch.
- A permanent financial-account transaction is created for the actual cash received.
- Balanced accounting entries distinguish:
  - Assets / cash received
  - Principal recovery
  - Interest
  - Fees
  - Penalties
  - Settlement adjustment
- Principal recovery remains separate from income components.
- Settlement adjustment is explicit rather than derived from an invented formula because the authoritative specification does not define an automatic adjustment formula.
- Non-zero adjustments require the dedicated `loans.settlement.adjust` permission and a reason.
- Negative settlement adjustments may reduce only interest, fees and penalties; they can never waive outstanding principal. Principal write-off remains outside Step 14 and belongs to Step 15.
- Duplicate early settlement is blocked.
- Early settlement is blocked while an unresolved restructuring or top-up replacement application exists.
- After successful settlement:
  - loan status becomes `Fully Paid`
  - outstanding and arrears balances become zero
  - completion and last-payment dates are stored
  - active installments are closed
  - customer statement and status history are updated permanently
  - linked non-terminal collateral becomes `Ready for Release`
  - each collateral transition creates a permanent custody movement
- `Ready for Release` does not physically release collateral; the existing collateral custody/release workflow remains the separate physical handover control.

## Restructuring

- Added controlled restructuring for active loans.
- Authorized staff can propose:
  - extended repayment terms
  - changed installment amounts
  - moved repayment dates
- Proposed schedule input uses `YYYY-MM-DD | amount` per installment.
- Proposed dates must be valid future dates and strictly increasing.
- Proposed installment amounts must reconcile exactly to the current outstanding principal + interest + fees using fixed-precision money math.
- Existing penalties remain payable and are carried into the restructured schedule instead of silently disappearing.
- Added versioned repayment schedules:
  - every installment has a `schedule_version`
  - only one version is operational through `is_active`
  - the loan stores `current_schedule_version`
  - uniqueness is enforced by `(loan_id, schedule_version, installment_number)`
- The original schedule is never deleted.
- Approval retires the previous version by setting it inactive and creates the new active version.
- `Loan::installments()` exposes only the active operational schedule while `Loan::allInstallments()` preserves every historical version.
- Payment, penalty, overdue, top-up and other loan operations that use the loan installment relationship therefore operate on the active schedule.
- Direct reminder processing was explicitly updated to ignore retired installments.
- Each restructuring permanently stores:
  - previous schedule version
  - new schedule version
  - outstanding balance component snapshot
  - previous schedule JSON snapshot
  - proposed schedule JSON snapshot
  - reason
  - supporting documents
  - requester and request date
  - approver/rejecter and decision date
  - decision comments
- Supporting documents are stored privately and downloaded only through authorized branch-scoped routes.
- Restructuring uses a proposal/approval workflow. Preparing a proposal does not activate it.
- Approval rechecks the loan status, current schedule version, current balance components and exact active-schedule snapshot.
- If a payment or other balance/schedule change occurred after the proposal, approval fails as stale and the current schedule remains unchanged.
- Rejection permanently records the decision without altering the active schedule.
- Approved restructuring creates permanent loan status history and a zero-value customer statement event documenting the schedule change.
- Restructuring itself moves no money and does not modify the customer's total outstanding balance.

## Database changes

Migration: `2026_08_12_150000_create_early_settlement_and_restructuring.php`

Created:
- `loan_early_settlements`
- `loan_restructurings`
- `loan_restructuring_documents`

Changed:
- `loan_installments`
  - `schedule_version`
  - `is_active`
  - `loan_restructuring_id`
  - version-aware installment uniqueness
- `loans`
  - `current_schedule_version`

## Permissions

Added:
- `loans.adjustments.view`
- `loans.settlement.execute`
- `loans.settlement.adjust`
- `loans.restructure.create`
- `loans.restructure.approve`

Role assignments separate viewing, settlement execution, settlement adjustment, restructuring preparation and restructuring approval.

## User interface

Added a branch-scoped **Loan Adjustments** workspace with:
- active loans eligible for Step 14 actions
- completed early-settlement history
- restructuring request history
- backend settlement quote screen
- permanent settlement detail screen
- restructuring proposal form
- backend restructuring preview
- side-by-side previous/proposed schedule review
- supporting-document access
- approval/rejection controls

The workspace is linked in the Operations navigation and follows the existing standardized table/form patterns.

## Audit and safety controls

Audit events include:
- `loan_early_settlement.executed`
- `loan_restructuring.requested`
- `loan_restructuring.approved`
- `loan_restructuring.rejected`

Financial posting, schedule activation, statements, status changes and collateral readiness use database transactions and locking where applicable.

## Verification

Final functional CI before documentation:
- Fresh migrations: PASS
- Seeders: PASS
- Full Laravel test suite: **113 passed**
- Assertions: **1,020**
- Step 1–13 regression tests: PASS
- Step 14 feature tests: **7 passed**

Step 14 tests cover:
1. Early settlement financial posting, loan closure and collateral readiness.
2. Settlement-adjustment permission, principal protection and balanced accounting.
3. Penalty-inclusive settlement and duplicate-execution protection.
4. Schedule preservation, supporting documents and approved schedule versioning.
5. Stale restructuring protection after an intervening balance change.
6. Rejected restructuring preserving the existing schedule.
7. Permissions, branch isolation, standardized UI and retired-schedule reminder protection.

## Remaining Step 14 work

None.

## Next roadmap module

**Step 15 — Loan Write-Off**.

No Step 15 write-off behavior was implemented as part of Step 14.
