# LendCore Finalization Blind Spot Roadmap

## Purpose

This roadmap addresses the most critical finalization blind spots around loan settlement, fines, arrears, and dues. The focus is to make these values clear in every relevant loan view, preserve them correctly through legacy importation, and ensure they remain dynamic and auditable when fines are waived or payments are applied.

### Client clarification

The fine amount is calculated and stored up to the point of installment allocation. The allocation logic must prioritize the installment amount first, preserve the penalty amount as an outstanding obligation, and clear penalties only after the installment balance has been settled. Admins should remain able to waive fines independently.

## Core Objectives

1. Make fines, arrears, and dues unambiguous across all loan-related views.
2. Ensure imported legacy loans carry forward these values consistently and can be resolved later through payment, waiver, or automated updates.
3. Provide a standard loan status and preview model for every loan.
4. Keep the fine system dynamic so admins can waive or reduce fines without breaking accounting behavior.
5. Define a stable payment allocation strategy when there is excess payment beyond the current installment and its fine.

---

## 1. Clarify Fine, Arrears, and Dues in All Relevant Views

### Problem

Different parts of the system currently expose loan obligations in ways that can appear inconsistent, especially where fines, overdue balances, and scheduled dues are shown together.

### Required Outcome

Every relevant screen must clearly separate and display:

- Current installment due
- Outstanding balance
- Fine amount due
- Total amount due including fine
- Arrears balance
- Dues balance
- Next due date
- Loan status summary

### Views and surfaces to cover

- Admin loan list
- Admin loan detail
- Admin repayment detail
- User repayment view
- Officer loan view
- Reports and exports
- API responses used by mobile/web clients

### Roadmap actions

- Standardize one shared summary object for loan due state.
- Display principal, fine, arrears, and total due in a consistent format.
- Ensure the same terms are used across UI, reports, and API payloads.
- Avoid mixing fine values into arrears totals unless explicitly labeled as such.

---

## 2. Legacy Importation and Consistency of Values

### Problem

Legacy-imported loans may carry values that are incomplete, inconsistent, or not fully resolved after import. This creates blind spots when later payments, waivers, or automated updates run.

### Required Outcome

Imported loans must be normalized so that:

- installment amounts, dues, balances, fines, and arrears are established consistently
- values remain resolvable and updateable after import
- paid, waived, or outstanding components can be recalculated safely
- the system can recover from incomplete or partially imported records without corrupting balances

### Roadmap actions

- Define a canonical import rule for each of the following:
  - installment amount due
  - outstanding balance
  - overdue amount
  - fine amount
  - days overdue
- On import, derive and persist a normalized due state for each repayment and loan.
- Support a reconciliation or repair routine that recalculates missing or inconsistent values without overwriting explicit payment history.
- Ensure imported data can be corrected later via:
  - payment posting
  - fine waiver or reduction
  - automated recalculation jobs

### Key guardrails

- Do not break existing database records during normalization.
- Preserve original import values where needed for auditability.
- Allow a safe reconciliation path that can be rerun idempotently.

---

## 3. Standard Loan Status and Preview Model

### Problem

Loans need a predictable lifecycle model so admins and users can immediately understand whether a loan is active, overdue, delinquent, completed, or otherwise resolved.

### Required Outcome

Every loan should have a standard status and a preview summary that includes:

- current status
- next due installment
- amount due now
- amount overdue
- fine outstanding
- total outstanding
- last payment date
- payment progress

### Recommended status model

- Pending review
- Active
- Overdue
- Defaulted
- Partially paid
- Fully paid
- Written off
- Closed

### Roadmap actions

- Define one canonical loan status calculation rule.
- Ensure the status is computed from the same data used for display.
- Add a loan preview panel that summarizes principal, fine, arrears, and overall health in one place.
- Make status derivation consistent in admin, officer, user, and report views.

---

## 4. Dynamic Fine Lifecycle and Admin Waiver Capability

### Problem

The fine mechanism must be operationally flexible. Admins need to be able to waive or reduce fines when appropriate without undermining the accounting logic or creating inconsistent state.

### Required Outcome

