FINERACT-2473: Add available balance to group accounts endpoint

Author: rhopman

fineract-core/src/main/java/org/apache/fineract/portfolio/accountdetails/data/SavingsAccountSummaryData.java

@@ -20,6 +20,7 @@
 
 import java.math.BigDecimal;
 import java.time.LocalDate;
+import lombok.Getter;
 import org.apache.fineract.infrastructure.core.data.EnumOptionData;
 import org.apache.fineract.organisation.monetary.data.CurrencyData;
 import org.apache.fineract.portfolio.savings.data.SavingsAccountApplicationTimelineData;
@@ -29,6 +30,7 @@
 /**
  * Immutable data object for savings accounts.
  */
+@Getter
 @SuppressWarnings("unused")
 public class SavingsAccountSummaryData {
 
@@ -40,7 +42,27 @@ public class SavingsAccountSummaryData {
     private final String shortProductName;
     private final SavingsAccountStatusEnumData status;
     private final CurrencyData currency;
+    /**
+     * The total balance of the savings account.
+     */
     private final BigDecimal accountBalance;
+    /**
+     * Funds held as collateral for loan guarantees. When a savings account is used as a guarantor for a loan, the
+     * guarantee amount is held here and unavailable for withdrawal until the loan is repaid or the guarantee is
+     * released. Sourced from the database column on_hold_funds_derived.
+     */
+    private final BigDecimal onHoldFunds;
+    /**
+     * User-initiated holds explicitly placed on the account, including lien holds. These are manual holds placed
+     * through hold/release transactions to restrict withdrawals for specific purposes. Sourced from the database column
+     * total_savings_amount_on_hold.
+     */
+    private final BigDecimal savingsAmountOnHold;
+    /**
+     * The actual available balance that can be withdrawn, accounting for all holds. Calculated as: accountBalance -
+     * onHoldFunds (guarantor holds) - savingsAmountOnHold (user/lien holds)
+     */
+    private final BigDecimal availableBalance;
     // differentiate Individual, JLG or Group account
     private final EnumOptionData accountType;
     private final SavingsAccountApplicationTimelineData timeline;
@@ -52,7 +74,8 @@ public class SavingsAccountSummaryData {
 
     public SavingsAccountSummaryData(final Long id, final String accountNo, final String externalId, final Long productId,
             final String productName, final String shortProductName, final SavingsAccountStatusEnumData status, final CurrencyData currency,
-            final BigDecimal accountBalance, final EnumOptionData accountType, final SavingsAccountApplicationTimelineData timeline,
+            final BigDecimal accountBalance, final BigDecimal onHoldFunds, final BigDecimal savingsAmountOnHold,
+            final BigDecimal availableBalance, final EnumOptionData accountType, final SavingsAccountApplicationTimelineData timeline,
             final EnumOptionData depositType, final SavingsAccountSubStatusEnumData subStatus, final LocalDate lastActiveTransactionDate) {
         this.id = id;
         this.accountNo = accountNo;
@@ -63,18 +86,13 @@ public SavingsAccountSummaryData(final Long id, final String accountNo, final St
         this.status = status;
         this.currency = currency;
         this.accountBalance = accountBalance;
+        this.onHoldFunds = onHoldFunds;
+        this.savingsAmountOnHold = savingsAmountOnHold;
+        this.availableBalance = availableBalance;
         this.accountType = accountType;
         this.timeline = timeline;
         this.depositType = depositType;
         this.subStatus = subStatus;
         this.lastActiveTransactionDate = lastActiveTransactionDate;
     }
-
-    public String getAccountNo() {
-        return accountNo;
-    }
-
-    public Long getId() {
-        return id;
-    }
 }

fineract-provider/src/main/java/org/apache/fineract/portfolio/accountdetails/service/AccountDetailsReadPlatformServiceJpaRepositoryImpl.java

@@ -311,6 +311,8 @@ private static final class SavingsAccountSummaryDataMapper implements RowMapper<
             accountsSummary.append("sa.id as id, sa.account_no as accountNo, sa.external_id as externalId, sa.status_enum as statusEnum, ");
             accountsSummary.append("sa.account_type_enum as accountType, ");
             accountsSummary.append("sa.account_balance_derived as accountBalance, ");
+            accountsSummary.append("sa.on_hold_funds_derived as onHoldFunds, ");
+            accountsSummary.append("sa.total_savings_amount_on_hold as onHoldAmount, ");
 
             accountsSummary.append("sa.submittedon_date as submittedOnDate,");
             accountsSummary.append("sbu.username as submittedByUsername,");
@@ -377,6 +379,18 @@ public SavingsAccountSummaryData mapRow(final ResultSet rs, @SuppressWarnings("u
             final String shortProductName = rs.getString("shortProductName");
             final Integer statusId = JdbcSupport.getInteger(rs, "statusEnum");
             final BigDecimal accountBalance = JdbcSupport.getBigDecimalDefaultToNullIfZero(rs, "accountBalance");
+            final BigDecimal onHoldFunds = JdbcSupport.getBigDecimalDefaultToNullIfZero(rs, "onHoldFunds");
+            final BigDecimal onHoldAmount = JdbcSupport.getBigDecimalDefaultToNullIfZero(rs, "onHoldAmount");
+
+            BigDecimal availableBalance = accountBalance;
+            if (availableBalance != null && onHoldFunds != null) {
+                availableBalance = availableBalance.subtract(onHoldFunds);
+            }
+
+            if (availableBalance != null && onHoldAmount != null) {
+                availableBalance = availableBalance.subtract(onHoldAmount);
+            }
+
             final SavingsAccountStatusEnumData status = SavingsEnumerations.status(statusId);
             final Integer accountType = JdbcSupport.getInteger(rs, "accountType");
             final EnumOptionData accountTypeData = AccountEnumerations.loanType(accountType);
@@ -433,7 +447,8 @@ public SavingsAccountSummaryData mapRow(final ResultSet rs, @SuppressWarnings("u
                     activatedByLastname, closedOnDate, closedByUsername, closedByFirstname, closedByLastname);
 
             return new SavingsAccountSummaryData(id, accountNo, externalId, productId, productName, shortProductName, status, currency,
-                    accountBalance, accountTypeData, timeline, depositTypeData, subStatus, lastActiveTransactionDate);
+                    accountBalance, onHoldFunds, onHoldAmount, availableBalance, accountTypeData, timeline, depositTypeData, subStatus,
+                    lastActiveTransactionDate);
         }
     }
 

fineract-provider/src/main/java/org/apache/fineract/portfolio/group/api/GroupsApiResourceSwagger.java

@@ -415,6 +415,14 @@ private GetGroupsGroupIdAccountsSavingAccountType() {}
             public String productName;
             public GetGroupsGroupIdAccountsSavingStatus status;
             public GetGroupsGroupIdAccountsSavingCurrency currency;
+            @Schema(example = "5000.00")
+            public java.math.BigDecimal accountBalance;
+            @Schema(example = "300.00")
+            public java.math.BigDecimal onHoldFunds;
+            @Schema(example = "200.00")
+            public java.math.BigDecimal savingsAmountOnHold;
+            @Schema(example = "4500.00")
+            public java.math.BigDecimal availableBalance;
             public GetGroupsGroupIdAccountsSavingAccountType accountType;
         }