Fineract-2460: Add Client Performance API for real-time financial metrics

nidhiii128 · nidhiii128 · commit 991caa5e0a74 · 2026-02-02T08:15:13.000Z
diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/client/api/ClientsApiResource.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/client/api/ClientsApiResource.java
@@ -66,6 +66,7 @@
 import org.apache.fineract.portfolio.accountdetails.data.AccountSummaryCollectionData;
 import org.apache.fineract.portfolio.accountdetails.service.AccountDetailsReadPlatformService;
 import org.apache.fineract.portfolio.client.data.ClientData;
+import org.apache.fineract.portfolio.client.data.ClientPerformanceData;
 import org.apache.fineract.portfolio.client.exception.ClientNotFoundException;
 import org.apache.fineract.portfolio.client.service.ClientReadPlatformService;
 import org.apache.fineract.portfolio.client.service.ClientTemplateReadPlatformService;
@@ -104,8 +105,7 @@ public class ClientsApiResource {
     @Produces({ MediaType.APPLICATION_JSON })
     @Operation(summary = "Retrieve Client Details Template", description = "This is a convenience resource. It can be useful when building maintenance user interface screens for client applications. The template data returned consists of any or all of:\n"
             + "\n" + "Field Defaults\n" + "Allowed Value Lists\n\n" + "Example Request:\n" + "\n" + "clients/template")
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.GetClientsTemplateResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.GetClientsTemplateResponse.class)))
     public String retrieveTemplate(@Context final UriInfo uriInfo,
             @Parameter(description = "officeId") @QueryParam("officeId") final Long officeId,
             @QueryParam("commandParam") @Parameter(description = "commandParam") final String commandParam,
@@ -137,8 +137,7 @@ public String retrieveTemplate(@Context final UriInfo uriInfo,
     @Operation(summary = "List Clients", description = "The list capability of clients can support pagination and sorting.\n\n"
             + "Example Requests:\n" + "\n" + "clients\n" + "\n" + "clients?fields=displayName,officeName,timeline\n" + "\n"
             + "clients?offset=10&limit=50\n" + "\n" + "clients?orderBy=displayName&sortOrder=DESC")
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.GetClientsResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.GetClientsResponse.class)))
     public String retrieveAll(@Context final UriInfo uriInfo,
             @QueryParam("officeId") @Parameter(description = "officeId") final Long officeId,
             @QueryParam("externalId") @Parameter(description = "externalId") final String externalId,
@@ -164,14 +163,29 @@ public String retrieveAll(@Context final UriInfo uriInfo,
     @Produces({ MediaType.APPLICATION_JSON })
     @Operation(summary = "Retrieve a Client", description = "Example Requests:\n" + "\n" + "clients/1\n" + "\n" + "\n"
             + "clients/1?template=true\n" + "\n" + "\n" + "clients/1?fields=id,displayName,officeName")
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.GetClientsClientIdResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.GetClientsClientIdResponse.class)))
     public String retrieveOne(@PathParam("clientId") @Parameter(description = "clientId") final Long clientId,
             @Context final UriInfo uriInfo,
             @DefaultValue("false") @QueryParam("staffInSelectedOfficeOnly") @Parameter(description = "staffInSelectedOfficeOnly") final boolean staffInSelectedOfficeOnly) {
         return retrieveClient(clientId, null, staffInSelectedOfficeOnly, uriInfo);
     }
 
