feat(deposits,clients): FD Special auto-configuration, interest schedule projection, and minor-age backend mirror

Three related pieces of backend support for this session's FD Special (monthly interest payout) work, plus one more instance of the same transaction-ordering bug fixed elsewhere this session. 1. FD Special account creation/modification auto-configuration FD Special (fdType=SPECIAL) is a non-cumulative product: interest must post monthly and leave for a linked savings account, and maturity must auto-transfer the principal out -- regardless of whatever compounding/ posting period or maturity instruction the request otherwise carries. Previously none of this was enforced, so a SPECIAL account could be created with e.g. quarterly compounding, or a later "modify application" request could silently unset transferInterestToLinkedAccount / the maturity instruction / the linked account by mere omission of those fields from the payload, while the account kept displaying as "FD Special". - DepositAccountAssembler: on create, forces interestCompoundingPeriodType and interestPostingPeriodType to MONTHLY, transferInterestToSavings to true, transferToSavingsId to the (now required) linked savings account, and accountOnClosureType to TRANSFER_TO_SAVINGS, whenever fdType is SPECIAL. Throws a clear domain error if no linked account was selected. - DepositAccountTermAndPreClosure: new forceMonthlyPayoutToLinkedSavings(), re-applying those same three standing-instruction fields. - DepositApplicationProcessWritePlatformServiceJpaRepositoryImpl: calls the equivalent re-enforcement on every modify-application request for a SPECIAL account, after the linked-account resolution in that same method has settled what account (if any) ends up linked. 2. FD Special projected interest schedule (engine + API) Staff/customers previously only saw a flat rate/12 approximation of monthly interest. Added a real, engine-computed month-by-month schedule: - DepositAccountWritePlatformService(Impl): new retrieveProjectedInterestSchedule(), running the same PostingPeriod engine the real maturity calculation uses (FixedDepositAccount# projectInterestSchedule), side-effect-free (@Transactional(readOnly)), clipping the last period's displayed end-date to maturityDate-1 (the engine otherwise rounds it out to the next calendar boundary even when maturity falls partway through), and flagging each period "paid" by matching real posted-interest transaction dates. - FixedDepositAccountsApiResource: computes and attaches the schedule, plus server-computed totalProjectedInterest/totalValueAtMaturity, to the FD template response for SPECIAL accounts only. - FixedDepositAccountData / DepositsApiConstants: carrier fields and response-parameter whitelist entries for the three new fields. 3. Minor-age threshold: backend now matches the frontend's shared constant Companion to this session's frontend minor-age-threshold change (18 -> 10, see client-age.util.ts). ClientKycApiResource's minor detection (which gates the required-KYC-document list, including whether PAN is mandatory) was still hardcoded to age < 18. Added ClientApiConstants.MINOR_AGE_THRESHOLD (10) and SENIOR_CITIZEN_AGE_ THRESHOLD (60) as the backend's own named constants, and switched the KYC endpoint to use MINOR_AGE_THRESHOLD, so the two sides can't silently disagree on who counts as a minor. 4. SavingsAccountTransactionComparator: same-date tie-break fixes another instance of this session's core reversal bug For a Special FD's interest-transfer sweep, the withdrawal shares the exact transaction_date of the interest posting it pays out. When that posting is reversed and recreated, the new posting transaction gets a higher id than the already-existing withdrawal; the comparator's id-order tiebreaker then sorted the withdrawal before the new posting, which understated the running balance shown between them (e.g. showing Rs.99,901.39 instead of Rs.100,000.00 immediately after the pair). Added an explicit tiebreaker so a same-date, same-createdDate interest posting always sorts before a withdrawal/debit. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-08-26 19:02:17 +05:30
parent a42a874811
commit 72221f704d
11 changed files with 236 additions and 9 deletions
@@ -182,6 +182,31 @@ public final class FixedDepositAccountData extends DepositAccountData {
        this.renewalHistory = renewalHistory;
    }

