[HARD][REPAYMENTS] Build deterministic repayment schedule, allocation, and arrears engine

[Obiajulu-gif]

Overview

Implement a domain engine that generates repayment schedules and deterministically allocates every driver payment across due installments, arrears, fees, principal, and overpayment.

Problem

Loan records contain monthly/weekly payment fields, while repayment handling must support partial payments, late payments, overpayments, missed periods, and ownership completion. Without a single allocation engine, dashboards and balances can disagree about what is due and how a payment was applied.

Scope

• Add installment/schedule models generated from contract terms.
• Support weekly and monthly schedules, start dates, grace periods, and final installment adjustments.
• Define a documented allocation order for arrears, current installment, approved fees/penalties, principal, and excess credit.
• Handle partial, exact, late, duplicate, and overpayments.
• Recalculate next due date, outstanding balance, arrears days, and ownership progress.
• Keep payment application idempotent by gateway/reference ID.
• Add reversal/correction support without deleting payment history.
• Provide a schedule regeneration/check command for legacy contracts.

Edge cases

• leap years and month-end dates
• payment received before contract activation
• multiple payments on the same day
• payment larger than remaining contract balance
• reversed provider charge
• completed contract receiving another webhook
• schedule rule changes after a contract starts

Test requirements

Use table-driven tests for the edge cases above, plus property/invariant tests proving:

• allocated amount always equals accepted payment amount
• installment paid amounts never become negative
• remaining principal never drops below zero
• duplicate references do not allocate twice
• final ownership completion happens exactly once

Acceptance criteria

• Schedules are generated from immutable contract terms.
• Every payment has a transparent allocation breakdown.
• Arrears and next-due calculations are deterministic.
• Overpayments are capped and excess is handled explicitly.
• Reversals create compensating records.
• Existing repayment services and dashboards use the new engine.
• Tests, migration/check scripts, and contributor docs are included.

Difficulty

Hard

[zeemscript]

Hello @maintainer, I’ve gone through the requirements and I’m confident I can implement a proper solution that matches the acceptance criteria. Kindly assign this issue to me.