+    @GET
+    @Path("{clientId}/performance")
+    @Consumes({ MediaType.APPLICATION_JSON })
+    @Produces({ MediaType.APPLICATION_JSON })
+    @Operation(summary = "Retrieve client performance metrics", description = "Returns a summary of active loans and outstanding balances for a specific client.")
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientPerformanceData.class)))
+    public String retrieveClientPerformance(@PathParam("clientId") @Parameter(description = "clientId") final Long clientId,
+            @Context final UriInfo uriInfo) {
+
+        this.context.authenticatedUser().validateHasReadPermission(ClientApiConstants.CLIENT_RESOURCE_NAME);
+
+        final ClientPerformanceData performanceData = this.clientReadPlatformService.retrieveClientPerformance(clientId);
+
+        return this.toApiJsonSerializer.serialize(performanceData);
+    }
+
     @POST
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
@@ -181,8 +195,7 @@ public String retrieveOne(@PathParam("clientId") @Parameter(description = "clien
             + "Mandatory Fields: firstname and lastname OR fullname, officeId, active=true and activationDate OR active=false, if(address enabled) address\n\n"
             + "Optional Fields: groupId, externalId, accountNo, staffId, mobileNo, savingsProductId, genderId, clientTypeId, clientClassificationId")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PostClientsRequest.class)))
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PostClientsResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PostClientsResponse.class)))
     public String create(@Parameter(hidden = true) final String apiRequestBodyAsJson) {
 
         final CommandWrapper commandRequest = new CommandWrapperBuilder() //
@@ -204,8 +217,7 @@ public String create(@Parameter(hidden = true) final String apiRequestBodyAsJson
             + "Changing the relationship between a client and its office is not supported through this API. An API specific to handling transfers of clients between offices is available for the same.\n"
             + "\n" + "The relationship between a client and a group must be removed through the Groups API.")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PutClientsClientIdRequest.class)))
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PutClientsClientIdResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PutClientsClientIdResponse.class)))
     public String update(@Parameter(description = "clientId") @PathParam("clientId") final Long clientId,
             @Parameter(hidden = true) final String apiRequestBodyAsJson) {
         return updateClient(clientId, null, apiRequestBodyAsJson);
@@ -216,8 +228,7 @@ public String update(@Parameter(description = "clientId") @PathParam("clientId")
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
     @Operation(summary = "Delete a Client", description = "If a client is in Pending state, you are allowed to Delete it. The delete is a 'hard delete' and cannot be recovered from. Once clients become active or have loans or savings associated with them, you cannot delete the client but you may Close the client if they have left the program.")
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.DeleteClientsClientIdResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.DeleteClientsClientIdResponse.class)))
     public String delete(@PathParam("clientId") @Parameter(description = "clientId") final Long clientId) {
         return deleteClient(clientId, null);
     }