+    /**
+     * FD Special only: the real, engine-computed interest schedule across the account's whole term -- one entry
+     * per posting period (fromDate, toDate, interestAmount) -- so staff/customers can see exactly how much
+     * interest is projected to post each month instead of a flat rate/12 approximation. Null for every other
+     * FD type (see FixedDepositAccountsApiResource#retrieveOne).
+     */
+    private java.util.List<java.util.Map<String, Object>> projectedInterestSchedule;
+    private BigDecimal totalProjectedInterest;
+    private BigDecimal totalValueAtMaturity;
+
+    public void setProjectedInterestSchedule(final java.util.List<java.util.Map<String, Object>> projectedInterestSchedule) {
+        this.projectedInterestSchedule = projectedInterestSchedule;
+    }
+
+    /**
+     * Server-computed sum of projectedInterestSchedule, and principal + that sum -- the same "what does the
+     * customer end up with overall" total the account view shows, computed once here instead of the
+     * frontend re-summing the schedule array itself, so there is a single source of truth (matching how
+     * maturityAmount itself already works).
+     */
+    public void setProjectedInterestTotals(final BigDecimal totalProjectedInterest, final BigDecimal totalValueAtMaturity) {
+        this.totalProjectedInterest = totalProjectedInterest;
+        this.totalValueAtMaturity = totalValueAtMaturity;
+    }
+
    // CBS account-level fields (stored per-account in m_savings_account)
    private String accountStatus;
    private String modeOfOperation;
@@ -340,6 +340,19 @@ public class DepositAccountTermAndPreClosure extends AbstractPersistableCustom<L
        this.onAccountClosureType = onClosureType.getValue();
    }

+    /**
+     * Re-applies the three standing-instruction fields that make an FD Special account pay interest out
+     * monthly and transfer the principal automatically at maturity, overriding whatever a modify-application
+     * request just changed them to. Called by {@code FixedDepositAccount#modifyApplication} for SPECIAL-type
+     * accounts, since {@link #update(JsonCommand, DataValidatorBuilder)} otherwise lets any of these three be
+     * unset -- including by mere omission of maturityInstructionId/transferToSavingsId from the request body.
+     */
+    public void forceMonthlyPayoutToLinkedSavings(final Long transferToSavingsId) {
+        this.transferInterestToLinkedAccount = true;
+        this.transferToSavingsAccountId = transferToSavingsId;
+        this.onAccountClosureType = DepositAccountOnClosureType.TRANSFER_TO_SAVINGS.getValue();
+    }
+
    /**
     * Copies the standing instructions -- maturity instruction, its payout target and the interest-transfer flag -- from
     * the term being renewed.
@@ -36,6 +36,22 @@ public class SavingsAccountTransactionComparator implements Comparator<SavingsAc
        if (result != 0) {
            return result;
        }
+        // For same date and same createdDate: interest postings must always be processed
+        // before withdrawals/debits. This is critical for Special FD (Non-Cumulative)
+        // accounts where the interest-transfer sweep withdrawal carries the same
+        // transaction_date as the interest posting it pays out.  When the original posting
+        // is reversed and a new one is created the new posting gets a higher ID than the
+        // old withdrawal.  Without this tiebreaker the comparator falls through to
+        // ID-order, placing the withdrawal before the new posting and causing the running
+        // balance to dip incorrectly (e.g. ₹99,901.39 instead of ₹100,000.00).
+        boolean o1IsPosting = o1.isInterestPostingAndNotReversed();
+        boolean o2IsPosting = o2.isInterestPostingAndNotReversed();
+        if (o1IsPosting && !o2IsPosting) {
+            return -1; // interest posting before withdrawal/debit
+        }
+        if (!o1IsPosting && o2IsPosting) {
+            return 1; // withdrawal/debit after interest posting
+        }
        if (o1.getId() != null && o2.getId() != null) {
            return o1.getId().compareTo(o2.getId());
        }
@@ -19,6 +19,8 @@
 package org.apache.fineract.portfolio.savings.service;

 import java.time.LocalDate;
+import java.util.List;
+import java.util.Map;
 import org.apache.fineract.infrastructure.core.api.JsonCommand;
 import org.apache.fineract.infrastructure.core.data.CommandProcessingResult;
 import org.apache.fineract.organisation.office.domain.Office;
@@ -43,6 +45,8 @@ public interface DepositAccountWritePlatformService {

    CommandProcessingResult calculateInterest(Long savingsId, DepositAccountType depositAccountType);

+    List<Map<String, Object>> retrieveProjectedInterestSchedule(Long savingsId, DepositAccountType depositAccountType);
+
    CommandProcessingResult postInterest(Long savingsId, DepositAccountType depositAccountType);

    CommandProcessingResult undoFDTransaction(Long savingsId, Long transactionId, boolean allowAccountTransferModification);