Feature: Contract Management
Relevant source files
The following files were used as context for generating this wiki page:- src/main/java/com/paymaster/backend/domain/entity/Contract.java
- src/main/java/com/paymaster/backend/domain/service/ContractService.java
- src/main/java/com/paymaster/backend/domain/repository/ContractRepository.java
- src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
- src/main/resources/templates/contracts/form.html
- src/main/resources/templates/contracts/list.html
- src/main/resources/templates/contracts/view.html
- src/main/resources/static/js/app.js
The Contract Management feature is a core component of the PayMaster system, responsible for the entire lifecycle of financial agreements with customers. It handles the creation of new contracts, calculation of interest and installments, tracking of contract status, and management of related data. This module integrates closely with the Customer and Installment modules to provide a comprehensive view of a customer's financial obligations.
The system supports creating contracts with specified principal amounts, interest rates, and durations. Upon creation, it automatically generates a schedule of installments. The feature also provides user interfaces for listing, viewing, creating, and canceling contracts.
Architecture and Components
The Contract Management feature follows a standard multi-layered architecture, comprising a presentation layer (Thymeleaf templates and a controller), a service layer for business logic, and a data access layer (JPA repository).
Key Components
| Component | File | Description |
|---|---|---|
Contract Entity | Contract.java | Represents the data model for a contract, including financial details and relationships. |
ContractRepository | ContractRepository.java | JPA repository for all database operations related to contracts. |
ContractService | ContractService.java | Contains the core business logic for creating, managing, and querying contracts. |
HomeController | HomeController.java | Spring MVC controller that handles web requests for contract-related pages. |
contracts/ templates | templates/contracts/ | Thymeleaf templates for the user interface (list, form, view). |
Sources: src/main/java/com/paymaster/backend/domain/entity/Contract.java, src/main/java/com/paymaster/backend/domain/service/ContractService.java, src/main/java/com/paymaster/backend/domain/repository/ContractRepository.java, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java, src/main/resources/templates/contracts/list.html
Data Model
The Contract entity is the central data structure for this feature. It holds all financial information and maintains relationships with Customer and Installment entities.
Entity Relationship Diagram
The diagram below shows how the Contract entity relates to Customer and Installment entities.
Contract Entity Fields
The table below details the fields of the Contract entity, including their constraints and descriptions.
| Field | Type | Constraints | Description |
|---|---|---|---|
contractNumber | String | @NotBlank, @Size(max=20), unique | Unique identifier for the contract. |
principalAmount | Long | @NotNull, @Min(1000000) | The initial loan amount. |
interestRate | Double | @NotNull, @DecimalMin("0.0"), @DecimalMax("100.0") | The annual interest rate in percent. |
interestAmount | Long | The total calculated interest amount. | |
totalAmount | Long | @NotNull | The total amount to be paid (principal + interest). |
installmentCount | Integer | @NotNull, @Min(1), @Max(60) | The total number of installments. |
installmentAmount | Long | The calculated amount for each installment. | |
startDate | LocalDate | @NotNull | The date the contract begins. |
endDate | LocalDate | The calculated end date of the contract. | |
penaltyRate | Double | @DecimalMin("0.0"), default=0.5 | The daily penalty rate for late payments. |
status | ContractStatus | @Enumerated(STRING), default=DRAFT | The current status of the contract (e.g., ACTIVE, COMPLETED). |
description | String | @Size(max=500) | Optional notes about the contract. |
customer | Customer | @ManyToOne, @NotNull | The customer associated with the contract. |
installments | List<Installment> | @OneToMany, CascadeType.ALL | The list of installments generated for this contract. |
Sources: src/main/java/com/paymaster/backend/domain/entity/Contract.java:23-131
Contract Status
The ContractStatus enum defines the possible states of a contract.
| Status | Badge Class (UI) | Description |
|---|---|---|
DRAFT | secondary | The contract is a draft and not yet active. |
ACTIVE | primary | The contract is active and payments are expected. |
COMPLETED | success | The contract has been fully paid off. |
CANCELLED | dark | The contract has been cancelled before completion. |
OVERDUE | danger | The contract is active but has at least one overdue installment. |
Sources: src/main/java/com/paymaster/backend/domain/valueobject/ContractStatus.java, src/main/resources/templates/contracts/list.html:70-72
Core Business Logic (ContractService)
The ContractService class orchestrates all business operations related to contracts. It is transactional and handles creation, cancellation, status updates, and data retrieval.
Sources: src/main/java/com/paymaster/backend/domain/service/ContractService.java
Contract Creation
The createContract method is the entry point for creating a new contract and its associated installments.
Creation Flow
This flowchart illustrates the steps involved in the createContract method.
Sequence Diagram: Creating a New Contract
This diagram shows the interaction between the user, controller, service, and repository when creating a contract.
Contract Cancellation
A contract can be cancelled via the cancelContract method, which updates its status to CANCELLED and appends a cancellation reason to the description. A contract cannot be cancelled if it is already COMPLETED.
Sources: src/main/java/com/paymaster/backend/domain/service/ContractService.java:210-225
Automatic Status Updates
The updateContractStatuses method is designed to be run periodically. It checks all ACTIVE contracts and:
- Changes the status to
COMPLETEDif all installments are paid. - Changes the status to
OVERDUEif any installment is overdue.
Sources: src/main/java/com/paymaster/backend/domain/service/ContractService.java:230-252
Controller and UI
The HomeController exposes endpoints for UI interaction, and the Thymeleaf templates render the views.
Endpoints
The following endpoints are defined in HomeController for contract management:
| Method | Path | Description |
|---|---|---|
GET | /contracts | Displays a paginated list of contracts, with optional filtering by status. |
GET | /contracts/new | Displays the form to create a new contract. |
POST | /contracts/save | Processes the new contract form submission, creates the contract, and redirects. |
GET | /contracts/view/{id} | Displays the detailed view of a specific contract and its installments. |
POST | /contracts/cancel/{id} | Cancels a contract. |
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:191-295
Contract Creation Form (contracts/form.html)
The creation form allows users to select a customer and input financial details. A key feature is the real-time calculation preview, which uses JavaScript to call a backend API.
- Customer Selection: A dropdown lists all active customers.
- Financial Inputs: Fields for principal amount, interest rate, and number of installments.
- Calculation Preview: A section dynamically updates to show the calculated total interest, total amount, and installment amount.
This preview is powered by the calculateInstallments function in app.js, which sends an AJAX request to the /api/calculate-installments endpoint.
// src/main/resources/static/js/app.js:410
calculate: async function() {
const principal = parseInt(document.getElementById('principalAmount')?.value) || 0;
const rate = parseFloat(document.getElementById('interestRate')?.value) || 0;
const months = parseInt(document.getElementById('installmentCount')?.value) || 0;
// ...
try {
const data = await ApiService.calculateInstallments(principal, rate, months);
this.displayResults(data);
this.updateChart(data.principal, data.interest);
} // ...
},
Sources: src/main/resources/templates/contracts/form.html:10-100, src/main/resources/static/js/app.js:405-426
Contract List View (contracts/list.html)
This page displays all contracts in a paginated table. Key features include:
- Filtering: Tabs allow filtering contracts by their status (
ACTIVE,OVERDUE, etc.). - Pagination: Navigation controls for moving between pages of results.
- Summary Data: Each row shows key details like contract number, customer, amounts, installment progress, and status.
- Progress Bar: A visual indicator of the payment progress for each contract.
Sources: src/main/resources/templates/contracts/list.html:24-85
Contract Detail View (contracts/view.html)
This view provides a comprehensive overview of a single contract, including:
- A summary card with financial details (principal, interest, total, remaining).
- A progress bar showing the percentage of the total amount paid.
- A detailed list of all associated installments, their due dates, statuses, and payment actions.
- An option to cancel the contract if it is still active.
Sources: src/main/resources/templates/contracts/view.html:21-104
Conclusion
The Contract Management feature is a robust and central part of the PayMaster application. It provides a clear data model, well-defined business logic in the ContractService, and a user-friendly interface for all contract-related operations. The automated generation of installments and real-time calculation previews on the frontend significantly improve user experience and data accuracy. The system's ability to track contract statuses automatically ensures that financial states like 'overdue' and 'completed' are always up-to-date.