@@ -257,8 +268,7 @@ public String delete(@PathParam("clientId") @Parameter(description = "clientId")
             + "Abstraction over the Propose and Accept Client Transfer API's which enable a user with Data Scope over both the Target and Destination Branches to directly transfer a Client to the destination Office.\n\n"
             + "Showing request/response for 'Reject a Client Transfer'")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PostClientsClientIdRequest.class)))
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PostClientsClientIdResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PostClientsClientIdResponse.class)))
     public String activate(@PathParam("clientId") @Parameter(description = "clientId") final Long clientId,
             @QueryParam("command") @Parameter(description = "command") final String commandParam,
             @Parameter(hidden = true) final String apiRequestBodyAsJson) {
@@ -328,8 +338,7 @@ public String retrieveTransferTemplate(@PathParam("clientId") final Long clientI
     @Produces({ MediaType.APPLICATION_JSON })
     @Operation(summary = "Retrieve a Client by External Id", description = "Example Requests:\n" + "\n" + "clients/123-456\n" + "\n" + "\n"
             + "clients/123-456?template=true\n" + "\n" + "\n" + "clients/123-456?fields=id,displayName,officeName")
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.GetClientsClientIdResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.GetClientsClientIdResponse.class)))
     public String retrieveOne(@PathParam("externalId") @Parameter(description = "externalId") final String externalId,
             @Context final UriInfo uriInfo,
             @DefaultValue("false") @QueryParam("staffInSelectedOfficeOnly") @Parameter(description = "staffInSelectedOfficeOnly") final boolean staffInSelectedOfficeOnly) {
@@ -359,8 +368,7 @@ public String retrieveAssociatedAccounts(@PathParam("externalId") @Parameter(des
             + "Changing the relationship between a client and its office is not supported through this API. An API specific to handling transfers of clients between offices is available for the same.\n"
             + "\n" + "The relationship between a client and a group must be removed through the Groups API.")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PutClientsClientIdRequest.class)))
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PutClientsClientIdResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PutClientsClientIdResponse.class)))
     public String update(@Parameter(description = "externalId") @PathParam("externalId") final String externalId,
             @Parameter(hidden = true) final String apiRequestBodyAsJson) {
         return updateClient(null, externalId, apiRequestBodyAsJson);
@@ -401,8 +409,7 @@ public String update(@Parameter(description = "externalId") @PathParam("external
             + "Abstraction over the Propose and Accept Client Transfer API's which enable a user with Data Scope over both the Target and Destination Branches to directly transfer a Client to the destination Office.\n\n"
             + "Showing request/response for 'Reject a Client Transfer'")
     @RequestBody(required = true, content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PostClientsClientIdRequest.class)))
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PostClientsClientIdResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.PostClientsClientIdResponse.class)))
     public String applyCommand(@PathParam("externalId") @Parameter(description = "externalId") final String externalId,
             @QueryParam("command") @Parameter(description = "command") final String commandParam,
             @Parameter(hidden = true) final String apiRequestBodyAsJson) {
@@ -414,8 +421,7 @@ public String applyCommand(@PathParam("externalId") @Parameter(description = "ex
     @Consumes({ MediaType.APPLICATION_JSON })
     @Produces({ MediaType.APPLICATION_JSON })
     @Operation(summary = "Delete a Client", description = "If a client is in Pending state, you are allowed to Delete it. The delete is a 'hard delete' and cannot be recovered from. Once clients become active or have loans or savings associated with them, you cannot delete the client but you may Close the client if they have left the program.")
-    @ApiResponses({
-            @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.DeleteClientsClientIdResponse.class))) })
+    @ApiResponse(responseCode = "200", description = "OK", content = @Content(schema = @Schema(implementation = ClientsApiResourceSwagger.DeleteClientsClientIdResponse.class)))
     public String delete(@PathParam("externalId") @Parameter(description = "externalId") final String externalId) {
         return deleteClient(null, externalId);
     }
diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/client/data/ClientPerformanceData.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/client/data/ClientPerformanceData.java
@@ -0,0 +1,51 @@
+/**
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements. See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership. The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License. You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied. See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+package org.apache.fineract.portfolio.client.data;
+
+import java.io.Serializable;
+import java.math.BigDecimal;
+
+/**
+ * Data object for Client Performance metrics.
+ */
+public final class ClientPerformanceData implements Serializable {
+
+    private final Integer activeLoans;
+    private final BigDecimal totalOutstandingBalance;
+
+    // Constructor is private to force use of the static 'instance' method (Fineract style)
+    private ClientPerformanceData(final Integer activeLoans, final BigDecimal totalOutstandingBalance) {
+        this.activeLoans = activeLoans;
+        this.totalOutstandingBalance = totalOutstandingBalance;
+    }
+
+    public static ClientPerformanceData instance(final Integer activeLoans, final BigDecimal totalOutstandingBalance) {
+        return new ClientPerformanceData(activeLoans, totalOutstandingBalance);
+    }
+
+    // Getters for Spring to convert this to JSON
+    public Integer getActiveLoans() {
+        return activeLoans;
+    }
+
+    public BigDecimal getTotalOutstandingBalance() {
+        return totalOutstandingBalance;
+    }
+}
diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/client/service/ClientReadPlatformService.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/client/service/ClientReadPlatformService.java
@@ -24,6 +24,7 @@
 import org.apache.fineract.infrastructure.core.service.Page;
 import org.apache.fineract.infrastructure.core.service.SearchParameters;
 import org.apache.fineract.portfolio.client.data.ClientData;
