Overview
Implement the backend engine for calculating, approving, posting, and reversing investor distributions from vehicle-pool repayment proceeds.
Problem
Payouts must be deterministic and auditable. Calculating from current ownership after the fact can incorrectly include late investors, exclude transferred positions, or produce rounding differences that make distributed totals exceed available funds.
Scope
- Create payout periods and immutable ownership snapshots at a defined cutoff.
- Calculate each investor’s entitlement using integer minor units and a documented rounding/remainder policy.
- Account for platform fees, reserves, taxes/withholding placeholders, prior adjustments, and available cash.
- Support
draft, calculated, approved, processing, paid, partially_failed, reversed, and cancelled states.
- Separate calculation from approval and execution.
- Add maker-checker controls so the calculator cannot approve a payout where appropriate.
- Post approved distributions through the ledger and durable job system.
- Handle failed recipient payouts, holds, retries, and reversals without recalculating successful recipients.
- Prevent the same repayment proceeds from funding more than one distribution.
Acceptance criteria
- Investor allocations plus fees, reserves, and rounding remainder equal the distributable total exactly.
- Re-running calculation with unchanged snapshot produces the same result.
- Ownership changes after cutoff do not alter the approved distribution.
- Duplicate approval or execution does not double-pay.
- Failed recipients can be retried independently.
- Every stage is auditable and admin-authorized.
Tests required
Cover uneven shares, rounding remainder, zero entitlement, changed ownership after snapshot, insufficient funds, duplicate execution, partial provider failure, retry, hold, cancellation, and reversal.
Documentation
Include worked allocation examples and payout-state diagrams.
Overview
Implement the backend engine for calculating, approving, posting, and reversing investor distributions from vehicle-pool repayment proceeds.
Problem
Payouts must be deterministic and auditable. Calculating from current ownership after the fact can incorrectly include late investors, exclude transferred positions, or produce rounding differences that make distributed totals exceed available funds.
Scope
draft,calculated,approved,processing,paid,partially_failed,reversed, andcancelledstates.Acceptance criteria
Tests required
Cover uneven shares, rounding remainder, zero entitlement, changed ownership after snapshot, insufficient funds, duplicate execution, partial provider failure, retry, hold, cancellation, and reversal.
Documentation
Include worked allocation examples and payout-state diagrams.