UI: Customer Pages
Relevant source files
The following files were used as context for generating this wiki page:- src/main/resources/templates/customers/list.html
- src/main/resources/templates/customers/view.html
- src/main/resources/templates/customers/form.html
- src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
- src/main/resources/static/js/app.js
- src/main/resources/templates/fragments/layout.html
- src/main/resources/static/css/style.css
The Customer Pages are a core feature of the PayMaster application, providing the user interface for all Customer Relationship Management (CRM) functionalities. This module allows users to create, view, list, update, and delete customer records. The UI is built using Thymeleaf for server-side rendering, Bootstrap for styling, and vanilla JavaScript for client-side interactivity and validation.
The system is composed of three primary views: a list page to browse all customers, a detailed view page for a single customer, and a form for creating and editing customer information. These views are managed by the HomeController on the backend, which handles data retrieval and persistence.
Overall User Flow
The following diagram illustrates the typical navigation flow for a user managing customers within the application.
Customer List Page
The Customer List page, accessible at /customers, is the main entry point for customer management. It displays a paginated and searchable list of all customers in the system.
Sources: src/main/resources/templates/customers/list.html, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:68-87
Features
- Search: Users can search for customers by a keyword, which queries the
fullName,nationalCode, ormobilefields. - Pagination: The list is paginated, with controls to navigate between pages. The page size is fixed at 10 items per page.
- Actions: Each customer row provides quick actions to
View,Edit, orDeletethe customer. - Empty State: If no customers are found, a user-friendly message is displayed with a call-to-action to create the first customer.
Displayed Information
The table on this page presents a summary of each customer's information.
| Column | Description | Data Source |
|---|---|---|
| # | Row number | iter.index |
| نام و نامخانوادگی | Customer's full name, linked to the view page. | customer.fullName |
| کد ملی | Customer's 10-digit national code. | customer.nationalCode |
| موبایل | Customer's mobile number. | customer.mobile |
| وضعیت | Customer's status (e.g., Active), displayed as a colored badge. | customer.status.persianName |
| قراردادها | The count of active contracts for the customer. | customer.activeContractsCount |
| تاریخ ثبت | The date the customer was created. | customer.createdAt |
| عملیات | A button group for View, Edit, and Delete actions. | Links to /customers/view, /edit, /delete |
Sources: src/main/resources/templates/customers/list.html:61-128
Delete Confirmation
The delete action is protected by a confirmation modal to prevent accidental deletion. The modal asks the user to confirm the action before submitting a POST request to /customers/delete/{id}.
Sources: src/main/resources/templates/customers/list.html:105-125
Customer Form Page
The form, located at customers/form.html, serves a dual purpose for both creating (/customers/new) and editing (/customers/edit/{id}) customers. The backend controller passes a boolean flag isEdit to the template to conditionally change titles, button labels, and icons.
Sources: src/main/resources/templates/customers/form.html:2-29, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:93-100, 131-142
Form Fields
The form captures essential customer information. Required fields are marked with an asterisk.
| Field | Label | Type | Validation |
|---|---|---|---|
fullName | نام و نامخانوادگی | text | required, minlength="2", maxlength="100" |
nationalCode | کد ملی | text | required, pattern="\d{10}", maxlength="10", AJAX uniqueness check |
mobile | شماره موبایل | text | required, pattern="09\d{9}", maxlength="11", AJAX uniqueness check |
phone | تلفن ثابت | text | maxlength="11" |
email | ایمیل | email | Valid email format |
postalCode | کد پستی | text | maxlength="10" |
status | وضعیت | select | Dropdown of CustomerStatus enum values |
address | آدرس | textarea | maxlength="500" |
notes | یادداشت | textarea | maxlength="1000" |
Sources: src/main/resources/templates/customers/form.html:35-131
Client-Side Validation
The form includes real-time, client-side validation for the nationalCode and mobile fields to provide immediate feedback to the user. This is handled by app.js.
National Code Validation Flow
When a user enters a 10-digit national code and the input field loses focus, a fetch request is sent to the backend to check for its validity and uniqueness.
This diagram shows the asynchronous validation process for the national code.
Sources: src/main/resources/templates/customers/form.html:151-186, src/main/resources/static/js/app.js:335-377
The mobile number validation follows a similar flow, checking for the correct format (09\d{9}) and uniqueness via an API call.
Sources: src/main/resources/static/js/app.js:382-414
Server-Side Submission
Upon submission, the form data is sent via a POST request to /customers/save. The HomeController#saveCustomer method handles the request.
This diagram outlines the server-side logic for creating or updating a customer.
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:102-129
Customer View Page
The Customer View page, accessible at /customers/view/{id}, provides a comprehensive overview of a single customer. It aggregates personal data, contact information, and a summary of their associated contracts.
Sources: src/main/resources/templates/customers/view.html, src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:144-158
Page Structure
The page is divided into two main columns:
- Left Column (Customer Details):
- Displays the customer's name, national code, and status badge.
- A list group shows contact details like mobile, phone, and email.
- Provides buttons to "Edit" the customer or create a "New Contract" for them.
- Shows address and postal code if available.
- Right Column (Contracts & Stats):
- A table lists all contracts associated with the customer, showing the contract number, total amount, status, and payment progress.
- A summary card displays key statistics: total number of contracts, number of active contracts, and total debt.
This layout provides a 360-degree view of the customer's relationship with the business.
Sources: src/main/resources/templates/customers/view.html:22-139
Conclusion
The Customer Pages module is a well-structured and user-friendly interface for managing customer data. It effectively uses a combination of server-side rendering with Thymeleaf and client-side enhancements with JavaScript to provide a responsive and efficient user experience. The clear separation of concerns between the list, form, and view pages, all orchestrated by the HomeController, results in a maintainable and scalable feature. The inclusion of real-time validation significantly improves data quality and user satisfaction.