+import org.apache.fineract.portfolio.client.data.ClientPerformanceData;
 
 public interface ClientReadPlatformService {
 
@@ -60,4 +61,6 @@ public interface ClientReadPlatformService {
 
     Long retrieveClientIdByExternalId(ExternalId externalId);
 
+    ClientPerformanceData retrieveClientPerformance(Long clientId);
+
 }
diff --git a/fineract-provider/src/main/java/org/apache/fineract/portfolio/client/service/ClientReadPlatformServiceImpl.java b/fineract-provider/src/main/java/org/apache/fineract/portfolio/client/service/ClientReadPlatformServiceImpl.java
@@ -47,6 +47,7 @@
 import org.apache.fineract.portfolio.client.data.ClientCollateralManagementData;
 import org.apache.fineract.portfolio.client.data.ClientData;
 import org.apache.fineract.portfolio.client.data.ClientNonPersonData;
+import org.apache.fineract.portfolio.client.data.ClientPerformanceData;
 import org.apache.fineract.portfolio.client.data.ClientTimelineData;
 import org.apache.fineract.portfolio.client.domain.Client;
 import org.apache.fineract.portfolio.client.domain.ClientEnumerations;
@@ -601,6 +602,28 @@ public Long retrieveClientIdByExternalId(final ExternalId externalId) {
         return clientRepositoryWrapper.findIdByExternalId(externalId);
     }
 
+    @Override
+    public ClientPerformanceData retrieveClientPerformance(final Long clientId) {
+        try {
+            final String sql = """
+                    SELECT
+                        COUNT(l.id) as activeLoans,
+                        COALESCE(SUM(l.principal_outstanding_derived + l.interest_outstanding_derived + l.fee_charges_outstanding_derived + l.penalty_charges_outstanding_derived), 0) as totalOutstandingBalance
+                    FROM m_client c
+                    LEFT JOIN m_loan l ON l.client_id = c.id AND l.loan_status_id = 300
+                    WHERE c.id = ?
+                    GROUP BY c.id
+                    """;
+            return this.jdbcTemplate.queryForObject(sql, (rs, rowNum) -> {
+                final Integer activeLoans = rs.getInt("activeLoans");
+                final BigDecimal totalOutstandingBalance = rs.getBigDecimal("totalOutstandingBalance");
+                return ClientPerformanceData.instance(activeLoans, totalOutstandingBalance);
+            }, clientId);
+        } catch (EmptyResultDataAccessException e) {
+            throw new ClientNotFoundException(clientId, e);
+        }
+    }
+
     private static final class ClientToDataMapper implements RowMapper<ClientData> {
 
         private final String schema;
@@ -773,5 +796,4 @@ public ClientData mapRow(final ResultSet rs, final int rowNum) throws SQLExcepti
 
         }
     }
-
 }
diff --git a/fineract-provider/src/main/resources/db/changelog/tenant/changelog-tenant.xml b/fineract-provider/src/main/resources/db/changelog/tenant/changelog-tenant.xml
@@ -227,4 +227,5 @@
     <include file="parts/0206_transaction_summary_with_asset_owner_classification_name_bug_fix.xml" relativeToChangelogFile="true" />
     <include file="parts/0207_add_allow_full_term_for_tranche.xml" relativeToChangelogFile="true" />
     <include file="parts/0208_trial_balance_summary_with_asset_owner_journal_entry_aggregation_fix.xml" relativeToChangelogFile="true" />
+    <include file="parts/0209_add_index_for_client_performance_api.xml" relativeToChangelogFile="true"/>
 </databaseChangeLog>
diff --git a/fineract-provider/src/main/resources/db/changelog/tenant/parts/0209_add_index_for_client_performance_api.xml b/fineract-provider/src/main/resources/db/changelog/tenant/parts/0209_add_index_for_client_performance_api.xml
diff --git a/integration-tests/src/test/java/org/apache/fineract/integrationtests/ClientPerformanceApiIntegrationTest.java b/integration-tests/src/test/java/org/apache/fineract/integrationtests/ClientPerformanceApiIntegrationTest.java
