UI: Contract Pages
Relevant source files
The following files were used as context for generating this wiki page:
- src/main/resources/templates/contracts/list.html
- src/main/resources/templates/contracts/view.html
- src/main/resources/templates/contracts/form.html
- src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
- src/main/resources/static/js/app.js
- src/main/java/com/paymaster/backend/domain/service/ContractService.java
- src/main/resources/templates/customers/view.html
The Contract Pages are a core feature of the PayMaster application, providing the user interface for managing the entire lifecycle of contracts. This includes listing and filtering existing contracts, creating new contracts with real-time calculation previews, and viewing detailed information about a specific contract, including its associated installments and payment status.
The UI is composed of three main Thymeleaf templates: list.html for an overview, form.html for creation, and view.html for detailed inspection and actions. These pages are served by the HomeController and interact with the ContractService for business logic and data persistence.
Contract List Page
The Contract List page, accessible at /contracts, serves as the main dashboard for managing all contracts within the system. It provides a paginated and filterable view of contracts.
Sources: src/main/resources/templates/contracts/list.html, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:200-226
Features
- Contract Count: Displays the total number of contracts.
- New Contract Button: A prominent button to navigate to the contract creation form (
/contracts/new). - Status Filtering: Users can filter the contract list by status (e.g.,
ACTIVE,COMPLETED). The "All" tab shows contracts regardless of status. - Paginated Table: The main content is a table listing contracts with key details. Pagination controls are available if the total number of pages is greater than one.
- Empty State: If no contracts are found, a user-friendly message is displayed with a call-to-action to create the first contract.
Data Flow
The following diagram illustrates the data flow when a user requests the contract list page.
Displayed Information
The table on this page displays the following columns for each contract:
| Column | Description | Data Source |
|---|---|---|
| شماره قرارداد (Contract Number) | The unique contract identifier. Links to the contract view page. | contract.contractNumber |
| مشتری (Customer) | The full name of the customer associated with the contract. Links to the customer view page. | contract.customer.fullName |
| مبلغ اصل (Principal Amount) | The initial amount of the loan. | contract.principalAmount |
| مبلغ کل (Total Amount) | The principal amount plus total interest. | contract.totalAmount |
| اقساط (Installments) | The ratio of paid installments to the total number of installments. | contract.paidInstallmentsCount / contract.installmentCount |
| تاریخ شروع (Start Date) | The start date of the contract. | contract.startDate |
| وضعیت (Status) | The current status of the contract (e.g., Active, Completed), displayed as a colored badge. | contract.status.persianName |
| پیشرفت (Progress) | A progress bar and percentage indicating the payment progress. | contract.progressPercentage |
| عملیات (Actions) | A button to view the contract details. | Link to /contracts/view/{id} |
Sources: src/main/resources/templates/contracts/list.html:41-100
New Contract Form
The "New Contract" form, located at /contracts/new, allows users to create a new contract. It features a two-column layout for data entry and a real-time calculation preview.
Sources: src/main/resources/templates/contracts/form.html, src/main/resources/static/js/app.js:463-605
Form Fields and Layout
The form is divided into two main sections:
- Customer and Contract Information:
- A dropdown to select an existing customer.
- Input fields for financial details like Principal Amount, Annual Interest Rate, and Number of Installments.
- A date picker for the contract's start date.
- Calculation Preview:
- A section that dynamically updates to show the calculated Principal, Interest, Total Amount, and per-installment amount.
- A doughnut chart (
pieChart) visually representing the ratio of principal to interest.
Sources: src/main/resources/templates/contracts/form.html:31-131
Real-Time Calculation
A key feature of this form is the real-time calculation preview. As the user modifies the principalAmount, interestRate, or installmentCount, a JavaScript function is triggered.
The calculateInstallments function in form.html (or ContractCalculator in app.js) sends an AJAX request to the backend. The backend responds with the calculated values, which are then displayed in the "Preview" section and used to update the chart.
Sources: src/main/resources/templates/contracts/form.html:229-253, src/main/resources/static/js/app.js:463-513
The following diagram shows the sequence of events for the real-time calculation.
Contract Creation Flow
Upon submission, the form POSTs data to /contracts/save. The saveContract method in HomeController orchestrates the creation process.
- It receives the form data as request parameters.
- It calls
dateUtils.toGregorianDateto convert the Persian date string to aLocalDateobject. - It invokes
contractService.createContractwith all the necessary parameters. - The
ContractServiceperforms business logic: generates a unique contract number, calculates financial amounts, creates theContractentity, and generates all associatedInstallmententities. - If successful, the user is redirected to the view page for the newly created contract. If an error occurs, the user is redirected back to the form with an error message.
The following flowchart visualizes the server-side creation process.
Contract View Page
The Contract View page (/contracts/view/{id}) provides a comprehensive, read-only summary of a single contract and its installments. It also serves as the primary interface for recording payments.
Sources: src/main/resources/templates/contracts/view.html
Page Layout and Components
The page is structured into two main columns:
-
Contract Summary (Left Column):
- Displays the contract number and status badge.
- Shows customer information with a link to the customer's detail page.
- A progress bar visualizes the percentage of the contract paid off.
- A summary box details the Principal, Interest, Total, and Remaining amounts.
- A list group provides other key details like installment count, start/end dates, and interest rate.
- An action button to "Cancel Contract" is available for active contracts, which triggers a confirmation modal.
-
Installment List (Right Column):
- A table listing every installment for the contract.
- Rows for overdue installments are highlighted with the
table-danger-subtleclass. - Each row displays the installment number, amount, due date, paid amount, penalty, and status.
- Action buttons for payment are available for unpaid installments.
Sources: src/main/resources/templates/contracts/view.html:22-148
Payment Actions
For each installment that is not yet PAID, two payment options are provided:
- Quick Pay: A form that POSTs to
/installments/quick-pay/{id}. This action settles the installment for its full remaining amount, including any calculated penalties. - Custom Pay: A button that opens a modal (
payModal). This modal allows the user to enter a custom payment amount, select a payment method, and add optional notes or a receipt number. The form POSTs to/installments/pay/{id}.
The sequence diagram below shows the flow for a custom payment.