Feature: Installment Management
Relevant source files
The following files were used as context for generating this wiki page:- src/main/java/com/paymaster/backend/domain/service/InstallmentService.java
- src/main/java/com/paymaster/backend/domain/entity/Installment.java
- src/main/resources/templates/installments/list.html
- src/main/java/com/paymaster/backend/domain/repository/InstallmentRepository.java
- src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
- src/main/java/com/paymaster/backend/domain/service/ContractService.java
- src/main/java/com/paymaster/backend/domain/entity/Contract.java
The Installment Management feature is a core component of the PayMaster system, responsible for the entire lifecycle of an installment. This includes its creation as part of a contract, tracking its status, processing payments, calculating penalties for late payments, and providing data for reports and dashboards.
Installments are generated automatically when a new contract is created via the ContractService. The InstallmentService then handles all business logic related to individual installments, such as payment processing and status updates. The system provides views for listing upcoming and overdue installments, and allows users to record payments through dedicated controller endpoints.
Data Model: The Installment Entity
The Installment entity represents a single payment obligation within a larger contract. It stores financial details, due dates, payment information, and its current status.
Sources: src/main/java/com/paymaster/backend/domain/entity/Installment.java
Entity Relationship Diagram
The diagram below shows that a Contract can have many Installment records, but each Installment belongs to exactly one Contract.
Fields and Properties
The table below details the key fields of the Installment entity.
| Field | Type | Description | Constraints |
|---|---|---|---|
id | Long | Primary key. | Auto-generated |
installmentNumber | Integer | The sequence number of the installment within the contract (e.g., 1, 2, 3). | Not Null, @Min(1) |
amount | Long | The total amount due for this installment. | Not Null, @Min(0) |
principalPortion | Long | The portion of the amount that is principal. | |
interestPortion | Long | The portion of the amount that is interest. | |
dueDate | LocalDate | The date the installment payment is due. | Not Null |
status | InstallmentStatus | The current status of the installment (e.g., PENDING, PAID). | Not Null, EnumType.STRING |
paidAmount | Long | The amount that has been paid so far for this installment. | @Min(0) |
penaltyAmount | Long | The accumulated penalty for late payment. | @Min(0) |
paymentDate | LocalDateTime | The timestamp when the last payment was made. | |
paymentMethod | PaymentMethod | The method used for payment (e.g., CASH, BANK_TRANSFER). | EnumType.STRING |
receiptNumber | String | An optional receipt or tracking number for the payment. | @Size(max=100) |
notes | String | Optional notes about the payment. | @Size(max=500) |
contract | Contract | The parent contract to which this installment belongs. | Not Null, Many-to-One |
Sources: src/main/java/com/paymaster/backend/domain/entity/Installment.java:23-86
Helper Methods
The Installment entity includes several helper methods for business logic calculations.
| Method | Return Type | Description |
|---|---|---|
isOverdue() | boolean | Checks if the installment is overdue and not fully paid. |
calculatePenalty() | long | Calculates the penalty amount based on the number of overdue days and the contract's penalty rate. |
getRemainingAmount() | long | Calculates the total amount remaining to be paid, including any penalties. |
Sources: src/main/java/com/paymaster/backend/domain/entity/Installment.java:93-118
Statuses (InstallmentStatus Enum)
Installments transition through various states, managed by the InstallmentStatus enum.
| Status | Badge Class | Persian Name | Description |
|---|---|---|---|
PENDING | secondary | در انتظار پرداخت | The installment is not yet due or is due but unpaid. |
PAID | success | پرداخت شده | The installment has been fully paid. |
PARTIALLY_PAID | info | پرداخت ناقص | A partial payment has been made, but a balance remains. |
OVERDUE | danger | معوق | The due date has passed, and the installment is not fully paid. |
CANCELLED | dark | لغو شده | The installment has been cancelled (not used in current logic). |
Sources: src/main/java/com/paymaster/backend/domain/valueobject/InstallmentStatus.java (File not provided, but referenced in Installment.java)
Core Logic: InstallmentService
The InstallmentService class orchestrates all business operations related to installments. It handles payment processing, status updates, and data retrieval for various parts of the application.
Sources: src/main/java/com/paymaster/backend/domain/service/InstallmentService.java
Key Service Methods
| Method | Description |
|---|---|
payInstallment(...) | Records a payment for an installment, calculates penalties, and updates the status. |
quickPay(Long) | A shortcut to fully pay an installment's remaining balance, including penalties. |
findOverdueInstallments() | Retrieves a list of all installments that are past their due date and not fully paid. |
findInstallmentsDueThisWeek() | Retrieves installments due within the next 7 days. |
updateOverdueInstallments() | A transactional method to update the status of PENDING installments to OVERDUE if their due date has passed. |
checkContractCompletion(Long) | Checks if all installments of a contract are paid and updates the contract's status to COMPLETED. |
sum...() methods | Aggregate functions to calculate total paid amounts, overdue amounts, and penalties for dashboard statistics. |
Sources: src/main/java/com/paymaster/backend/domain/service/InstallmentService.java:48-216
Payment Processing Flow (payInstallment)
The sequence diagram below illustrates the process of recording an installment payment.
Data Persistence: InstallmentRepository
The InstallmentRepository is a Spring Data JPA interface responsible for all database interactions concerning Installment entities. It includes several custom JPQL queries to support specific business requirements.
Sources: src/main/java/com/paymaster/backend/domain/repository/InstallmentRepository.java
Custom JPQL Queries
| Method | Query | Description |
|---|---|---|
findOverdueInstallments | SELECT i FROM Installment i WHERE i.dueDate < :today AND i.status = 'PENDING' | Finds all pending installments whose due date is before today. |
findInstallmentsDueThisWeek | SELECT i FROM Installment i WHERE i.dueDate BETWEEN :startOfWeek AND :endOfWeek AND i.status = 'PENDING' | Finds pending installments due within a given week. |
sumPaidAmount | SELECT COALESCE(SUM(i.paidAmount), 0) FROM Installment i WHERE i.status = 'PAID' | Calculates the total amount paid across all PAID installments. |
sumOverdueAmount | SELECT COALESCE(SUM(i.amount - i.paidAmount), 0) FROM Installment i WHERE i.dueDate < :today AND i.status = 'PENDING' | Calculates the total remaining balance of overdue installments. |
updateOverdueInstallments | UPDATE Installment i SET i.status = 'OVERDUE' WHERE i.dueDate < :today AND i.status = 'PENDING' | Updates the status of pending installments to OVERDUE. |
Sources: src/main/java/com/paymaster/backend/domain/repository/InstallmentRepository.java:71-131
Web Layer and UI
The HomeController exposes endpoints for managing and viewing installments, while Thymeleaf templates render the user interface.
Controller Endpoints
The following endpoints in HomeController are dedicated to installment management:
| Endpoint | HTTP Method | Description |
|---|---|---|
/installments/overdue | GET | Displays a list of all overdue installments. |
/installments/upcoming | GET | Displays a list of installments due in the current week. |
/installments/pay/{id} | POST | Processes a payment for a specific installment. |
/installments/quick-pay/{id} | POST | Processes a "quick pay" action to fully settle an installment. |
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:318-386
Installment List View
The installments/list.html template is used to display lists of installments, such as overdue or upcoming ones. It dynamically renders a table showing key details for each installment.
The view displays the following information for each installment:
- Contract Number (link to contract)
- Customer Name (link to customer)
- Installment Number
- Due Date
- Amount Due
- Remaining Amount
- Days Overdue (if applicable)
- Status Badge
Sources: src/main/resources/templates/installments/list.html:26-67
Summary
The Installment Management feature is a well-structured module that effectively separates concerns between the data model (Installment), business logic (InstallmentService), data access (InstallmentRepository), and presentation (HomeController, HTML templates). It provides robust functionality for tracking payments, handling overdue scenarios with penalties, and updating the state of both installments and their parent contracts, which is crucial for the financial integrity of the PayMaster application.