diff --git a/fineract-core/src/main/java/org/apache/fineract/infrastructure/jobs/service/JobName.java b/fineract-core/src/main/java/org/apache/fineract/infrastructure/jobs/service/JobName.java
index ba41bb64c..93e097cc6 100644
--- a/fineract-core/src/main/java/org/apache/fineract/infrastructure/jobs/service/JobName.java
+++ b/fineract-core/src/main/java/org/apache/fineract/infrastructure/jobs/service/JobName.java
@@ -43,6 +43,7 @@ public enum JobName {
UPDATE_SAVINGS_DORMANT_ACCOUNTS("Update Savings Dormant Accounts"), //
APPLY_KYC_EXPIRY_RESTRICTIONS("Apply KYC Expiry Restrictions"), //
SAVINGS_DAILY_INTEREST("Savings Daily Interest Accrual And Posting"), //
+ SAVINGS_INTEREST_POSTING_REPORT("Generate Savings Interest Posting Report"), //
ADD_PERIODIC_ACCRUAL_ENTRIES_FOR_LOANS_WITH_INCOME_POSTED_AS_TRANSACTIONS(
"Add Accrual Transactions For Loans With Income Posted As Transactions"), //
EXECUTE_REPORT_MAILING_JOBS("Execute Report Mailing Jobs"), //
diff --git a/fineract-provider/src/main/java/org/apache/fineract/accounting/glaccount/validation/GLAccountTransactionGuard.java b/fineract-provider/src/main/java/org/apache/fineract/accounting/glaccount/validation/GLAccountTransactionGuard.java
index 08b7cea5a..0c324de1e 100644
--- a/fineract-provider/src/main/java/org/apache/fineract/accounting/glaccount/validation/GLAccountTransactionGuard.java
+++ b/fineract-provider/src/main/java/org/apache/fineract/accounting/glaccount/validation/GLAccountTransactionGuard.java
@@ -55,4 +55,49 @@ public final class GLAccountTransactionGuard {
"glAccountId", glAccountId);
}
}
+
+ /**
+ * Refuses to draw more out of a holding account than it holds.
+ *
+ *
+ * A suspense or sundry account exists to hold money on its way somewhere else, so what is in it
+ * is the whole of what can come out. Drawing more leaves it with a negative balance, and a
+ * liability with a negative balance is not a small number - it says the bank owes less than
+ * nothing, which is not a state that exists. It also breaks the balance sheet by the overdraw,
+ * and the figure is small enough to sit unnoticed inside a head that totals positive.
+ *
+ *
+ * Checked here rather than at each call site because the accounts this protects are reached by
+ * several features posting directly through JDBC, and a rule enforced in one of them is a rule
+ * the next one added will not have.
+ *
+ * @param glAccountId the account being drawn on.
+ * @param amount how much the caller wants to take out.
+ * @param what the account's role in the caller's own words, for the message a clerk reads.
+ */
+ public static void assertSufficientBalance(final JdbcTemplate jdbcTemplate, final Long glAccountId,
+ final java.math.BigDecimal amount, final String what) {
+ if (glAccountId == null || amount == null || amount.signum() <= 0) {
+ return;
+ }
+ // Credits less debits: these are liability-natured holding accounts, so the balance is what
+ // is still owed onward. Reversed entries and the entries they reverse both drop out - a
+ // reversal pair nets to nothing, and counting either side alone moves the balance by the
+ // whole amount.
+ final java.math.BigDecimal held = jdbcTemplate.queryForObject("""
+ SELECT COALESCE(SUM(CASE WHEN type_enum = 1 THEN amount ELSE -amount END), 0)
+ FROM acc_gl_journal_entry
+ WHERE account_id = ?
+ AND (reversed IS NULL OR reversed = false)
+ AND id NOT IN (SELECT reversal_id FROM acc_gl_journal_entry WHERE reversal_id IS NOT NULL)
+ """, java.math.BigDecimal.class, glAccountId);
+ final java.math.BigDecimal balance = held == null ? java.math.BigDecimal.ZERO : held;
+ if (balance.compareTo(amount) < 0) {
+ throw new PlatformDataIntegrityException("error.msg.glaccount.insufficient.balance",
+ what + " holds " + balance + " but " + amount + " was asked of it. Drawing the "
+ + "difference would leave the account with a negative balance, which a "
+ + "holding account cannot have.",
+ "glAccountId", glAccountId, amount);
+ }
+ }
}
diff --git a/fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/AccountingProcessorHelper.java b/fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/AccountingProcessorHelper.java
index b5c375a61..1ee9fe013 100644
--- a/fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/AccountingProcessorHelper.java
+++ b/fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/AccountingProcessorHelper.java
@@ -42,6 +42,7 @@ import org.apache.fineract.accounting.financialactivityaccount.domain.FinancialA
import org.apache.fineract.accounting.financialactivityaccount.domain.FinancialActivityAccountRepositoryWrapper;
import org.apache.fineract.accounting.glaccount.domain.GLAccount;
import org.apache.fineract.accounting.glaccount.domain.GLAccountRepository;
+import org.apache.fineract.accounting.glaccount.domain.GLAccountType;
import org.apache.fineract.accounting.journalentry.data.ChargePaymentDTO;
import org.apache.fineract.accounting.journalentry.data.ClientChargePaymentDTO;
import org.apache.fineract.accounting.journalentry.data.ClientTransactionDTO;
@@ -666,30 +667,56 @@ public class AccountingProcessorHelper {
final GLAccount paidAccount = Optional.ofNullable(namedSavingsGlAccount(savingsProductId, SAVINGS_INTEREST_PAID_MAPPING))
.orElse(payableAccount);
- // Stage 1: the expense is recognised against whatever the liability sits in right now -- the
- // named Payable account if the product has one, or straight against Savings Control if it
- // doesn't. This was missing entirely: every product, configured or not, posted zero journal
- // entries for interest until this leg existed, since a product with no Payable/Paid names
- // configured also collapsed stages 2 and 3 below into a same-account no-op with nothing else
- // to post in their place.
- postSavingsLeg(office, currencyCode, interestOnSavingsAccount, payableAccount, savingsId, transactionId, transactionDate, amount,
+ // A product that names no payable falls back to Savings Control above. The chain below would
+ // then open with Dr Savings Control / Cr Interest On Savings and close with its exact
+ // reverse, the two cancelling: the expense never charged and the member never credited. Such
+ // a product has no liability to draw down, so it keeps the single pair it always posted.
+ if (payableAccount.getId().equals(controlAccount.getId())) {
+ postSavingsLeg(office, currencyCode, interestOnSavingsAccount, controlAccount, savingsId, transactionId, transactionDate,
+ amount, isReversal);
+ return;
+ }
+
+ // The interest is charged to expense and raised as a liability first, for whatever part of
+ // it no accrual has already covered.
+ //
+ // The chain below draws the payable DOWN, so it assumes an accrual already credited it for
+ // the period. Where none ran - a product posting on cash accounting, or a period the accrual
+ // job never covered - the payable went negative by the interest and the expense netted to
+ // nothing across the next two legs, leaving the charge off the P&L entirely. A liability
+ // account cannot hold a negative balance: the bank does not owe less than nothing.
+ //
+ // So the shortfall is raised here rather than assumed away. Where the accrual DID run, the
+ // payable already carries the interest and this leg writes nothing - the balance below is
+ // enough, and raising it again would double the liability.
+ //
+ // Only a liability payable is topped up. A bank that maps an expense GL as the payable books
+ // the cost there directly: payableBalance reads credit minus debit, so an expense's normal
+ // debit balance would come back negative and every posting would raise a shortfall larger
+ // than the interest itself.
+ final boolean payableIsLiability = GLAccountType.LIABILITY.getValue().equals(payableAccount.getType());
+ final BigDecimal alreadyAccrued = payableBalance(office, payableAccount, currencyCode);
+ final BigDecimal shortfall = amount.subtract(alreadyAccrued).max(BigDecimal.ZERO);
+ if (!isReversal && payableIsLiability && shortfall.compareTo(BigDecimal.ZERO) > 0) {
+ // Dr Interest On Savings (the expense) / Cr Payable - the accrual that should have run.
+ postSavingsLeg(office, currencyCode, interestOnSavingsAccount, payableAccount, savingsId, transactionId, transactionDate,
+ shortfall, false);
+ }
+
+ // Out of the payable, into the interest-paid account the product names.
+ postSavingsLeg(office, currencyCode, payableAccount, interestOnSavingsAccount, savingsId, transactionId, transactionDate, amount,
isReversal);
- // The interest expense is not raised again here. It was just raised above, and this posting
- // only settles that recognised debt onward to where it is actually paid out from -- raising
- // the expense a second time would put the same interest on the P&L twice.
- //
- // Stage 2: the liability moves from the payable to the account it is paid out of. Where the
- // product names no paid account both resolve to the payable and this says nothing, so it is
- // skipped and the payout comes straight out of the payable.
- final boolean payableIsPaid = payableAccount.getId().equals(paidAccount.getId());
- if (!payableIsPaid) {
- postSavingsLeg(office, currencyCode, payableAccount, paidAccount, savingsId, transactionId, transactionDate, amount,
+ // A separate paid account, where the product names one, sits between interest-paid and the
+ // member; otherwise the payout leaves straight from interest-paid.
+ final boolean hasSeparatePaidAccount = !payableAccount.getId().equals(paidAccount.getId());
+ if (hasSeparatePaidAccount) {
+ postSavingsLeg(office, currencyCode, interestOnSavingsAccount, paidAccount, savingsId, transactionId, transactionDate, amount,
isReversal);
}
- // Stage 3: into the member's own balance.
- final GLAccount payoutFromAccount = payableIsPaid ? payableAccount : paidAccount;
+ // Into the member's own balance.
+ final GLAccount payoutFromAccount = hasSeparatePaidAccount ? paidAccount : interestOnSavingsAccount;
postSavingsLeg(office, currencyCode, payoutFromAccount, controlAccount, savingsId, transactionId, transactionDate, amount,
isReversal);
}
@@ -733,6 +760,38 @@ public class AccountingProcessorHelper {
*
* @return the account, or null where the product does not configure this name
*/
+ /**
+ * What the interest payable account currently holds for this office, on its own liability side.
+ *
+ *
+ * Read so an interest posting can tell an accrual that already ran from one that did not. The
+ * posting chain draws the payable down; where nothing had raised it, the account went negative
+ * and the expense netted to nothing, so the charge never reached the P&L at all. The caller
+ * raises only the shortfall, which is nil when the accrual did run.
+ *
+ *
+ * Credits less debits, because a payable is a liability: the balance is what the bank still
+ * owes. Floored at zero by the caller rather than here - a negative balance is a real state to
+ * report, and the caller's arithmetic needs the true figure, not a clamped one.
+ */
+ private BigDecimal payableBalance(final Office office, final GLAccount payableAccount, final String currencyCode) {
+ if (payableAccount == null || payableAccount.getId() == null) {
+ return BigDecimal.ZERO;
+ }
+ // Reversed entries and the entries they reverse are both excluded: a reversal pair nets to
+ // nothing, and counting either side alone would move the balance by the whole amount.
+ final BigDecimal balance = jdbcTemplate.queryForObject("""
+ SELECT COALESCE(SUM(CASE WHEN type_enum = 1 THEN amount ELSE -amount END), 0)
+ FROM acc_gl_journal_entry
+ WHERE account_id = ?
+ AND office_id = ?
+ AND currency_code = ?
+ AND (reversed IS NULL OR reversed = false)
+ AND id NOT IN (SELECT reversal_id FROM acc_gl_journal_entry WHERE reversal_id IS NOT NULL)
+ """, BigDecimal.class, payableAccount.getId(), office.getId(), currencyCode);
+ return balance == null ? BigDecimal.ZERO : balance;
+ }
+
private GLAccount namedSavingsGlAccount(final Long savingsProductId, final String accountName) {
if (savingsProductId == null) {
return null;
diff --git a/fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/AccrualBasedAccountingProcessorForSavings.java b/fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/AccrualBasedAccountingProcessorForSavings.java
index 5092daed6..82d124e58 100644
--- a/fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/AccrualBasedAccountingProcessorForSavings.java
+++ b/fineract-provider/src/main/java/org/apache/fineract/accounting/journalentry/service/AccrualBasedAccountingProcessorForSavings.java
@@ -180,18 +180,21 @@ public class AccrualBasedAccountingProcessorForSavings implements AccountingProc
// "amount > 0" guard) left the FD subledger showing the clawback while the GL never
// recorded it, silently going out of sync. Treating a negative amount as a mirror-image
// reversal -- positive magnitude, debit/credit legs swapped, same mechanism
- // createCashBasedJournalEntriesAndReversalsForSavings already uses for isReversal -- keeps
- // the two in sync instead. See CashBasedAccountingProcessorForSavings for the same fix on
- // the cash-based path.
+ // createInterestPostingJournalEntriesForSavings already uses for isReversal -- keeps the two
+ // in sync instead. See CashBasedAccountingProcessorForSavings for the same fix on the
+ // cash-based path.
final int amountSign = savingsTransactionDTO.getAmount().compareTo(BigDecimal.ZERO);
if (amountSign != 0) {
final boolean isClawback = amountSign < 0;
final BigDecimal postingAmount = isClawback ? amount.abs() : amount;
final boolean effectiveIsReversal = isReversal ^ isClawback;
- this.helper.createCashBasedJournalEntriesAndReversalsForSavings(office, currencyCode,
- AccrualAccountsForSavings.INTEREST_PAYABLE.getValue(), AccrualAccountsForSavings.SAVINGS_CONTROL.getValue(),
- savingsProductId, paymentTypeId, savingsId, transactionId, transactionDate, postingAmount,
- effectiveIsReversal);
+ // Routed through the same helper the cash processor uses, so a posting states
+ // the whole chain the product is configured for -- out of the payable, through
+ // the interest-paid account, into the member's balance -- rather than the single
+ // payable-to-control pair that used to be here, which skipped interest-paid
+ // entirely and left the expense off the P&L.
+ this.helper.createInterestPostingJournalEntriesForSavings(office, currencyCode, savingsProductId, paymentTypeId,
+ savingsId, transactionId, transactionDate, postingAmount, effectiveIsReversal);
}
}
diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/branchday/api/BranchDayRegisterApiResource.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/branchday/api/BranchDayRegisterApiResource.java
index 31ac82030..71920ecff 100644
--- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/branchday/api/BranchDayRegisterApiResource.java
+++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/branchday/api/BranchDayRegisterApiResource.java
@@ -46,6 +46,8 @@ import org.apache.fineract.infrastructure.core.service.DateUtils;
import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
import org.apache.fineract.portfolio.cashreport.service.VaultPositionService;
import org.apache.fineract.portfolio.denominationmaster.service.CountedCashLedger;
+import org.apache.fineract.portfolio.savings.dailyinterest.SavingsDailyInterestOrchestrator;
+import org.apache.fineract.portfolio.savings.dailyinterest.SavingsInterestPostingReportService;
import org.apache.fineract.useradministration.domain.AppUser;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.stereotype.Component;
@@ -73,6 +75,8 @@ public class BranchDayRegisterApiResource {
private final PlatformSecurityContext context;
private final FromJsonHelper fromJsonHelper;
private final VaultPositionService vaultPositionService;
+ private final SavingsInterestPostingReportService interestPostingReportService;
+ private final SavingsDailyInterestOrchestrator savingsDailyInterestOrchestrator;
private final Gson gson = new Gson();
// ── GET /v1/branchday ── the register itself ──────────────────────────────
@@ -589,6 +593,34 @@ public class BranchDayRegisterApiResource {
"Business day " + businessDate + " is already closed.");
}
+ // ── This branch's savings interest reports must be approved before it closes ──
+ // Not overridable by a force-close reason: the branch posts its own customers' interest when
+ // it closes, and a report nobody approved has nothing to post, so they would go unpaid.
+ final List interestPending = interestPostingReportService.reportsBlockingDayClose(officeId, businessDate);
+ if (!interestPending.isEmpty()) {
+ throw new PlatformDataIntegrityException("error.msg.branchday.interest.report.pending",
+ "Cannot close the day — this branch's savings interest posting report is not approved for: "
+ + String.join(", ", interestPending)
+ + ". Approve it under Reports → Interest Posting Reports, then close the day.");
+ }
+
+ // ── The head office closes last ──
+ // Every branch that opened the day closes first and posts its own interest; a branch that
+ // never opened is not waited for.
+ final boolean isHeadOffice = interestPostingReportService.isHeadOffice(officeId);
+ if (isHeadOffice) {
+ final List stillOpen = jdbcTemplate.queryForList("""
+ SELECT o.name FROM m_branch_day_register r JOIN m_office o ON o.id = r.office_id
+ WHERE r.business_date = ? AND r.closed_at IS NULL AND r.office_id <> ?
+ ORDER BY o.name
+ """, String.class, Date.valueOf(businessDate), officeId);
+ if (!stillOpen.isEmpty()) {
+ throw new PlatformDataIntegrityException("error.msg.branchday.branches.still.open",
+ "Cannot close the head office yet — these branches have not closed the day: " + String.join(", ", stillOpen)
+ + ". The head office closes last.");
+ }
+ }
+
// ── Ensure every cashier holding cash has been reconciled AND settled ──
// Find all cashiers under tellers belonging to this office, check if they have a cash position,
// and if so, verify reconciliation and settlement records exist for the business date.
@@ -687,6 +719,28 @@ public class BranchDayRegisterApiResource {
final BigDecimal bookCash = (BigDecimal) bookBreakdown(officeId, businessDate).get("expectedCash");
final BigDecimal difference = closingCash != null ? closingCash.subtract(bookCash) : null;
+ // ── The branch posts its own approved savings interest as it closes ──
+ // The head office also posts what it approved for branches that did not open today. Entries
+ // are raised in the customers' own branch either way.
+ //
+ // Posted here, before the close is written, and synchronously, so the outcome is never
+ // silent: each report posts in a transaction of its own and commits, and if any fails the
+ // close is refused with the reason — the day stays open, the report stays APPROVED, and
+ // closing again once the cause is fixed posts it.
+ final List toPost = new ArrayList<>(interestPostingReportService.approvedReportIds(officeId, businessDate));
+ if (isHeadOffice) {
+ toPost.addAll(interestPostingReportService.approvedReportIdsOfBranchesNotOpened(businessDate, officeId));
+ }
+ if (!toPost.isEmpty()) {
+ log.info("Day close {}: office {} posting {} approved savings interest report(s)", businessDate, officeId, toPost.size());
+ final List interestFailures = savingsDailyInterestOrchestrator.postReports(toPost);
+ if (!interestFailures.isEmpty()) {
+ throw new PlatformDataIntegrityException("error.msg.branchday.interest.posting.failed",
+ "Cannot close the day — savings interest could not be posted: " + String.join("; ", interestFailures)
+ + ". The report is still approved; fix the cause and close the day again.");
+ }
+ }
+
// "closed_at IS NULL" in the WHERE, not just the read above: the already-closed check and
// this write are two separate statements, so two managers pressing Close at once (or one
// double-click) both got past the check. The second UPDATE then overwrote the first's
diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/clerkwithdrawal/api/ClerkShareWithdrawalRequestApiResource.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/clerkwithdrawal/api/ClerkShareWithdrawalRequestApiResource.java
index dc9690edf..da1a79dc7 100644
--- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/clerkwithdrawal/api/ClerkShareWithdrawalRequestApiResource.java
+++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/clerkwithdrawal/api/ClerkShareWithdrawalRequestApiResource.java
@@ -709,6 +709,21 @@ public class ClerkShareWithdrawalRequestApiResource {
+ "applied to it, so these shares have not actually been paid for and cannot be redeemed.");
}
+ // The Share Sundry account the redemption draws on must actually hold the money.
+ //
+ // collectionApplied above says A collection was applied to THIS account, not that the
+ // proceeds are still sitting in Sundry - the same holding account serves every share
+ // account, and an earlier redemption may already have drawn it down. Approving past that
+ // takes Sundry negative, which is a liability owing less than nothing, and the overdraw
+ // lands inside a balance-sheet head that totals positive, where it does not look wrong.
+ final BigDecimal redemptionValue = redemptionValueOf(shareAccountId, requestedShares);
+ if (redemptionValue != null) {
+ final Long productId = jdbcTemplate.queryForObject("SELECT product_id FROM m_share_account WHERE id = ?", Long.class,
+ shareAccountId);
+ GLAccountTransactionGuard.assertSufficientBalance(jdbcTemplate, resolveGl(productId, FA_SHARES_SUSPENSE), redemptionValue,
+ "The Share Sundry (Suspense) account");
+ }
+
final JsonObject payload = new JsonObject();
payload.addProperty("locale", "en");
payload.addProperty("dateFormat", "dd MMMM yyyy");
@@ -958,6 +973,33 @@ public class ClerkShareWithdrawalRequestApiResource {
* text is only unique so long as {@code m_share_account_transactions.id} never repeats, which a
* reset id sequence in a dev environment can violate.
*/
+ /**
+ * What a redemption of this many shares will draw out of Share Sundry.
+ *
+ *
+ * Priced at the unit price the member's own shares were issued at, which is the price the
+ * redemption itself uses. The product's nominal price is not consulted: a member who subscribed
+ * at an earlier price redeems at theirs, and pricing the guard differently from the posting
+ * would either block a redemption that fits or let one through that does not.
+ *
+ * @return the value, or null where no price can be established - the guard then stands aside
+ * rather than blocking on a figure it had to invent.
+ */
+ private BigDecimal redemptionValueOf(final Long shareAccountId, final Long requestedShares) {
+ if (shareAccountId == null || requestedShares == null || requestedShares <= 0) {
+ return null;
+ }
+ // The purchase that issued the holding - type 500. Its unit price is what the member paid.
+ final BigDecimal unitPrice = jdbcTemplate
+ .queryForList("""
+ SELECT unit_price FROM m_share_account_transaction
+ WHERE share_account_id = ? AND type_enum = 500 AND unit_price IS NOT NULL
+ ORDER BY id DESC LIMIT 1
+ """, BigDecimal.class, shareAccountId)
+ .stream().findFirst().orElse(null);
+ return unitPrice == null ? null : unitPrice.multiply(BigDecimal.valueOf(requestedShares));
+ }
+
private Long redeemDebitGlOf(final Long shareTransactionId) {
if (shareTransactionId == null) {
return null;
diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiFormAFilingApiResource.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiFormAFilingApiResource.java
index fdb524c9a..184a4f990 100644
--- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiFormAFilingApiResource.java
+++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiFormAFilingApiResource.java
@@ -166,12 +166,23 @@ public class RbiFormAFilingApiResource {
"The generated return must be supplied with the save.");
}
- final LocalDate periodStart = localDate(report, "fortnightStart");
- final LocalDate periodEnd = localDate(report, "fortnightEnd");
- final BigDecimal ndtl = decimal(report, "ndtlAmount");
- final BigDecimal required = decimal(report, "requiredAmount");
- final BigDecimal maintained = decimal(report, "maintainedAmount");
- final BigDecimal rate = decimal(report, "ratePercentage");
+ // The statutory form states its figures per column inside Part B rather than once at the
+ // top level, so the columns the saved LIST shows - NDTL, required, maintained - have to be
+ // read out of it. Without this a filed statutory return listed as a row of dashes, and the
+ // list could not be scanned for the one return somebody was looking for.
+ final boolean statutory = report.has("formCode") && !report.get("formCode").isJsonNull()
+ && "FORM_1_STATUTORY".equals(report.get("formCode").getAsString());
+
+ // The statutory form's period runs between its two fortnight closes, which is what the
+ // saved list prints as the row's period.
+ final LocalDate periodStart = statutory ? columnDate(report, 0) : localDate(report, "fortnightStart");
+ final LocalDate periodEnd = statutory ? columnDate(report, 1) : localDate(report, "fortnightEnd");
+ // The current fortnight's figures are the second column - the close the form is made up to.
+ final BigDecimal ndtl = statutory ? partFigure(report, "partA", "baseDateLiabilities") : decimal(report, "ndtlAmount");
+ final BigDecimal required = statutory ? partFigure(report, "partB", "required") : decimal(report, "requiredAmount");
+ final BigDecimal maintained = statutory ? partFigure(report, "partB", "maintained")
+ : decimal(report, "maintainedAmount");
+ final BigDecimal rate = statutory ? decimal(report, "crrPercentage") : decimal(report, "ratePercentage");
BigDecimal average = null;
if (report.has("maintenance") && report.get("maintenance").isJsonObject()) {
average = decimal(report.getAsJsonObject("maintenance"), "average");
@@ -302,4 +313,40 @@ public class RbiFormAFilingApiResource {
final String value = object.get(field).getAsString();
return value == null || value.isBlank() ? null : LocalDate.parse(value);
}
+
+ /**
+ * One of a statutory part's per-column figures, taken at the column the form is made up to.
+ *
+ * The form carries three columns and the saved list has one cell per figure, so it takes the
+ * second - the close the return reports. Index 1 rather than "the last": the third column is
+ * the base the ratios are charged on, not a later position, and listing it would show a
+ * requirement against liabilities from a fortnight nobody filed.
+ */
+ private static BigDecimal partFigure(final JsonObject report, final String part, final String field) {
+ if (!report.has(part) || !report.get(part).isJsonObject()) {
+ return null;
+ }
+ final JsonObject partObject = report.getAsJsonObject(part);
+ if (!partObject.has(field) || !partObject.get(field).isJsonArray()) {
+ return null;
+ }
+ final var values = partObject.getAsJsonArray(field);
+ if (values.size() < 2 || values.get(1).isJsonNull()) {
+ return null;
+ }
+ return values.get(1).getAsBigDecimal();
+ }
+
+ /** One of the statutory form's column dates, for the period a saved row reports. */
+ private static LocalDate columnDate(final JsonObject report, final int index) {
+ if (!report.has("columns") || !report.get("columns").isJsonArray()) {
+ return null;
+ }
+ final var columns = report.getAsJsonArray("columns");
+ if (columns.size() <= index || columns.get(index).isJsonNull()) {
+ return null;
+ }
+ final String value = columns.get(index).getAsString();
+ return value == null || value.isBlank() ? null : LocalDate.parse(value);
+ }
}
diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiReserveConfigApiResource.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiReserveConfigApiResource.java
index 9b07890e5..3b40943d3 100644
--- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiReserveConfigApiResource.java
+++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiReserveConfigApiResource.java
@@ -199,6 +199,7 @@ public class RbiReserveConfigApiResource {
ROLE_GROUP_LABELS.put("RESERVE", "Form 1 (CRR) & Form 9 (SLR)");
ROLE_GROUP_LABELS.put("OSS1", "OSS 1 — Return on Assets and Liabilities");
ROLE_GROUP_LABELS.put("OSS2", "OSS 2 — Return on Earnings");
+ ROLE_GROUP_LABELS.put("FORM9", "Form IX — Return on Assets and Liabilities (R408)");
for (final String role : ROLE_DESCRIPTIONS.keySet()) {
if (role.startsWith("OSS1_")) {
@@ -227,9 +228,15 @@ public class RbiReserveConfigApiResource {
*/
private static final List RATE_TYPES = List.of("CRR", "SLR", "SAVINGS_DEMAND");
- /** The four treatments a head can be given, each naming a branch the returns already have. */
+ /**
+ * The treatments a head can be given, each naming a branch the returns already have.
+ *
+ * ASSET is Form IX's, and is not ASSET_NET: that one is netted OFF the liability base to arrive
+ * at NDTL, this one is added INTO Total Assets. A Form IX asset given ASSET_NET would be
+ * subtracted from the liabilities of a return that has no such base.
+ */
private static final List ROLE_USAGES = List.of("LIABILITY", "ASSET_NET", "MAINTAINED", "SLR_ASSET",
- "MEMO");
+ "ASSET", "MEMO");
private static final Map USAGE_DESCRIPTIONS = new LinkedHashMap<>();
static {
@@ -243,6 +250,27 @@ public class RbiReserveConfigApiResource {
USAGE_DESCRIPTIONS.put("MEMO", "Shown on the return but entering no total");
}
+ /**
+ * How a head is consumed, in the terms of the return it belongs to.
+ *
+ * LIABILITY means two different things depending on the group. On Form 1 and Form 9 it says the
+ * head is added into the DTL base a ratio is charged on. On Form IX there is no ratio and no
+ * base: it says which SIDE OF THE BALANCE SHEET the head sits on. Describing both with the DTL
+ * wording would tell a Form IX filer their head feeds a calculation that does not exist on
+ * their return.
+ */
+ private static String usedBy(final String group, final String usage) {
+ if ("FORM9".equals(group)) {
+ return switch (usage == null ? "" : usage) {
+ case "LIABILITY" -> "Form IX — a liability; enters Total Liabilities";
+ case "ASSET" -> "Form IX — an asset; enters Total Assets";
+ case "MEMO" -> "Form IX — stated on the form but entering no total";
+ default -> usage;
+ };
+ }
+ return USAGE_DESCRIPTIONS.getOrDefault(usage, usage);
+ }
+
/** How each built-in role is treated, so the screen can describe built-ins and additions alike. */
private static final Map BUILT_IN_USAGE = new LinkedHashMap<>();
static {
@@ -390,11 +418,14 @@ public class RbiReserveConfigApiResource {
o.put("label", row.get("label"));
o.put("group", group);
o.put("groupLabel", ROLE_GROUP_LABELS.getOrDefault(group, group));
- o.put("usedBy", USAGE_DESCRIPTIONS.getOrDefault(usage, usage));
+ o.put("usedBy", usedBy(group, usage));
o.put("builtIn", false);
o.put("usage", usage);
- // A liability head carries the demand/time split; nothing else does.
- o.put("classified", "LIABILITY".equals(usage));
+ // A liability head carries the demand/time split; nothing else does. Not on Form IX,
+ // where the demand and time heads are separate lines of the form itself - asking for a
+ // class on top of that would let a head declared under 5(a) Fixed Deposits be marked
+ // DEMAND, which the form has no way to report.
+ o.put("classified", "LIABILITY".equals(usage) && !"FORM9".equals(group));
o.put("roleId", row.get("id"));
o.put("accounts", byKey.getOrDefault(key, new ArrayList<>()));
out.add(o);
diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiReserveReturnApiResource.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiReserveReturnApiResource.java
index ad11ff8f9..b8e2c98a7 100644
--- a/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiReserveReturnApiResource.java
+++ b/fineract-provider/src/main/java/org/apache/fineract/portfolio/rbireserve/api/RbiReserveReturnApiResource.java
@@ -30,10 +30,13 @@ import java.time.DayOfWeek;
import java.time.LocalDate;
import java.time.temporal.TemporalAdjusters;
import java.util.ArrayList;
+import java.util.HashSet;
import java.util.LinkedHashMap;
import java.util.List;
import java.util.Map;
+import java.util.Set;
import lombok.RequiredArgsConstructor;
+import org.apache.fineract.infrastructure.core.exception.PlatformDataIntegrityException;
import org.apache.fineract.infrastructure.core.service.DateUtils;
import org.apache.fineract.infrastructure.security.service.PlatformSecurityContext;
import org.springframework.jdbc.core.JdbcTemplate;
@@ -138,15 +141,23 @@ public class RbiReserveReturnApiResource {
@GET
@Path("form1")
public String form1(@QueryParam("reportingDate") final String reportingDateParam,
- @QueryParam("officeId") final Long officeId) {
+ @QueryParam("baseDate") final String baseDateParam, @QueryParam("officeId") final Long officeId) {
this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSION);
- final LocalDate reportingDate = parseOrBusinessDate(reportingDateParam);
+ final LocalDate reportingDate = requirePastOrPresent(parseOrBusinessDate(reportingDateParam),
+ "The reporting date");
final LocalDate rawLagDate = reportingDate.minusDays(DTL_LAG_DAYS);
// A reporting Friday that falls on a holiday has no close of business to strike a balance
// at, so the position is taken at the preceding working day instead.
final LocalDate nominalDtlDate = reportingFridayOnOrBefore(rawLagDate);
- final LocalDate dtlDate = precedingWorkingDay(nominalDtlDate);
+ // The base date can be given outright. The 45-day lag lands where it lands, and a bank
+ // reading an earlier fortnight - or correcting a filing - needs to name the date the base
+ // is struck at rather than work backwards from it. Given explicitly it is used as given;
+ // otherwise it is derived from the lag as before.
+ final boolean baseGiven = baseDateParam != null && !baseDateParam.isBlank();
+ final LocalDate dtlDate = baseGiven
+ ? requirePastOrPresent(LocalDate.parse(baseDateParam), "The base date")
+ : precedingWorkingDay(nominalDtlDate);
final Map response = new LinkedHashMap<>();
response.put("formCode", "FORM_1");
@@ -155,8 +166,10 @@ public class RbiReserveReturnApiResource {
response.put("reportingDate", reportingDate.toString());
response.putAll(fortnightOf(reportingDate));
- // The lag basis, spelled out so a reviewer can check it rather than trust it.
- final boolean shifted = !dtlDate.equals(nominalDtlDate);
+ // The lag basis, spelled out so a reviewer can check it rather than trust it. A base date
+ // the filer chose is said to be theirs: the note must never imply the lag produced a date
+ // somebody typed.
+ final boolean shifted = !baseGiven && !dtlDate.equals(nominalDtlDate);
final Map basis = new LinkedHashMap<>();
basis.put("lagDays", DTL_LAG_DAYS);
basis.put("rawLagDate", rawLagDate.toString());
@@ -164,13 +177,18 @@ public class RbiReserveReturnApiResource {
basis.put("dtlAsOnDate", dtlDate.toString());
basis.put("holdingsAsOnDate", reportingDate.toString());
basis.put("shiftedForHoliday", shifted);
- basis.put("note", "DTL is taken as at the reporting Friday on or before " + rawLagDate + " ("
- + DTL_LAG_DAYS + " days before the reporting date)"
- + (shifted
- ? "; that Friday (" + nominalDtlDate + ") was a holiday, so the position is taken at the "
- + "preceding working day " + dtlDate
- : "")
- + "; balances maintained are taken as at " + reportingDate + ".");
+ basis.put("baseDateChosen", baseGiven);
+ basis.put("note", baseGiven
+ ? "DTL is taken as at " + dtlDate + ", the base date entered for this return; balances maintained "
+ + "are taken as at " + reportingDate + "."
+ : "DTL is taken as at the reporting Friday on or before " + rawLagDate + " (" + DTL_LAG_DAYS
+ + " days before the reporting date)"
+ + (shifted
+ ? "; that Friday (" + nominalDtlDate
+ + ") was a holiday, so the position is taken at the preceding working day "
+ + dtlDate
+ : "")
+ + "; balances maintained are taken as at " + reportingDate + ".");
response.put("basis", basis);
final RoleFigure dtl = figureFor("DEMAND_TIME_LIABILITIES", dtlDate, officeId);
@@ -207,25 +225,32 @@ public class RbiReserveReturnApiResource {
final BigDecimal ndtl = liabilities.subtract(netted).max(BigDecimal.ZERO);
final List> lines = new ArrayList<>();
- lines.add(line("Demand and Time Liabilities (DTL)", dtl, dtlDate));
+ lines.add(withComparison(line("Demand and Time Liabilities (DTL)", dtl, dtlDate),
+ "DEMAND_TIME_LIABILITIES", dtlDate, reportingDate, officeId));
for (final CustomHead head : heads) {
if (USAGE_LIABILITY.equals(head.usage)) {
- lines.add(line(head.label, head.figure, dtlDate));
+ lines.add(withComparison(line(head.label, head.figure, dtlDate), head.figure.configKey, dtlDate,
+ reportingDate, officeId));
}
}
// The two heads the liability total is built from, each stated on the face of the return as
// RBI reports them rather than left implicit inside the total above.
lines.add(subLine("of which: Demand Liabilities", demand, dtl.configured, dtlDate));
lines.add(subLine("of which: Time Liabilities", time, dtl.configured, dtlDate));
- lines.add(line("Less: balances with other banks — deducted from the DTL base", interBankAtDtlDate, dtlDate));
+ lines.add(withComparison(
+ line("Less: balances with other banks — deducted from the DTL base", interBankAtDtlDate, dtlDate),
+ "BALANCE_WITH_OTHER_BANKS", dtlDate, reportingDate, officeId));
for (final CustomHead head : heads) {
if (USAGE_ASSET_NET.equals(head.usage)) {
- lines.add(line("Less: " + head.label, head.figure, dtlDate));
+ lines.add(withComparison(line("Less: " + head.label, head.figure, dtlDate), head.figure.configKey,
+ dtlDate, reportingDate, officeId));
}
}
lines.add(subLine("Net Demand and Time Liabilities (NDTL)", ndtl, dtl.configured, dtlDate));
- lines.add(line("Cash in hand — counts toward CRR maintained", cash, reportingDate));
- lines.add(line("Balances with other banks — counts toward CRR maintained", banks, reportingDate));
+ lines.add(withComparison(line("Cash in hand — counts toward CRR maintained", cash, reportingDate),
+ "CASH_IN_HAND", dtlDate, reportingDate, officeId));
+ lines.add(withComparison(line("Balances with other banks — counts toward CRR maintained", banks, reportingDate),
+ "BALANCE_WITH_OTHER_BANKS", dtlDate, reportingDate, officeId));
for (final CustomHead head : heads) {
// A head belonging to the Memorandum or an Annexure prints under that section's own
// heading below, not here: listing it in both places would show one figure twice and
@@ -234,11 +259,16 @@ public class RbiReserveReturnApiResource {
continue;
}
if (!USAGE_LIABILITY.equals(head.usage) && !USAGE_ASSET_NET.equals(head.usage)) {
- lines.add(line(head.label + (USAGE_MAINTAINED.equals(head.usage) ? "" : " (memo)"), head.figure,
- reportingDate));
+ lines.add(withComparison(
+ line(head.label + (USAGE_MAINTAINED.equals(head.usage) ? "" : " (memo)"), head.figure,
+ reportingDate),
+ head.figure.configKey, dtlDate, reportingDate, officeId));
}
}
response.put("lines", lines);
+ // Named so the screen can head its two columns without re-deriving either date.
+ response.put("baseDate", dtlDate.toString());
+ response.put("currentDate", reportingDate.toString());
final boolean computable = rate != null && dtl.configured && (cash.configured || banks.configured);
response.put("computable", computable);
@@ -355,8 +385,15 @@ public class RbiReserveReturnApiResource {
@QueryParam("officeId") final Long officeId) {
this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSION);
- final LocalDate requested = parseOrBusinessDate(reportingDateParam);
- final LocalDate monthEnd = requested.with(TemporalAdjusters.lastDayOfMonth());
+ final LocalDate requested = requirePastOrPresent(parseOrBusinessDate(reportingDateParam),
+ "The reporting date");
+ final LocalDate nominalMonthEnd = requested.with(TemporalAdjusters.lastDayOfMonth());
+ // Run inside the current month, the month end has not arrived. Reading balances at it
+ // returned today's figures under the month-end heading, so a month still running reported
+ // as a closed one - with nothing on the return to say the month was not over.
+ final LocalDate today = DateUtils.getBusinessLocalDate();
+ final LocalDate monthEnd = minimum(nominalMonthEnd, today);
+ final boolean monthComplete = !nominalMonthEnd.isAfter(today);
final Map response = new LinkedHashMap<>();
response.put("formCode", "FORM_9");
@@ -364,13 +401,22 @@ public class RbiReserveReturnApiResource {
response.put("frequency", "Monthly");
response.put("requestedDate", requested.toString());
response.put("reportingDate", monthEnd.toString());
+ // Stated so a return read before the month closes cannot be mistaken for the filed one.
+ response.put("monthEnd", nominalMonthEnd.toString());
+ response.put("monthComplete", monthComplete);
response.put("monthStart", requested.withDayOfMonth(1).toString());
final Map basis = new LinkedHashMap<>();
basis.put("dtlAsOnDate", monthEnd.toString());
basis.put("holdingsAsOnDate", monthEnd.toString());
- basis.put("note", "SLR is reported on the month-end position: both the DTL base and the "
- + "SLR-eligible investments are taken as at " + monthEnd + ".");
+ basis.put("note", monthComplete
+ ? "SLR is reported on the month-end position: both the DTL base and the "
+ + "SLR-eligible investments are taken as at " + monthEnd + "."
+ // Said plainly rather than left to the dates: a provisional return that reads like a
+ // filed one is the whole risk here.
+ : "The month ending " + nominalMonthEnd + " has not closed. Both the DTL base and "
+ + "the SLR-eligible investments are taken as at " + monthEnd
+ + ", the position so far, and will move before the month ends.");
response.put("basis", basis);
final RoleFigure dtl = figureFor("DEMAND_TIME_LIABILITIES", monthEnd, officeId);
@@ -540,6 +586,10 @@ public class RbiReserveReturnApiResource {
figure.configured = true;
for (final Map account : accounts) {
+ // The mapping row, not the account. One account can be pinned to a role twice - a
+ // savings balance split into its demand and time slices - and the comparison below
+ // matches rows across the two dates by this, so the two slices stay apart.
+ final Long mappingId = ((Number) account.get("mapping_id")).longValue();
final Long accountId = ((Number) account.get("id")).longValue();
final int classification = ((Number) account.get("classification_enum")).intValue();
final String glCode = (String) account.get("gl_code");
@@ -559,6 +609,7 @@ public class RbiReserveReturnApiResource {
if (disabled || header) {
figure.excluded.add(glCode + " — " + account.get("name") + (disabled ? " (disabled)" : " (header account)"));
final Map skipped = new LinkedHashMap<>();
+ skipped.put("mappingId", mappingId);
skipped.put("glAccountId", accountId);
skipped.put("glCode", glCode);
skipped.put("name", account.get("name"));
@@ -607,6 +658,7 @@ public class RbiReserveReturnApiResource {
}
final Map detail = new LinkedHashMap<>();
+ detail.put("mappingId", mappingId);
detail.put("glAccountId", accountId);
detail.put("glCode", glCode);
detail.put("name", account.get("name"));
@@ -890,6 +942,89 @@ public class RbiReserveReturnApiResource {
return out;
}
+ /**
+ * Fills in a line's figure at the OTHER of the return's two dates, so every row can be read
+ * across both columns rather than only at the one date its own figure belongs to.
+ *
+ *
+ * The return is built from figures struck at two different dates - the base at its lagged date,
+ * the holdings at the reporting date - and a reader comparing them has no way to tell a real
+ * movement from the two dates simply being different. Reading each line at both dates makes the
+ * movement visible: the DTL line then shows what the liabilities were on the base date AND what
+ * they are now, and the cash line the same.
+ *
+ *
+ * The line's own {@code amount} is left exactly as it was. That is the figure the return is
+ * computed from, and nothing here may move it.
+ */
+ private Map withComparison(final Map row, final String configKey,
+ final LocalDate baseDate, final LocalDate reportingDate, final Long officeId) {
+ if (configKey == null) {
+ return row;
+ }
+ final String ownDate = (String) row.get("asOnDate");
+ final boolean ownIsBase = baseDate.toString().equals(ownDate);
+ final LocalDate otherDate = ownIsBase ? reportingDate : baseDate;
+
+ final RoleFigure other = figureFor(configKey, otherDate, officeId);
+ row.put("comparisonDate", otherDate.toString());
+ row.put("comparisonAmount", other.configured ? other.amount : null);
+
+ // Stated as base-then-current whichever date the line's own figure belongs to, so a column
+ // means the same thing on every row of the return.
+ final BigDecimal own = (BigDecimal) row.get("amount");
+ row.put("baseAmount", ownIsBase ? own : other.amount);
+ row.put("currentAmount", ownIsBase ? other.amount : own);
+ if (own != null) {
+ final BigDecimal from = ownIsBase ? own : other.amount;
+ final BigDecimal to = ownIsBase ? other.amount : own;
+ row.put("movement", to.subtract(from));
+ }
+
+ // The accounts behind the line get the same treatment as the line itself. Without this the
+ // breakdown states each account at one date and leaves the other column blank, so a reader
+ // who can see a head has moved cannot see WHICH account moved - which is the one question
+ // the breakdown exists to answer.
+ //
+ // Matched on the mapping row, so a savings balance split into a demand slice and a time
+ // slice keeps the two apart instead of giving both the same figure.
+ final Map> otherAccounts = new LinkedHashMap<>();
+ for (final Map account : other.accounts) {
+ final Object key = account.get("mappingId");
+ if (key != null) {
+ otherAccounts.put(((Number) key).longValue(), account);
+ }
+ }
+ @SuppressWarnings("unchecked")
+ final List> ownAccounts = (List>) row.get("accounts");
+ if (ownAccounts != null) {
+ for (final Map account : ownAccounts) {
+ final Object key = account.get("mappingId");
+ final Map match = key == null ? null
+ : otherAccounts.get(((Number) key).longValue());
+ // An account mapped since the other date has no row there. Left null rather than
+ // shown as zero: it did not hold nothing, it did not exist on the return.
+ final BigDecimal otherBalance = match == null ? null : (BigDecimal) match.get("balance");
+ final BigDecimal ownBalance = (BigDecimal) account.get("balance");
+ account.put("baseBalance", ownIsBase ? ownBalance : otherBalance);
+ account.put("currentBalance", ownIsBase ? otherBalance : ownBalance);
+ // The account's own unweighted balance at the other date too, so a weighted row
+ // still reconciles against the ledger in both columns.
+ final BigDecimal otherAccountBalance = match == null ? null
+ : (BigDecimal) match.get("accountBalance");
+ final BigDecimal ownAccountBalance = (BigDecimal) account.get("accountBalance");
+ account.put("baseAccountBalance", ownIsBase ? ownAccountBalance : otherAccountBalance);
+ account.put("currentAccountBalance", ownIsBase ? otherAccountBalance : ownAccountBalance);
+ if (ownBalance != null && otherBalance != null) {
+ final BigDecimal from = ownIsBase ? ownBalance : otherBalance;
+ final BigDecimal to = ownIsBase ? otherBalance : ownBalance;
+ account.put("movement", to.subtract(from));
+ }
+ }
+ }
+ return row;
+ }
+
/**
* Human-readable reasons the return could not be computed, for the screen to show verbatim.
*
@@ -935,4 +1070,1331 @@ public class RbiReserveReturnApiResource {
private static LocalDate parseOrBusinessDate(final String param) {
return (param == null || param.isBlank()) ? DateUtils.getBusinessLocalDate() : LocalDate.parse(param);
}
+
+ /**
+ * Refuses a date the bank has not reached yet.
+ *
+ * A balance is summed as {@code entry_date <= date}, so a future date does not fail and does not
+ * come back empty - it returns TODAY'S balance under tomorrow's heading. The return then looks
+ * complete and is wrong in the one way nothing on its face can show: a fortnight that has not
+ * closed reported as though it had, with figures that will still move before it does.
+ *
+ * Checked against the business date rather than the wall clock, because that is the date every
+ * figure on the return is read at.
+ */
+ private static LocalDate requirePastOrPresent(final LocalDate date, final String what) {
+ final LocalDate today = DateUtils.getBusinessLocalDate();
+ if (date.isAfter(today)) {
+ throw new PlatformDataIntegrityException("error.msg.rbireservereturn.future.date",
+ what + " (" + date + ") is in the future; the bank's business date is " + today
+ + ". A period that has not closed cannot be reported.",
+ what, date.toString(), today.toString());
+ }
+ return date;
+ }
+
+ /** The earlier of two dates. */
+ private static LocalDate minimum(final LocalDate a, final LocalDate b) {
+ return a.isAfter(b) ? b : a;
+ }
+
+ // ══════════════ Statutory Form 1 ══════════════
+
+ /**
+ * Form 1 as a co-operative bank actually files it - Banking Regulation (Co-operative Societies)
+ * Rules 1966, Form 1 under Rule 5, sections 18(1) and 24(3).
+ *
+ *
+ * This is a different statement from the {@code form1} endpoint above, not a reformatting of
+ * it. Three differences matter:
+ *
+ *
+ *
Three columns. The form reports two alternate Fridays side by side with the
+ * reporting date, so a reviewer sees the position move across the fortnight rather than a
+ * single snapshot.
+ *
The base date. Both ratios are charged on the liabilities of the last Friday of
+ * the SECOND PRECEDING fortnight, not on the column's own liabilities. That lag is what gives a
+ * bank time to arrange its position, and reading the rate off the current column would report a
+ * requirement the bank never had.
+ *
One form, both ratios. Part B settles section 18 (cash reserve) and Part C
+ * section 24 (liquid assets) on the same liabilities, so they are computed together.
+ *
+ *
+ *
+ * Every figure is read from the heads an administrator mapped; nothing is hardcoded to a GL
+ * code. A head left unmapped reports as nil, because on this form a nil line is a real answer -
+ * a bank with no balances at the State Co-operative Bank files that line empty.
+ */
+ @GET
+ @Path("form1-statutory")
+ public String form1Statutory(@QueryParam("reportingDate") final String reportingDateParam,
+ @QueryParam("firstColumnDate") final String firstColumnDateParam,
+ @QueryParam("secondColumnDate") final String secondColumnDateParam,
+ @QueryParam("officeId") final Long officeId) {
+ this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSION);
+
+ final LocalDate requestedDate = parseOrBusinessDate(reportingDateParam);
+
+ // The two alternate Fridays the form reports, and the reporting date itself. The filed form
+ // shows the earlier Friday first, so the columns read left to right in time order.
+ // Fortnights run 1st-15th and 16th-month end, and each closes on its last day. Those closes
+ // are what the form's columns report, not alternate Fridays: a filed Form 1 for August
+ // heads its columns 15/08 and 31/08, which are the fortnight ends however the weekdays
+ // fall. The reporting date itself is the third column.
+ //
+ // Both closes can be given outright. A bank filing August wants 15/08 and 31/08 on the face
+ // of the form whatever today is, and deriving them from one date cannot produce a pair that
+ // spans a month boundary or skips a fortnight - which is exactly what a late or corrected
+ // filing needs. Given explicitly they are used as given; otherwise they are derived as
+ // before.
+ //
+ // Both are refused if they have not happened yet: the figures under a future close are
+ // today's, and a fortnight still running would be filed as though it had closed.
+ final LocalDate currentClose = secondColumnDateParam == null || secondColumnDateParam.isBlank()
+ // Derived, the close can legitimately fall ahead of today - it is the fortnight the
+ // requested date sits inside. Pulled back to the business date so the form reports
+ // the position as far as it exists rather than refusing its own default.
+ ? minimum(fortnightCloseOnOrAfter(requestedDate), DateUtils.getBusinessLocalDate())
+ : requirePastOrPresent(LocalDate.parse(secondColumnDateParam), "The second column's date");
+ final LocalDate previousClose = firstColumnDateParam == null || firstColumnDateParam.isBlank()
+ ? fortnightCloseBefore(currentClose)
+ : requirePastOrPresent(LocalDate.parse(firstColumnDateParam), "The first column's date");
+
+ // The form is made up to the later of its two closes. Taking the reporting date separately
+ // let a caller pass one that belonged to a different fortnight than the columns, and the
+ // rate in force was then looked up on that stray date - so a form could be headed one
+ // period and computed at another period's rate, with nothing on it to show the mismatch.
+ final LocalDate reportingDate = currentClose;
+ // The form reads left to right as the period advances. Reversed, every movement across it
+ // carries the wrong sign while the form still looks properly filled in.
+ if (!previousClose.isBefore(currentClose)) {
+ throw new PlatformDataIntegrityException("error.msg.rbireservereturn.columns.out.of.order",
+ "The first column (" + previousClose + ") must fall before the second (" + currentClose + ").",
+ previousClose.toString(), currentClose.toString());
+ }
+
+ // The third column is the base the current fortnight's ratios are charged on - the last
+ // Friday of the second preceding fortnight - not the reporting date.
+ //
+ // It was the reporting date. Since the return is now made up to the second column, that
+ // made the third column a copy of the second: two identically dated columns carrying
+ // identical figures, which reads as a filled form and says nothing. The base belongs on the
+ // face of the form because every required amount below is computed from it, and a reviewer
+ // cannot check a requirement whose base is not stated.
+ final LocalDate currentBase = formOneBaseDate(currentClose);
+ final List columnDates = List.of(previousClose, currentClose, currentBase);
+
+ final Map response = new LinkedHashMap<>();
+ response.put("formCode", "FORM_1_STATUTORY");
+ response.put("formName", "Form 1 (Rule 5) — Sections 18(1) and 24(3)");
+ response.put("statutoryReference", "Banking Regulation (Co-operative Societies) Rules, 1966");
+ response.put("reportingDate", reportingDate.toString());
+ response.put("columns", columnDates.stream().map(LocalDate::toString).toList());
+
+ final Rate crr = rateInForce("CRR", reportingDate);
+ final Rate slr = rateInForce("SLR", reportingDate);
+ response.put("crrPercentage", crr == null ? null : crr.percentage);
+ response.put("slrPercentage", slr == null ? null : slr.percentage);
+
+ final List> parts = new ArrayList<>();
+ parts.add(formOnePartA(columnDates, officeId, crr, slr));
+ response.put("partA", parts.get(0));
+ response.put("partB", formOnePartB(columnDates, officeId, crr));
+ response.put("partC", formOnePartC(columnDates, officeId, slr));
+
+ final List unmet = new ArrayList<>();
+ if (crr == null) {
+ unmet.add("No CRR rate is on record effective on or before the reporting date.");
+ }
+ if (slr == null) {
+ unmet.add("No SLR rate is on record effective on or before the reporting date.");
+ }
+
+ // A nil base makes both required amounts nil, and the form then reads as a bank with no
+ // reserve requirement at all - which is what a bank in breach would also look like. The
+ // base is dated well before the columns, so a ledger that only starts part-way through can
+ // have real liabilities on its face and nothing behind the ratio, and nothing on the form
+ // says why. Named here with the date, so the nil is read as "no liabilities on that day"
+ // rather than as "nothing required".
+ final BigDecimal baseLiabilities = formOneNetLiabilities(currentBase, officeId);
+ if (baseLiabilities.compareTo(BigDecimal.ZERO) == 0) {
+ unmet.add("Both ratios are charged on the net liabilities of " + currentBase
+ + " — the last Friday of the second preceding fortnight — and the ledger holds "
+ + "none on that date. The required amounts are therefore nil. They are nil "
+ + "because the base is nil, not because nothing is required.");
+ }
+
+ response.put("unmetRequirements", unmet);
+ return gson.toJson(response);
+ }
+
+ /** Part A: the liabilities and assets the two ratios are worked out from. */
+ private Map formOnePartA(final List dates, final Long officeId, final Rate crr,
+ final Rate slr) {
+ final List> lines = new ArrayList<>();
+
+ lines.add(formOneHeading("I. LIABILITIES IN INDIA TO THE BANKING SYSTEM"));
+ lines.add(formOneHeading("(a) Demand Liabilities"));
+ final List iai = formOneLine(lines, "(i) Current account balances of SBI, its subsidiaries and the corresponding new banks",
+ "FORM1_I_A_I_SBI_CURRENT", dates, officeId, 2);
+ final List iaii = formOneLine(lines, "(ii) Other demand liabilities to the banking system",
+ "FORM1_I_A_II_OTHER_DEMAND_BS", dates, officeId, 2);
+ final List ib = formOneLine(lines, "(b) Time liabilities to the banking system", "FORM1_I_B_TIME_BS",
+ dates, officeId, 1);
+ final List totalI = sumOf(iai, iaii, ib);
+ lines.add(formOneTotal("TOTAL OF I", totalI));
+
+ lines.add(formOneHeading("II. LIABILITIES IN INDIA TO OTHERS"));
+ // Demand and time come from the one DTL head, split by the class each mapped account
+ // carries - the same split the fortnightly return reports.
+ final List iiA = new ArrayList<>();
+ final List iiB = new ArrayList<>();
+ for (final LocalDate date : dates) {
+ final RoleFigure dtl = figureFor("DEMAND_TIME_LIABILITIES", date, officeId);
+ iiA.add(dtl.demandAmount);
+ iiB.add(dtl.timeAmount);
+ }
+ lines.add(formOneRow("(A) Demand liabilities", "DEMAND_TIME_LIABILITIES", iiA, 1));
+ lines.add(formOneRow("(B) Time liabilities", "DEMAND_TIME_LIABILITIES", iiB, 1));
+ final List totalII = sumOf(iiA, iiB);
+ lines.add(formOneTotal("TOTAL OF II", totalII));
+
+ lines.add(formOneHeading("III. ASSETS IN INDIA WITH THE BANKING SYSTEM"));
+ final List iiiA = formOneLine(lines, "(A) Current account balances with SBI, its subsidiaries and the corresponding new banks",
+ "FORM1_III_A_SBI_CURRENT", dates, officeId, 1);
+ lines.add(formOneHeading("(B) Other assets with the banking system"));
+ final List iiiBi = formOneLine(lines, "(i) Balances in all accounts other than III(A)",
+ "FORM1_III_B_I_OTHER_BALANCES", dates, officeId, 2);
+ final List iiiBii = formOneLine(lines, "(ii) Money at call and short notice",
+ "FORM1_III_B_II_MONEY_AT_CALL_BS", dates, officeId, 2);
+ final List iiiBiv = formOneLine(lines, "(iv) Advances and any other assets",
+ "FORM1_III_B_IV_ADVANCES_BS", dates, officeId, 2);
+ final List totalIII = sumOf(iiiA, iiiBi, iiiBii, iiiBiv);
+ lines.add(formOneTotal("TOTAL OF III", totalIII));
+
+ // IV: the banking system nets out, and what is left is added to the liabilities to others.
+ // Floored at zero per column - the form's own wording, "(I - III) + II if minus figure",
+ // says the netting cannot push the base below the liabilities to others.
+ final List iv = new ArrayList<>();
+ for (int i = 0; i < dates.size(); i++) {
+ iv.add(totalI.get(i).subtract(totalIII.get(i)).max(BigDecimal.ZERO).add(totalII.get(i)));
+ }
+ lines.add(formOneTotal("IV. TOTAL (NET) DEMAND AND TIME LIABILITIES FOR THE PURPOSE OF SECTIONS 18 AND 24", iv));
+
+ final List v = formOneLine(lines, "V. CASH ON HAND", "CASH_IN_HAND", dates, officeId, 0);
+
+ lines.add(formOneHeading("VI. BALANCE IN CURRENT ACCOUNTS WITH"));
+ final List viA = formOneLine(lines, "(a) Reserve Bank of India", "FORM1_VI_A_RBI_CURRENT", dates,
+ officeId, 1);
+ final List viB = formOneLine(lines, "(b) State Co-operative Bank of the state concerned",
+ "FORM1_VI_B_STATE_COOP_CURRENT", dates, officeId, 1);
+ final List viC = formOneLine(lines, "(c) District Central Co-operative Bank of the district concerned",
+ "FORM1_VI_C_DCCB_CURRENT", dates, officeId, 1);
+ final List totalVI = sumOf(viA, viB, viC);
+ lines.add(formOneTotal("TOTAL OF VI", totalVI));
+
+ lines.add(formOneHeading("VII. BALANCES OF ALL OTHER TYPES WITH"));
+ final List viiA = formOneLine(lines, "(a) State Co-operative Bank of the state concerned",
+ "FORM1_VII_A_STATE_COOP_OTHER", dates, officeId, 1);
+ final List viiB = formOneLine(lines, "(b) District Central Co-operative Bank",
+ "FORM1_VII_B_DCCB_OTHER", dates, officeId, 1);
+ final List viiC = formOneLine(lines, "(c) Investment in Government securities",
+ "FORM1_VII_C_GOVT_SECURITIES", dates, officeId, 1);
+ final List totalVII = sumOf(viiA, viiB, viiC);
+ lines.add(formOneTotal("TOTAL OF VII", totalVII));
+
+ // VIII: only the excess counts. Where the banking system's claim on this bank exceeds the
+ // bank's own balance there is nothing to carry into the cash reserve, so it floors at zero.
+ final List viii = new ArrayList<>();
+ for (int i = 0; i < dates.size(); i++) {
+ viii.add(iiiA.get(i).subtract(iai.get(i)).max(BigDecimal.ZERO));
+ }
+ lines.add(formOneTotal("VIII. NET BALANCE IN CURRENT ACCOUNTS — excess of III(A) over I(a)(i)", viii));
+
+ // The liabilities the ratios are charged on: the last Friday of the second preceding
+ // fortnight, read per column rather than once, so each column states its own base.
+ final List baseDateDtl = new ArrayList<>();
+ final List baseDates = new ArrayList<>();
+ for (final LocalDate date : dates) {
+ final LocalDate base = formOneBaseDate(date);
+ baseDates.add(base.toString());
+ baseDateDtl.add(formOneNetLiabilities(base, officeId));
+ }
+ final Map baseRow = formOneTotal(
+ "DEMAND AND TIME LIABILITIES OF THE BASE DATE — last Friday of the second preceding fortnight",
+ baseDateDtl);
+ baseRow.put("baseDates", baseDates);
+ lines.add(baseRow);
+
+ final Map part = new LinkedHashMap<>();
+ part.put("title", "PART A");
+ part.put("lines", lines);
+ part.put("baseDates", baseDates);
+ part.put("baseDateLiabilities", baseDateDtl);
+ return part;
+ }
+
+ /** Part B: compliance with section 18 — the cash reserve. */
+ private Map formOnePartB(final List dates, final Long officeId, final Rate crr) {
+ final List> lines = new ArrayList<>();
+ final List required = new ArrayList<>();
+ final List maintained = new ArrayList<>();
+
+ for (final LocalDate date : dates) {
+ final BigDecimal base = formOneNetLiabilities(formOneBaseDate(date), officeId);
+ required.add(crr == null ? BigDecimal.ZERO
+ : base.multiply(crr.percentage).divide(HUNDRED, 2, RoundingMode.HALF_UP));
+ // X = V + VI + VIII, the form's own definition.
+ final BigDecimal cash = figureFor("CASH_IN_HAND", date, officeId).amount;
+ final BigDecimal currentAccounts = figureFor("FORM1_VI_A_RBI_CURRENT", date, officeId).amount
+ .add(figureFor("FORM1_VI_B_STATE_COOP_CURRENT", date, officeId).amount)
+ .add(figureFor("FORM1_VI_C_DCCB_CURRENT", date, officeId).amount);
+ final BigDecimal netCurrent = figureFor("FORM1_III_A_SBI_CURRENT", date, officeId).amount
+ .subtract(figureFor("FORM1_I_A_I_SBI_CURRENT", date, officeId).amount).max(BigDecimal.ZERO);
+ maintained.add(cash.add(currentAccounts).add(netCurrent));
+ }
+
+ lines.add(formOneTotal("IX. " + (crr == null ? "CRR" : crr.percentage + "%")
+ + " of IV as on the last Friday of the second preceding fortnight", required));
+ lines.add(formOneTotal("X. CASH RESERVE ACTUALLY MAINTAINED (V + VI + VIII)", maintained));
+
+ final Map part = new LinkedHashMap<>();
+ part.put("title", "PART B — Compliance with Section 18");
+ part.put("lines", lines);
+ part.put("required", required);
+ part.put("maintained", maintained);
+ part.put("surplus", differenceOf(maintained, required));
+ return part;
+ }
+
+ /** Part C: compliance with section 24 — the liquid assets. */
+ private Map formOnePartC(final List dates, final Long officeId, final Rate slr) {
+ final List> lines = new ArrayList<>();
+ final List required = new ArrayList<>();
+ final List cashAndOther = new ArrayList<>();
+ final List gold = new ArrayList<>();
+ final List securities = new ArrayList<>();
+
+ for (final LocalDate date : dates) {
+ final BigDecimal base = formOneNetLiabilities(formOneBaseDate(date), officeId);
+ final BigDecimal slrRequired = slr == null ? BigDecimal.ZERO
+ : base.multiply(slr.percentage).divide(HUNDRED, 2, RoundingMode.HALF_UP);
+ required.add(slrRequired);
+
+ // XII(a) is the cash reserve held OVER the section 18 requirement, plus the other
+ // balances of part VII. Only the excess counts: the part of the cash reserve that meets
+ // section 18 is already committed and cannot also meet section 24.
+ final BigDecimal crrRequired = formOnePartBRequired(date, officeId);
+ final BigDecimal crrMaintained = formOnePartBMaintained(date, officeId);
+ final BigDecimal excessCash = crrMaintained.subtract(crrRequired).max(BigDecimal.ZERO);
+ final BigDecimal otherBalances = figureFor("FORM1_VII_A_STATE_COOP_OTHER", date, officeId).amount
+ .add(figureFor("FORM1_VII_B_DCCB_OTHER", date, officeId).amount)
+ .add(figureFor("FORM1_VII_C_GOVT_SECURITIES", date, officeId).amount);
+ cashAndOther.add(excessCash.add(otherBalances));
+ gold.add(figureFor("FORMA_SLR_GOLD", date, officeId).amount);
+ securities.add(figureFor("SLR_INVESTMENTS", date, officeId).amount);
+ }
+
+ lines.add(formOneTotal("XI. " + (slr == null ? "SLR" : slr.percentage + "%")
+ + " of IV as on the last Friday of the second preceding fortnight", required));
+ lines.add(formOneHeading("XII. ASSETS ACTUALLY MAINTAINED"));
+ lines.add(formOneRow("(a) Cash and other balances maintained in India (X − IX + VII)", null, cashAndOther, 1));
+ lines.add(formOneRow("(b) Gold", "FORMA_SLR_GOLD", gold, 1));
+ lines.add(formOneRow("(c) Unencumbered approved securities", "SLR_INVESTMENTS", securities, 1));
+ final List totalXII = sumOf(cashAndOther, gold, securities);
+ lines.add(formOneTotal("TOTAL OF XII", totalXII));
+
+ final Map part = new LinkedHashMap<>();
+ part.put("title", "PART C — Compliance with Section 24");
+ part.put("lines", lines);
+ part.put("required", required);
+ part.put("maintained", totalXII);
+ part.put("surplus", differenceOf(totalXII, required));
+ return part;
+ }
+
+ private BigDecimal formOnePartBRequired(final LocalDate date, final Long officeId) {
+ final Rate crr = rateInForce("CRR", date);
+ if (crr == null) {
+ return BigDecimal.ZERO;
+ }
+ return formOneNetLiabilities(formOneBaseDate(date), officeId).multiply(crr.percentage).divide(HUNDRED, 2,
+ RoundingMode.HALF_UP);
+ }
+
+ private BigDecimal formOnePartBMaintained(final LocalDate date, final Long officeId) {
+ final BigDecimal cash = figureFor("CASH_IN_HAND", date, officeId).amount;
+ final BigDecimal currentAccounts = figureFor("FORM1_VI_A_RBI_CURRENT", date, officeId).amount
+ .add(figureFor("FORM1_VI_B_STATE_COOP_CURRENT", date, officeId).amount)
+ .add(figureFor("FORM1_VI_C_DCCB_CURRENT", date, officeId).amount);
+ final BigDecimal netCurrent = figureFor("FORM1_III_A_SBI_CURRENT", date, officeId).amount
+ .subtract(figureFor("FORM1_I_A_I_SBI_CURRENT", date, officeId).amount).max(BigDecimal.ZERO);
+ return cash.add(currentAccounts).add(netCurrent);
+ }
+
+ /**
+ * The date both ratios are charged on: the last Friday of the SECOND PRECEDING fortnight.
+ *
+ *
+ * Counted in fortnights, not in weeks. For a column closing 15 August the fortnight it belongs
+ * to is 1-15 August, the first preceding one is 16-31 July, and the second is 1-15 July - so
+ * the base falls in the first half of July, roughly six weeks back rather than the four a
+ * straight subtraction would give. Reading the rate off a date a fortnight too late would
+ * report a requirement the bank never had time to meet, which is the whole point of the lag.
+ *
+ *
+ * Within that fortnight the form takes its last Friday, shifted off a holiday the same way
+ * every other reporting date is.
+ */
+ private LocalDate formOneBaseDate(final LocalDate columnDate) {
+ final LocalDate ownClose = fortnightCloseOnOrAfter(columnDate);
+ final LocalDate secondPrecedingClose = fortnightCloseBefore(fortnightCloseBefore(ownClose));
+ return precedingWorkingDay(reportingFridayOnOrBefore(secondPrecedingClose));
+ }
+
+ /**
+ * The close of the fortnight a date falls in: the 15th for the first half of a month, the last
+ * day of the month for the second.
+ */
+ private static LocalDate fortnightCloseOnOrAfter(final LocalDate date) {
+ return date.getDayOfMonth() <= 15 ? date.withDayOfMonth(15) : date.with(TemporalAdjusters.lastDayOfMonth());
+ }
+
+ /** The close of the fortnight before the one ending on the given close. */
+ private static LocalDate fortnightCloseBefore(final LocalDate close) {
+ return close.getDayOfMonth() <= 15
+ // First half of a month: the fortnight before it ends with the previous month.
+ ? close.minusMonths(1).with(TemporalAdjusters.lastDayOfMonth())
+ // Second half: the fortnight before it ends on the 15th of the same month.
+ : close.withDayOfMonth(15);
+ }
+
+ /** Item IV computed for one date: (I − III floored at zero) + II. */
+ private BigDecimal formOneNetLiabilities(final LocalDate date, final Long officeId) {
+ final BigDecimal toBankingSystem = figureFor("FORM1_I_A_I_SBI_CURRENT", date, officeId).amount
+ .add(figureFor("FORM1_I_A_II_OTHER_DEMAND_BS", date, officeId).amount)
+ .add(figureFor("FORM1_I_B_TIME_BS", date, officeId).amount);
+ final BigDecimal withBankingSystem = figureFor("FORM1_III_A_SBI_CURRENT", date, officeId).amount
+ .add(figureFor("FORM1_III_B_I_OTHER_BALANCES", date, officeId).amount)
+ .add(figureFor("FORM1_III_B_II_MONEY_AT_CALL_BS", date, officeId).amount)
+ .add(figureFor("FORM1_III_B_IV_ADVANCES_BS", date, officeId).amount);
+ final BigDecimal toOthers = figureFor("DEMAND_TIME_LIABILITIES", date, officeId).amount;
+ return toBankingSystem.subtract(withBankingSystem).max(BigDecimal.ZERO).add(toOthers);
+ }
+
+ // ── Form 1 row builders ──
+
+ private static Map formOneHeading(final String label) {
+ final Map row = new LinkedHashMap<>();
+ row.put("label", label);
+ row.put("heading", true);
+ return row;
+ }
+
+ private static Map formOneRow(final String label, final String configKey,
+ final List values, final int indent) {
+ final Map row = new LinkedHashMap<>();
+ row.put("label", label);
+ row.put("configKey", configKey);
+ row.put("indent", indent);
+ row.put("values", values);
+ return row;
+ }
+
+ private static Map formOneTotal(final String label, final List values) {
+ final Map row = formOneRow(label, null, values, 0);
+ row.put("total", true);
+ return row;
+ }
+
+ /** Reads one head across every column and appends its row. */
+ private List formOneLine(final List> lines, final String label,
+ final String configKey, final List dates, final Long officeId, final int indent) {
+ final List values = new ArrayList<>();
+ boolean configured = false;
+ for (final LocalDate date : dates) {
+ final RoleFigure figure = figureFor(configKey, date, officeId);
+ configured |= figure.configured;
+ values.add(figure.amount);
+ }
+ final Map row = formOneRow(label, configKey, values, indent);
+ row.put("configured", configured);
+ lines.add(row);
+ return values;
+ }
+
+ @SafeVarargs
+ private static List sumOf(final List... columns) {
+ final List out = new ArrayList<>();
+ final int size = columns.length == 0 ? 0 : columns[0].size();
+ for (int i = 0; i < size; i++) {
+ BigDecimal total = BigDecimal.ZERO;
+ for (final List column : columns) {
+ total = total.add(column.get(i));
+ }
+ out.add(total);
+ }
+ return out;
+ }
+
+ private static List differenceOf(final List a, final List b) {
+ final List out = new ArrayList<>();
+ for (int i = 0; i < a.size(); i++) {
+ out.add(a.get(i).subtract(b.get(i)));
+ }
+ return out;
+ }
+
+ /**
+ * Form 9 in the shape it is filed - the statutory statement of compliance with section 24.
+ *
+ *
+ * The same Part A and Part C the statutory Form 1 carries, on this return's own dates. Form 1
+ * reports two fortnight closes because it is filed fortnightly; Form 9 is filed monthly, so it
+ * reports the month it covers and the month before, and charges the ratio on the last Friday of
+ * the second preceding fortnight exactly as Form 1 does.
+ *
+ *
+ * Part B is left out. That part settles section 18, which is the cash reserve - Form 1's
+ * subject, not this one's. Printing it here would put a CRR compliance statement on an SLR
+ * return, where a reader has no reason to expect one.
+ *
+ * @param reportingDate any date in the month; the return reports that month's end.
+ * @param officeId Optional - scopes every figure to one office.
+ */
+ @GET
+ @Path("form9-statutory")
+ public String form9Statutory(@QueryParam("reportingDate") final String reportingDateParam,
+ @QueryParam("officeId") final Long officeId) {
+ this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSION);
+
+ final LocalDate requested = requirePastOrPresent(parseOrBusinessDate(reportingDateParam),
+ "The reporting date");
+ final LocalDate nominalMonthEnd = requested.with(TemporalAdjusters.lastDayOfMonth());
+ final LocalDate today = DateUtils.getBusinessLocalDate();
+ // A month end that has not arrived would report today's balances under its heading - a month
+ // still running filed as a closed one.
+ final LocalDate currentClose = minimum(nominalMonthEnd, today);
+ final boolean monthComplete = !nominalMonthEnd.isAfter(today);
+ final LocalDate previousClose = requested.withDayOfMonth(1).minusDays(1);
+ final LocalDate base = formOneBaseDate(currentClose);
+
+ final List columnDates = List.of(previousClose, currentClose, base);
+
+ final Map response = new LinkedHashMap<>();
+ response.put("formCode", "FORM_9_STATUTORY");
+ response.put("formName", "Form 9 - Statement of Compliance with Section 24 (SLR)");
+ response.put("statutoryReference", "Banking Regulation (Co-operative Societies) Rules, 1966");
+ response.put("frequency", "Monthly");
+ response.put("reportingDate", currentClose.toString());
+ response.put("monthEnd", nominalMonthEnd.toString());
+ response.put("monthComplete", monthComplete);
+ response.put("columns", columnDates.stream().map(LocalDate::toString).toList());
+
+ final Rate crr = rateInForce("CRR", currentClose);
+ final Rate slr = rateInForce("SLR", currentClose);
+ response.put("crrPercentage", crr == null ? null : crr.percentage);
+ response.put("slrPercentage", slr == null ? null : slr.percentage);
+
+ // Part A establishes the liabilities both ratios are charged on, so it is needed here even
+ // though only section 24 is settled below: without it the required amount at XI is a figure
+ // with nothing behind it.
+ response.put("partA", formOnePartA(columnDates, officeId, crr, slr));
+ response.put("partC", formOnePartC(columnDates, officeId, slr));
+
+ final List unmet = new ArrayList<>();
+ if (slr == null) {
+ unmet.add("No SLR rate is on record effective on or before the reporting date.");
+ }
+ if (crr == null) {
+ // Not an aside: XII(a) counts only the cash reserve held OVER the section 18
+ // requirement, so without a CRR rate that line takes the whole reserve and overstates
+ // what is available to meet section 24.
+ unmet.add("No CRR rate is on record. The cash counted at XII(a) is the reserve held over "
+ + "the section 18 requirement, so without a CRR rate that line is overstated.");
+ }
+ if (!monthComplete) {
+ unmet.add("The month ending " + nominalMonthEnd + " has not closed. This is the position "
+ + "as at " + currentClose + ", not the month-end position the return reports.");
+ }
+ // As on Form 1: a nil base makes the requirement nil, and the form then reads the same as a
+ // bank with nothing to maintain. Said with the date so the nil can be read for what it is.
+ if (formOneNetLiabilities(base, officeId).compareTo(BigDecimal.ZERO) == 0) {
+ unmet.add("The ratio is charged on the net liabilities of " + base + " — the last Friday "
+ + "of the second preceding fortnight — and the ledger holds none on that date. "
+ + "The required amount is therefore nil, because the base is nil.");
+ }
+ response.put("unmetRequirements", unmet);
+ return gson.toJson(response);
+ }
+
+ // ══════════════ Form IX - Return on Assets and Liabilities (R408) ══════════════
+
+ /** Rupees to rupees-thousands. Form IX reports in thousands; Form 1 reports in rupees. */
+ private static final BigDecimal THOUSAND = BigDecimal.valueOf(1000);
+
+ /** role_group for Form IX heads, so they sit apart from Form 1's on the configuration screen. */
+ private static final String GROUP_FORM9 = "FORM9";
+
+ private static final String USAGE_ASSET = "ASSET";
+
+ /**
+ * Form IX - the Return on Assets and Liabilities a co-operative bank files monthly, return code
+ * R408.
+ *
+ *
+ * A different return from {@code form9} above despite the name. That one reports a ratio: the
+ * liquid assets held against the liabilities, and whether the bank complied. This one reports
+ * the bank's whole balance sheet - every class of liability and every class of asset - and its
+ * two sides must agree.
+ *
+ *
+ * Three things about it differ from every other return here:
+ *
+ *
+ *
Thousands. Every figure is in rupees thousands. The conversion happens once, on a
+ * finished total, never per account - see {@code thousands}.
+ *
Unmapped heads still print. Elsewhere a head with nothing mapped is left off. Here
+ * a nil line is a real answer - a bank with no borrowings from the EXIM Bank files that line
+ * empty - so every head appears, with whether it was configured stated beside it.
+ *
Both sides are totalled independently and their difference reported. The filed
+ * return this was built from balanced its sides by subtracting the difference from the side
+ * that was already short, and printed "DIFF ADJUSTED" rather than saying the balance did not
+ * hold. A figure is never adjusted here to make the form balance.
+ *
+ *
+ * @param reportingDate any date in the month; the return reports that month's end.
+ * @param officeId Optional - scopes every figure to one office.
+ */
+ @GET
+ @Path("form9-return")
+ public String form9Return(@QueryParam("reportingDate") final String reportingDateParam,
+ @QueryParam("officeId") final Long officeId) {
+ this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSION);
+
+ final LocalDate requested = requirePastOrPresent(parseOrBusinessDate(reportingDateParam),
+ "The reporting date");
+ final LocalDate nominalMonthEnd = requested.with(TemporalAdjusters.lastDayOfMonth());
+ final LocalDate today = DateUtils.getBusinessLocalDate();
+ // Run inside the current month, the month end has not arrived. Reading balances at it would
+ // return today's figures under the month-end heading - a month still running reported as a
+ // closed one, with nothing on the return to say so.
+ final LocalDate asOn = minimum(nominalMonthEnd, today);
+ final boolean monthComplete = !nominalMonthEnd.isAfter(today);
+
+ final Map response = new LinkedHashMap<>();
+ response.put("formCode", "FORM_9_RETURN");
+ response.put("formName", "Form IX - Return on Assets and Liabilities");
+ response.put("returnCode", "R408");
+ response.put("statutoryReference", "The Banking Regulation Act - Form IX");
+ response.put("frequency", "Monthly");
+ response.put("unit", "Rs. in Thousands");
+ response.put("reportingDate", asOn.toString());
+ response.put("monthEnd", nominalMonthEnd.toString());
+ response.put("monthComplete", monthComplete);
+ response.put("note", monthComplete
+ ? "Every figure is a closing balance as at " + asOn + ", in rupees thousands."
+ : "The month ending " + nominalMonthEnd + " has not closed. Figures are the position "
+ + "as at " + asOn + " and will move before the month ends.");
+
+ // Every Form IX head, mapped or not, in the order the form prints them.
+ final List> roles = jdbcTemplate.queryForList("""
+ SELECT config_key, label, role_usage
+ FROM m_rbi_reserve_role
+ WHERE role_group = ?
+ ORDER BY position, label
+ """, GROUP_FORM9);
+
+ final Map> byKey = new LinkedHashMap<>();
+ BigDecimal liabilityTotal = BigDecimal.ZERO;
+ BigDecimal assetTotal = BigDecimal.ZERO;
+ final List> liabilityLines = new ArrayList<>();
+ final List> assetLines = new ArrayList<>();
+ final List> memoLines = new ArrayList<>();
+ int unmappedCount = 0;
+
+ for (final Map role : roles) {
+ final String key = (String) role.get("config_key");
+ final String usage = (String) role.get("role_usage");
+ final RoleFigure figure = figureFor(key, asOn, officeId);
+
+ final Map row = new LinkedHashMap<>();
+ row.put("configKey", key);
+ row.put("label", role.get("label"));
+ row.put("usage", usage);
+ row.put("configured", figure.configured);
+ // Rupees as well as thousands. The rupee figure is what the ledger actually holds, and a
+ // reviewer checking a line against the trial balance needs it: a thousands figure alone
+ // cannot be reconciled, because the rounding already happened.
+ row.put("amountInRupees", figure.configured ? figure.amount : null);
+ row.put("amount", figure.configured ? thousands(figure.amount) : null);
+ row.put("accounts", accountsInThousands(figure));
+ byKey.put(key, row);
+
+ if (!figure.configured) {
+ unmappedCount++;
+ }
+
+ if (USAGE_LIABILITY.equals(usage)) {
+ liabilityLines.add(row);
+ liabilityTotal = liabilityTotal.add(figure.amount);
+ } else if (USAGE_ASSET.equals(usage)) {
+ assetLines.add(row);
+ assetTotal = assetTotal.add(figure.amount);
+ } else {
+ memoLines.add(row);
+ }
+ }
+
+ // A loss belongs on the asset side at item 12, not on the liability side as a negative
+ // item 9. The form carries two separate lines because the year's result goes to one of them
+ // or the other, never to both: a bank that made a loss files item 9 empty and item 12 with
+ // the figure. Reported as a negative liability instead it pulls the liability total DOWN by
+ // the loss, when a loss makes the two sides agree by being added to the assets - so the
+ // return came out short by twice the loss and said the balance did not hold.
+ //
+ // Moved rather than left with a caveat, because this one has a right answer: the figure is
+ // correct, only its side is wrong, and the form itself says which side that is.
+ // ── The year's own result ──
+ //
+ // Income and expense accounts hold the year's trading, and no balance-sheet head maps them
+ // because they are not balance-sheet accounts. But their NET is - it is the profit or loss
+ // the balance sheet closes with, and without it the two sides cannot agree by exactly that
+ // amount.
+ //
+ // What the equity profit accounts hold is LAST year's result and what has been appropriated
+ // out of it - a year-end closing entry moved it there when the books were closed, and the
+ // dividend and reserve transfers drew it down. That is a balance-sheet figure in its own
+ // right and is already reported through the accounts mapped to this head.
+ //
+ // This year's trading has not been closed to anywhere, so it is added on top. Adding it to
+ // what the equity accounts hold is not double counting: the year-end entry that would move
+ // it there has not run, which is exactly why the two sides were out by this amount.
+ //
+ // The whole figure - brought forward plus this year - then goes to ONE of the two lines the
+ // form carries for it. Positive it is item 9 on the liability side, negative it is item 12
+ // on the asset side, and never a share of each. Two passes were tried, one adding the result
+ // and a second moving a negative across, and the second subtracted the whole balance from a
+ // total the first had already adjusted - so the return moved by the result twice.
+ final BigDecimal tradingResult = unclosedTradingResult(asOn, officeId);
+ final Map profitRow = byKey.get("FORM9_L9_BALANCE_OF_PROFIT");
+ final Map lossRow = byKey.get("FORM9_A12_BALANCE_OF_LOSS");
+ if (profitRow != null) {
+ final BigDecimal broughtForward = profitRow.get("amountInRupees") == null ? BigDecimal.ZERO
+ : (BigDecimal) profitRow.get("amountInRupees");
+ final BigDecimal result = broughtForward.add(tradingResult);
+
+ // Whatever the profit head contributed to the liability total in the loop above is taken
+ // back out, so the result can be placed once, on whichever side it belongs.
+ liabilityTotal = liabilityTotal.subtract(broughtForward);
+
+ // Two figures, each named: what the equity accounts hold, and what the income and
+ // expense accounts still hold because no year-end entry has closed them. A reviewer
+ // checking this line against the ledger needs both, since neither account alone shows it.
+ final String provenance = "Equity accounts mapped here: " + rupees(broughtForward)
+ + ". Income and expense accounts not yet closed to equity: " + rupees(tradingResult) + ".";
+
+ if (result.compareTo(BigDecimal.ZERO) < 0 && lossRow != null) {
+ final BigDecimal loss = result.negate();
+ assetTotal = assetTotal.add(loss);
+
+ // The accounts move WITH the figure, they are not copied to both lines. Item 9 now
+ // reports nil and has nothing to show; listing its accounts under a nil total said
+ // the bank held a profit made up of two balances that came to nothing. Worse, they
+ // were also printed under item 12 with their signs flipped, so the same account
+ // appeared twice with opposite figures and read as counted twice.
+ final Object accountsBehind = profitRow.get("accounts");
+ profitRow.put("amountInRupees", BigDecimal.ZERO);
+ profitRow.put("amount", BigDecimal.ZERO);
+ profitRow.put("accounts", List.of());
+ profitRow.put("note", "Nil — the bank stands in loss, so the figure is at item 12 on "
+ + "the asset side. " + provenance);
+
+ lossRow.put("configured", true);
+ lossRow.put("amountInRupees", loss);
+ lossRow.put("amount", thousands(loss));
+ // Exactly as the ledger holds them, signs and all. A loss IS a debit balance on an
+ // equity account, so showing it as one is the honest reading - and the unclosed
+ // trading is added as its own row because no account carries it. The three add to
+ // the loss, read as negatives, which is what a reviewer tracing the figure expects.
+ lossRow.put("accounts", withTradingRow(accountsBehind, tradingResult));
+ // The rows below carry the OPPOSITE sign to the head, because a loss reported as a
+ // positive figure on the asset side is made up of balances that are negative on the
+ // liability side. Saying so lets the screen head the column "as the ledger holds
+ // it", rather than leaving a reader to wonder how three negatives make a positive.
+ lossRow.put("accountsMirrorHead", true);
+ // Short, because the row above the balances already says they read the other way
+ // round. What belongs here is where the figure came from, not how to read it.
+ lossRow.put("note", "The bank stands in loss, so the figure is reported here rather "
+ + "than as a negative profit at item 9. " + provenance);
+ } else {
+ profitRow.put("configured", true);
+ profitRow.put("amountInRupees", result);
+ profitRow.put("amount", thousands(result));
+ profitRow.put("note", provenance);
+ liabilityTotal = liabilityTotal.add(result);
+ }
+ }
+
+ // ── Overdrawn holding accounts ──
+ //
+ // A liability that has been drawn past nil is not a liability at all: the bank has paid out
+ // more than it owed, and what is left is money owed BACK to it. On a balance sheet that is
+ // an asset, and the form has a line for exactly this - 11(i) Other Assets, tangible.
+ //
+ // Reported there rather than left as a negative liability. A negative on the liability side
+ // pulls the liability total down by the overdraw AND leaves the asset it really is off the
+ // asset side, so the balance breaks by twice the figure - the same way a loss did before it
+ // was moved to item 12. It is also unreadable: minus one thousand under "Other Demand
+ // Liabilities" looks like a small liability rather than a debt owed to the bank.
+ final Map otherAssets = byKey.get("FORM9_A11_I_TANGIBLE_ASSETS");
+ if (otherAssets != null) {
+ BigDecimal overdrawn = BigDecimal.ZERO;
+ final List overdrawnAccounts = new ArrayList<>();
+ for (final Map.Entry> keyed : byKey.entrySet()) {
+ // The profit head is exempt. Its accounts read negative because the bank is in
+ // loss, not because anyone drew them past nil, and the return has already carried
+ // that figure to item 12. Counting it here as well put the loss on the asset side
+ // twice - once at item 12 and once inside Other Assets - and inflated both sides of
+ // the return by it while still, by luck, agreeing.
+ if ("FORM9_L9_BALANCE_OF_PROFIT".equals(keyed.getKey())) {
+ continue;
+ }
+ final Map row = keyed.getValue();
+ if (!USAGE_LIABILITY.equals(row.get("usage"))) {
+ continue;
+ }
+ @SuppressWarnings("unchecked")
+ final List> accounts = (List>) row.get("accounts");
+ if (accounts == null) {
+ continue;
+ }
+ for (final Map account : accounts) {
+ final BigDecimal balance = (BigDecimal) account.get("balanceInRupees");
+ if (balance == null || balance.compareTo(BigDecimal.ZERO) >= 0) {
+ continue;
+ }
+ overdrawn = overdrawn.add(balance.negate());
+ overdrawnAccounts.add(account.get("glCode") + " " + account.get("name"));
+ }
+ }
+
+ if (overdrawn.compareTo(BigDecimal.ZERO) > 0) {
+ // Both totals move by the same amount and in the same direction: the liability side
+ // loses a negative, the asset side gains the positive it always was.
+ liabilityTotal = liabilityTotal.add(overdrawn);
+ assetTotal = assetTotal.add(overdrawn);
+
+ final BigDecimal existing = otherAssets.get("amountInRupees") == null ? BigDecimal.ZERO
+ : (BigDecimal) otherAssets.get("amountInRupees");
+ final BigDecimal total = existing.add(overdrawn);
+ otherAssets.put("configured", true);
+ otherAssets.put("amountInRupees", total);
+ otherAssets.put("amount", thousands(total));
+ otherAssets.put("note", "Includes " + rupees(overdrawn) + " rupees drawn out of holding accounts "
+ + "beyond what they held (" + String.join(", ", overdrawnAccounts) + "). A liability "
+ + "paid past nil is money owed back to the bank, which is an asset.");
+ }
+ }
+
+ response.put("liabilityLines", liabilityLines);
+ response.put("assetLines", assetLines);
+ response.put("memoLines", memoLines);
+
+ // ── Sub-totals the form states on its face ──
+ //
+ // Summed in RUPEES and converted once. Adding up figures that were each already rounded to
+ // thousands is what put the two sides of the filed return 2 thousand apart.
+ final Map totals = new LinkedHashMap<>();
+ totals.put("paidUpCapital", sumThousands(byKey, "FORM9_L1_A_CAPITAL_INDIVIDUALS",
+ "FORM9_L1_B_CAPITAL_COOP_SOCIETIES", "FORM9_L1_C_CAPITAL_STATE_GOVT", "FORM9_L1_D_CAPITAL_OTHERS"));
+ totals.put("reserveFund", sumThousands(byKey, "FORM9_L2_A_STATUTORY_RESERVE", "FORM9_L2_B_AGRI_CREDIT_FUND",
+ "FORM9_L2_C_DIVIDEND_EQUALISATION", "FORM9_L2_D_SPECIAL_BAD_DEBT", "FORM9_L2_E_BAD_DOUBTFUL_RESERVE",
+ "FORM9_L2_F_INVESTMENT_DEPRECIATION", "FORM9_L2_G_OTHER_FUNDS"));
+ totals.put("partnershipFund", sumThousands(byKey, "FORM9_L3_A_PARTNERSHIP_CCB", "FORM9_L3_B_PARTNERSHIP_PACS",
+ "FORM9_L3_C_PARTNERSHIP_OTHER"));
+
+ final BigDecimal demandRupees = sumRupees(byKey, "FORM9_L4_A1_CURRENT_CCB", "FORM9_L4_A2_CURRENT_PCB",
+ "FORM9_L4_A3_CURRENT_SOCIETIES", "FORM9_L4_A4_CURRENT_INDIVIDUALS", "FORM9_L4_A5_CURRENT_RESERVE_FUND",
+ "FORM9_L4_B4_SAVINGS_DEMAND_INDIVIDUALS", "FORM9_L4_B_SAVINGS_DEMAND_OTHER",
+ "FORM9_L4_C_BORROWINGS_DEMAND", "FORM9_L4_D_OTHER_DEMAND");
+ final BigDecimal timeRupees = sumRupees(byKey, "FORM9_L5_A1_FD_CCB", "FORM9_L5_A2_FD_PCB",
+ "FORM9_L5_A3_FD_SOCIETIES", "FORM9_L5_A4_FD_INDIVIDUALS", "FORM9_L5_A5_FD_RESERVE_FUND",
+ "FORM9_L5_B4_SAVINGS_TIME_INDIVIDUALS", "FORM9_L5_B_SAVINGS_TIME_OTHER", "FORM9_L5_C_BORROWINGS_TIME",
+ "FORM9_L5_D_CASH_CERT_RD", "FORM9_L5_E_OTHER_TIME");
+ final BigDecimal branchRupees = rupeesOf(byKey, "FORM9_L6_BRANCH_ADJUSTMENTS");
+
+ totals.put("demandLiabilities", thousands(demandRupees));
+ totals.put("timeLiabilities", thousands(timeRupees));
+ totals.put("branchAdjustments", thousands(branchRupees));
+ // Item 8 of the form: demand + time + branch adjustments, the figure CRR and SLR are charged
+ // on elsewhere. Converted from the rupee sum, not from the three thousands figures above.
+ totals.put("totalDemandAndTime", thousands(demandRupees.add(timeRupees).add(branchRupees)));
+ totals.put("balanceOfProfit", sumThousands(byKey, "FORM9_L9_BALANCE_OF_PROFIT"));
+ totals.put("totalLiabilities", thousands(liabilityTotal));
+
+ totals.put("cashInHand", sumThousands(byKey, "FORM9_A1_CASH_IN_HAND"));
+ totals.put("balanceWithBanksCurrent", sumThousands(byKey, "FORM9_A2_A_CUR_RBI", "FORM9_A2_B_CUR_SBI",
+ "FORM9_A2_C_CUR_BANKING_SYSTEM", "FORM9_A2_D_CUR_STATE_COOP", "FORM9_A2_E_CUR_DCCB",
+ "FORM9_A2_F_CUR_OTHER_COOP"));
+ totals.put("balanceWithBanksSavings", sumThousands(byKey, "FORM9_A2_SAV_BANKING_SYSTEM", "FORM9_A2_SAV_COOP"));
+ totals.put("moneyAtCall", sumThousands(byKey, "FORM9_A3_MONEY_AT_CALL"));
+ totals.put("investments", sumThousands(byKey, "FORM9_A4_A1_CENTRAL_GOVT_SEC", "FORM9_A4_A2_STATE_GOVT_SEC",
+ "FORM9_A4_B_LAND_MORTGAGE_DEBENTURES", "FORM9_A4_C_OTHER_TRUSTEE_SEC", "FORM9_A4_D_SHARES_STATE_COOP",
+ "FORM9_A4_E_SHARES_DCCB", "FORM9_A4_F_SHARES_OTHER_COOP", "FORM9_A4_G1_FD_SBI",
+ "FORM9_A4_G2_FD_BANKING_SYSTEM", "FORM9_A4_G3_FD_STATE_COOP", "FORM9_A4_G4_FD_DCCB",
+ "FORM9_A4_G5_FD_OTHER_COOP", "FORM9_A4_H_OTHER_INVESTMENTS"));
+ final BigDecimal advancesRupees = sumRupees(byKey, "FORM9_A6_A_SEASONAL_AGRI", "FORM9_A6_B_MARKETING_CROPS",
+ "FORM9_A6_C_MEDIUM_TERM_AGRI", "FORM9_A6_D_WEAVERS_SOCIETIES", "FORM9_A6_E_INDUSTRIAL_SHORT",
+ "FORM9_A6_E_INDUSTRIAL_MEDIUM", "FORM9_A6_F_OTHER_SHORT", "FORM9_A6_F_OTHER_MEDIUM",
+ "FORM9_A6_F_OTHER_LONG");
+ totals.put("loansAndAdvances", thousands(advancesRupees));
+ totals.put("otherAssets", sumThousands(byKey, "FORM9_A11_I_TANGIBLE_ASSETS", "FORM9_A11_II_INTANGIBLE_ASSETS"));
+ totals.put("totalAssets", thousands(assetTotal));
+
+ // The form's two explanation percentages, computed from the advances they qualify.
+ final BigDecimal overdueRupees = rupeesOf(byKey, "FORM9_A6_G_OVERDUE_ADVANCES");
+ final BigDecimal priorityRupees = rupeesOf(byKey, "FORM9_A6_G_PRIORITY_SECTOR");
+ totals.put("overduePercentage", percentageOf(overdueRupees, advancesRupees));
+ totals.put("prioritySectorPercentage", percentageOf(priorityRupees, advancesRupees));
+ response.put("totals", totals);
+
+ // ── Reconciliation ──
+ //
+ // Stated whether or not it holds. A return whose sides disagree is a return with something
+ // unmapped or double-mapped, and saying so is the only way anyone finds out which.
+ final BigDecimal differenceRupees = liabilityTotal.subtract(assetTotal);
+ final Map reconciliation = new LinkedHashMap<>();
+ reconciliation.put("totalLiabilities", thousands(liabilityTotal));
+ reconciliation.put("totalAssets", thousands(assetTotal));
+ reconciliation.put("differenceInRupees", differenceRupees);
+ reconciliation.put("difference", thousands(differenceRupees));
+ reconciliation.put("balanced", differenceRupees.compareTo(BigDecimal.ZERO) == 0);
+ response.put("reconciliation", reconciliation);
+
+ final List caveats = new ArrayList<>();
+ if (differenceRupees.compareTo(BigDecimal.ZERO) != 0) {
+ caveats.add("The two sides of the return do not agree: liabilities exceed assets by "
+ + rupees(differenceRupees) + " rupees. A head is unmapped, mapped twice, or mapped to the "
+ + "wrong side. The figures are left as the ledger reports them.");
+ }
+
+ // A liability with a negative balance, or an asset with one, is always a ledger fault - the
+ // bank cannot owe less than nothing, nor hold less than nothing. It arrives as an ordinary
+ // figure on the face of the return and reads as a small number rather than as a broken one,
+ // and it is exactly the kind of thing that puts the two sides out of agreement. Named here
+ // so whoever reads the return knows which account to look at.
+ for (final Map.Entry> keyed : byKey.entrySet()) {
+ // The profit and loss heads are exempt. A bank that has made a loss holds it on an
+ // equity account as a debit, and that account reads negative for a perfectly good
+ // reason - the return has already moved the figure to item 12 on the asset side, where
+ // it belongs. Flagging it would report the year's loss as a ledger fault.
+ if ("FORM9_L9_BALANCE_OF_PROFIT".equals(keyed.getKey())
+ || "FORM9_A12_BALANCE_OF_LOSS".equals(keyed.getKey())) {
+ continue;
+ }
+ final Map row = keyed.getValue();
+ final String usage = (String) row.get("usage");
+ final String side = USAGE_LIABILITY.equals(usage) ? "A liability" : USAGE_ASSET.equals(usage) ? "An asset" : "A head";
+
+ // Each ACCOUNT, not only the head's total. A negative account inside a head that totals
+ // positive is invisible in the total - "4(d) Other Demand Liabilities" reads 140,826
+ // while one of the four accounts under it sits at minus a thousand - and that is the
+ // case most worth catching, because nothing about the printed figure looks wrong.
+ @SuppressWarnings("unchecked")
+ final List> accounts = (List>) row.get("accounts");
+ boolean namedAnAccount = false;
+ if (accounts != null) {
+ for (final Map account : accounts) {
+ final BigDecimal balance = (BigDecimal) account.get("balanceInRupees");
+ if (balance == null || balance.compareTo(BigDecimal.ZERO) >= 0) {
+ continue;
+ }
+ namedAnAccount = true;
+ final String where = USAGE_LIABILITY.equals(usage)
+ // Already carried to the asset side above, so the note says where it
+ // went rather than asking the reader to go and find it.
+ ? " It is reported at 11(i) Other Assets, because a liability paid past "
+ + "nil is money owed back to the bank."
+ : "";
+ caveats.add(side + " has been drawn past nil: " + account.get("glCode") + " "
+ + account.get("name") + ", under \"" + row.get("label") + "\", stands at "
+ + rupees(balance) + " rupees. Either an entry was posted to it that should have "
+ + "gone elsewhere, or the entry that should have raised it never ran."
+ + where);
+ }
+ }
+
+ // The head itself, where no account under it accounts for the sign - a derived figure,
+ // or a head whose accounts are individually fine but sum below zero.
+ final BigDecimal headBalance = (BigDecimal) row.get("amountInRupees");
+ if (!namedAnAccount && headBalance != null && headBalance.compareTo(BigDecimal.ZERO) < 0) {
+ caveats.add(side + " cannot hold a negative balance: \"" + row.get("label") + "\" reports "
+ + rupees(headBalance) + " rupees. Either an entry was posted to it that should have gone "
+ + "elsewhere, or the entry that should have raised it never ran.");
+ }
+ }
+ // Named, not counted. A difference tells a filer THAT something is missing; this tells them
+ // WHICH account, which is the only form of the answer they can act on. Without it the gap
+ // has to be hunted down by reading the trial balance against the return line by line - and
+ // it comes back every time somebody opens a GL account and forgets to map it.
+ for (final Map account : unmappedAccountsWithBalances(asOn, officeId, byKey)) {
+ caveats.add("Not on this return: " + account.get("glCode") + " " + account.get("name") + " holds "
+ + rupees((java.math.BigDecimal) account.get("balance")) + " rupees but is mapped to no head, so it is counted on "
+ + "neither side. Map it under Admin, or the return stays out by this amount.");
+ }
+
+ if (unmappedCount > 0) {
+ // Not an error. A nil line is a real answer on this return, so this says what it is -
+ // how much of the form has been configured - rather than calling it a failure.
+ caveats.add(unmappedCount + " of " + roles.size() + " heads have no GL account mapped and "
+ + "report nil. On this return a nil line is a real answer; map any head the bank "
+ + "does hold a balance under.");
+ }
+ if (!monthComplete) {
+ caveats.add("The month has not closed. This is the position so far, not the month-end "
+ + "position the return reports.");
+ }
+ response.put("caveats", caveats);
+ response.put("computable", true);
+
+ return gson.toJson(response);
+ }
+
+ /**
+ * Rupees to rupees-thousands, rounded half-up.
+ *
+ *
+ * Called on a finished total and never on an individual account. Rounding each account and then
+ * adding the results drifts by up to half a thousand per account, and on the filed return this
+ * was built from that drift put the two sides 2 thousand apart - which the report then hid
+ * behind a "DIFF ADJUSTED" line.
+ */
+ /**
+ * Every balance-sheet account with a balance, and which head of this return reports it.
+ *
+ *
+ * A trial balance read through the return's own eyes. It exists because a difference between the
+ * two sides can only be chased by comparing what the ledger holds against what the return counts,
+ * and doing that by hand across a chart of accounts is where the time goes. Every figure here is
+ * read by the same code the return itself uses, so the two cannot disagree about an account.
+ */
+ @GET
+ @Path("form9-trial-balance")
+ public String form9TrialBalance(@QueryParam("reportingDate") final String reportingDateParam,
+ @QueryParam("officeId") final Long officeId) {
+ this.context.authenticatedUser().validateHasReadPermission(RESOURCE_NAME_FOR_PERMISSION);
+
+ final LocalDate asOn = requirePastOrPresent(parseOrBusinessDate(reportingDateParam), "The reporting date")
+ .with(TemporalAdjusters.lastDayOfMonth());
+
+ // Which head, if any, claims each account - an account can be claimed by more than one, and
+ // that is itself worth seeing.
+ final Map> heads = new LinkedHashMap<>();
+ for (final Map row : jdbcTemplate.queryForList("""
+ SELECT c.gl_account_id, r.config_key, c.weight_percentage
+ FROM m_rbi_reserve_gl_config c
+ JOIN m_rbi_reserve_role r ON r.config_key = c.config_key
+ WHERE r.role_group = ?
+ """, GROUP_FORM9)) {
+ final Long accountId = ((Number) row.get("gl_account_id")).longValue();
+ heads.computeIfAbsent(accountId, k -> new ArrayList<>())
+ .add(row.get("config_key") + " @" + row.get("weight_percentage") + "%");
+ }
+
+ final StringBuilder sql = new StringBuilder("""
+ SELECT a.id, a.gl_code, a.name, a.classification_enum,
+ COALESCE(SUM(CASE WHEN j.type_enum = 2 THEN j.amount ELSE 0 END), 0) AS total_debit,
+ COALESCE(SUM(CASE WHEN j.type_enum = 1 THEN j.amount ELSE 0 END), 0) AS total_credit
+ FROM acc_gl_account a
+ JOIN acc_gl_journal_entry j ON j.account_id = a.id
+ WHERE a.account_usage = 1
+ AND j.entry_date <= ?
+ AND (j.reversed IS NULL OR j.reversed = false)
+ AND j.id NOT IN (SELECT reversal_id FROM acc_gl_journal_entry WHERE reversal_id IS NOT NULL)
+ """);
+ final List