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

Author: nidhiii128

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;
@@ -172,6 +173,23 @@ public String retrieveOne(@PathParam("clientId") @Parameter(description = "clien
         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.")
+    @ApiResponses({
+            @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 })

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;
+    }
+}

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);
+
 }

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,29 @@ public Long retrieveClientIdByExternalId(final ExternalId externalId) {
         return clientRepositoryWrapper.findIdByExternalId(externalId);
     }
 
+    @Override
+    public ClientPerformanceData retrieveClientPerformance(final Long clientId) {
+        try {
+            final String checkClientSql = "SELECT count(*) FROM m_client WHERE id = ?";
+            final Integer count = this.jdbcTemplate.queryForObject(checkClientSql, Integer.class, clientId);
+            if (count == null || count == 0) {
+                throw new ClientNotFoundException(clientId);
+            }
+            final String sql = "SELECT " + "(SELECT COUNT(*) FROM m_loan WHERE client_id = c.id AND loan_status_id = 300) as activeLoans, "
+                    + "(SELECT COALESCE(SUM(principal_outstanding_derived + interest_outstanding_derived + fee_charges_outstanding_derived + penalty_charges_outstanding_derived), 0) "
+                    + " FROM m_loan WHERE client_id = c.id AND loan_status_id = 300) as totalOutstanding "
+                    + "FROM m_client c WHERE c.id = ?";
+
+            return this.jdbcTemplate.queryForObject(sql, (rs, rowNum) -> {
+                final Integer activeLoans = rs.getInt("activeLoans");
+                BigDecimal totalOutstanding = rs.getBigDecimal("totalOutstanding");
+                return ClientPerformanceData.instance(activeLoans, totalOutstanding);
+            }, clientId);
+        } catch (EmptyResultDataAccessException e) {
+            throw new ClientNotFoundException(clientId);
+        }
+    }
+
     private static final class ClientToDataMapper implements RowMapper<ClientData> {
 
         private final String schema;
@@ -773,5 +797,4 @@ public ClientData mapRow(final ResultSet rs, final int rowNum) throws SQLExcepti
 
         }
     }
-
 }

integration-tests/src/test/java/org/apache/fineract/integrationtests/ClientPerformanceApiIntegrationTest.java

@@ -0,0 +1,68 @@
+/**
+ * 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.integrationtests;
+
+import static org.apache.fineract.integrationtests.common.ClientHelper.createClient;
+import static org.apache.fineract.integrationtests.common.Utils.initializeRESTAssured;
+import static org.apache.fineract.integrationtests.common.Utils.performServerGet;
+import static org.junit.jupiter.api.Assertions.assertEquals;
+
+import io.restassured.builder.RequestSpecBuilder;
+import io.restassured.builder.ResponseSpecBuilder;
+import io.restassured.http.ContentType;
+import io.restassured.specification.RequestSpecification;
+import io.restassured.specification.ResponseSpecification;
+import java.util.HashMap;
+import org.apache.fineract.integrationtests.common.ClientHelper;
+import org.apache.fineract.integrationtests.common.Utils;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+public class ClientPerformanceApiIntegrationTest {
+
+    private RequestSpecification requestSpec;
+    private ResponseSpecification responseSpec;
+
+    @BeforeEach
+    public void setup() {
+        initializeRESTAssured();
+        this.requestSpec = new RequestSpecBuilder().setContentType(ContentType.JSON).build();
+        this.requestSpec.header("Authorization", "Basic bWlmb3M6cGFzc3dvcmQ=");
+        this.requestSpec.header("fineract-platform-tenantid", "default");
+        this.responseSpec = new ResponseSpecBuilder().expectStatusCode(200).build();
+    }
+
+    @Test
+    public void testClientPerformanceMetrics() {
+        // Step 1: Create a Client
+        final Integer clientId = createClient(this.requestSpec, this.responseSpec);
+
+        // Step 2: Use the exact path that worked in Swagger
+        HashMap<String, Object> performanceData = performServerGet(
+                this.requestSpec,
+                this.responseSpec,
+                "/fineract-provider/api/v1/clients/" + clientId + "/performance",
+                ""
+        );
+
+        assertEquals(0, performanceData.get("activeLoans"), "Should have 0 active loans");
+        assertEquals(0, ((Number) performanceData.get("totalOutstandingBalance")).intValue(), "Should have 0 balance");
+    }
+}