nidhiii128 opened a new pull request, #5410:
URL: https://github.com/apache/fineract/pull/5410
## Description
This project implements a robust API endpoint and service layer to retrieve
and display performance-related data for a client within the Apache Fineract
ecosystem. The implementation focuses on aggregating real-time financial
metrics, including active loan counts and a comprehensive "Total Outstanding
Balance" (Principal + Interest + Fees + Penalties) for active loan accounts.
## Acceptance Criteria & Implementation Proof
1. Integrate Client Profile Performance API with the app
What I Did: Developed a RESTful endpoint GET /clients/{clientId}/performance
within the ClientsApiResource class.
<img width="1870" height="567" alt="Screenshot 2026-01-28 212943"
src="https://github.com/user-attachments/assets/8b16c652-7a5b-4325-ab4d-41c625123ab4";
/>
Proof: Successfully mapped the resource and confirmed accessibility via the
terminal using curl.
2. Fetch and display performance data for a client in the profile view
What I Did: Implemented the retrieveClientPerformance method in the service
layer to fetch real-time data from the database using an optimized SQL query.
<img width="1466" height="100" alt="Screenshot 2026-01-28 200929"
src="https://github.com/user-attachments/assets/244ea6be-f4c5-49f9-9691-50b415b289f4";
/>
Proof: The API successfully returns a JSON payload containing activeLoans
and totalOutstandingBalance.
3. Ensure data is updated in real-time or via scheduled sync
What I Did: Utilized Fineract's JdbcTemplate to perform direct reads on the
m_loan and m_client tables, ensuring the metrics reflect the current state of
the database immediately upon request.
<img width="1843" height="716" alt="Screenshot 2026-01-28 211242"
src="https://github.com/user-attachments/assets/20f4023c-480c-4000-a610-1d76ebcb499e";
/>
Proof: Manual verification through Swagger and database checks confirmed
that balance changes are reflected as soon as loans are updated.
4. Handle API failures gracefully with appropriate error messages
What I Did: Implemented error handling to detect non-existent client IDs,
throwing a ClientNotFoundException which results in a standard Fineract 404
error response.
<img width="1791" height="846" alt="Screenshot 2026-01-28 212445"
src="https://github.com/user-attachments/assets/16c6c766-9fce-4a3f-8249-5dcd631ccbc5";
/>
Proof: Added logic to verify client existence before running the aggregation
query, ensuring a clear error message is returned if the ID is invalid.
5. Add unit tests and integration tests for the API layer
What I Did: Created ClientPerformanceApiIntegrationTest.java using the
RestAssured framework to automate the verification of the API.
<img width="1907" height="442" alt="Screenshot 2026-01-29 073849"
src="https://github.com/user-attachments/assets/84945bcf-8ec6-4f7b-b93f-a263130b49c7";
/>
?[32m2026-01-29 02:06:36.116?[0;39m [Test worker] ?[34mINFO ?[0;39m
?[36mo.a.f.i.common.ClientHelper?[0;39m -
---------------------------------CREATING A
CLIENT---------------------------------------------
?[32m2026-01-29 02:06:36.130?[0;39m [Test worker] ?[34mINFO ?[0;39m
?[36mo.a.f.i.common.ClientHelper?[0;39m - TestClient Request :
{"firstname":"Client_FirstName_Q528L","officeId":"1","dateFormat":"dd MMMM
yyyy","externalId":"b92a1915-a58e-401e-96b4-45a089036319","active":"true","locale":"en","activationDate":"04
March 2011","legalFormId":1,"lastname":"Client_LastName_ILBP"}
?[32m2026-01-29 02:06:36.132?[0;39m [Test worker] ?[34mINFO ?[0;39m
?[36mo.a.f.integrationtests.common.Utils?[0;39m - JSON
{"firstname":"Client_FirstName_Q528L","officeId":"1","dateFormat":"dd MMMM
yyyy","externalId":"b92a1915-a58e-401e-96b4-45a089036319","active":"true","locale":"en","activationDate":"04
March 2011","legalFormId":1,"lastname":"Client_LastName_ILBP"}
Proof: The test suite executed with a 100% success rate.
6. Confirm data matches the API response structure
What I Did: Defined a dedicated Data Transfer Object (DTO),
ClientPerformanceData, to ensure the response structure is consistent and types
match the expected financial precision.
Supporting Evidence:
[Image 1: DTO Structure]: ClientPerformanceData.java showing the defined
fields.
<img width="1195" height="502" alt="image"
src="https://github.com/user-attachments/assets/0d12ab5b-6985-467b-82be-9699563aa547";
/>
[Image 2: Test Assertions]: assertEquals logic in the Integration Test.
<img width="1193" height="131" alt="image"
src="https://github.com/user-attachments/assets/e05723d1-611f-4032-bcdf-463abf39587c";
/>
[Image 3: Test Success]: The green "100% Success" bar from terminal/Gradle
report.
<img width="1916" height="909" alt="Screenshot 2026-01-29 071856"
src="https://github.com/user-attachments/assets/d6c8193b-4c33-4f1a-b304-4429bf57fccd";
/>
Proof: The integration test specifically asserts the values of activeLoans
and totalOutstandingBalance against the JSON response.
## Technical Summary of Financial Logic
The balance is aggregated using the following formula for all loans with
Status 300 (Active):
TotalOutstanding = Principal_{derived} + Interest_{derived} + Fees_{derived}
+ Penalties_{derived}
Using the _derived columns from the m_loan table ensures that we are using
pre-calculated, high-performance data rather than re-calculating the entire
schedule on every API call.
## Checklist
Please make sure these boxes are checked before submitting your pull request
- thanks!
- [x] Write the commit message as per [our
guidelines](https://github.com/apache/fineract/blob/develop/CONTRIBUTING.md#pull-requests)
- [x] Acknowledge that we will not review PRs that are not passing the build
_("green")_ - it is your responsibility to get a proposed PR to pass the build,
not primarily the project's maintainers.
- [x] Create/update [unit or integration
tests](https://fineract.apache.org/docs/current/#_testing) for verifying the
changes made.
- [x] Follow our [coding
conventions](https://cwiki.apache.org/confluence/display/FINERACT/Coding+Conventions).
- [x] Add required Swagger annotation and update API documentation at
fineract-provider/src/main/resources/static/legacy-docs/apiLive.htm with
details of any API changes
- [x] [This PR must not be a "code
dump"](https://cwiki.apache.org/confluence/display/FINERACT/Pull+Request+Size+Limit).
Large changes can be made in a branch, with assistance. Ask for help on the
[developer mailing list](https://fineract.apache.org/#contribute).
Your assigned reviewer(s) will follow our [guidelines for code
reviews](https://cwiki.apache.org/confluence/display/FINERACT/Code+Review+Guide).
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