The fine system should be highly dynamic and support:

- automatic fine calculation based on overdue days and amount due
- per-repayment fine visibility
- manual waiver or reduction by admin
- clear status tracking for fines such as pending, waived, partially paid, fully paid
- future recalculation without double-counting

### Roadmap actions

- Keep fine calculation based on a clear rule such as:
  - fine amount = amount due × overdue days × daily rate
- Expose the formula and its inputs in admin views for transparency.
- Allow admin waiver/reduction actions that update the fine record without corrupting repayment history.
- Maintain a clear audit trail for any waiver, reduction, or reset.
- Ensure paid installments with remaining fine obligations are resolved correctly.

### Important rule

Waiving a fine should not erase the repayment history or the overdue context; it should simply change the active fine obligation state in a controlled, auditable way.

---

## 5. Payment Allocation Rules for Excess Payments

### Problem

When a payment exceeds the current installment balance and its associated fine, the system must allocate the surplus consistently and avoid double counting or hidden balances.

### Required Outcome

Payment allocation should work as follows:

1. First clear the current installment amount balance.
2. Preserve the penalty/fine amount and keep it outstanding until the installment amount is fully settled.
3. Only after the installment balance is cleared should the fine amount be considered for settlement.
4. If there is still excess, roll it to the next installment(s) in order.
5. Continue until the payment is fully allocated or all available dues are exhausted.
6. If any amount remains after all due installments and fines are covered, route it according to the business rule for surplus payments, such as guarantee deposit or suspense, rather than leaving it invisible.

### Roadmap actions

- Define a strict allocation order for payments.
- Make the allocation order visible in admin and repayment logs.
- Ensure each allocation step is stored in a traceable audit format.
- Prevent payment from being silently lost when it exceeds current dues.
- Document whether surplus should go to guarantee deposit, suspense, or a future installment.

### Recommended business rule

- Apply to the oldest active overdue installment first.
- Keep the associated fine outstanding and do not clear it before the installment balance is settled.
- Only after the installment amount is fully covered should the fine be considered for settlement.
- Then roll to the next installment if further balance remains.
- Only then consider deposit or suspense handling if a true surplus remains.

---

## 6. Implementation Phases

### Phase 1 — Foundation and Definition

- Agree the canonical rules for:
  - amount due
  - balance
  - arrears
  - fine
  - loan status
- Document the definitions in one place and align all modules to them.

### Phase 2 — Unified Due-State Model

- Create a single due-state summary that all views can consume.
- Expose it in admin, user, officer, report, and API layers.

### Phase 3 — Legacy Import Reconciliation

- Normalize imported loans and repayments.
- Recalculate missing values without breaking historical records.
- Normalize legacy numeric formats during import and ensure CSV `paid` values drive summary reconciliation.
- Keep the fix scoped to import logic and avoid any database schema changes.
- Make repair and reconciliation jobs repeatable.

### Phase 4 — Fine Management Workflow

- Add a robust fine lifecycle with pending, waived, paid, and partial states.
- Allow admin waiver and reduction actions.
- Make fine values visible and easy to understand.

### Phase 5 — Payment Allocation and Surplus Handling

- Implement deterministic allocation logic.
- Ensure excess payments roll forward correctly.
- Keep an auditable trail of every allocation.

### Phase 6 — Reporting and UX Hardening

- Ensure all reports and exports reflect the same due/fine/arrears logic.
- Make standard loan previews prominent in the UI.
- Introduce review screens for reconciliation issues.

---

## 7. Acceptance Criteria

The roadmap is complete when:

- all loan views clearly show principal due, fines, arrears, and total due
- legacy-imported loans have consistent due and fine values
- fines can be waived or reduced by admin without breaking repayment state
- excess payments are allocated predictably and visibly
- every loan has a standard status and preview summary
- reports and exports remain consistent with the same rules

---

## 8. Priority Order

1. Standardize due/fine/arrears presentation across all views
2. Normalize legacy import values and make them repairable
3. Define a standard loan status and preview model
4. Make fine waiver and reduction fully dynamic and auditable
5. Define and enforce payment allocation rules for excess amounts
