Feature: Customer Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/main/java/com/paymaster/backend/domain/entity/Customer.java
• src/main/java/com/paymaster/backend/domain/service/CustomerService.java
• src/main/java/com/paymaster/backend/domain/repository/CustomerRepository.java
• src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
• src/main/resources/templates/customers/list.html
• src/main/resources/templates/customers/form.html
• src/main/resources/templates/customers/view.html
• src/main/resources/static/js/app.js

The Customer Management feature is a core component of the PayMaster system, responsible for handling all operations related to customer data. This includes creating, reading, updating, deleting (CRUD), and searching for customer records. Customers are the primary entities for whom installment contracts are created, making this module fundamental to the application's purpose.

The feature is implemented using a standard three-tier architecture (Controller, Service, Repository) on the backend, with server-side rendered templates using Thymeleaf for the user interface. It includes robust validation for key fields like National Code and mobile number, both on the client and server sides.

Backend Architecture

The backend follows a layered architecture to separate concerns, consisting of a Controller for handling web requests, a Service for business logic, and a Repository for data access.

This diagram shows the flow of a request from the user through the application layers to the database and back.
Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java, src/main/java/com/paymaster/backend/domain/service/CustomerService.java, src/main/java/com/paymaster/backend/domain/repository/CustomerRepository.java

Data Model (Customer Entity)

The Customer entity represents a customer in the system. It is mapped to the customers table in the database and contains personal information, contact details, and status.

Sources: src/main/java/com/paymaster/backend/domain/entity/Customer.java

Entity Relationship Diagram

The Customer has a one-to-many relationship with the Contract entity. One customer can have multiple contracts.

Fields and Validations

The table below details the fields of the Customer entity, along with their validation rules defined using jakarta.validation.constraints.

Field	Type	Column Name	Constraints	Description
id	Long	id	@Id	Primary key.
fullName	String	full_name	@NotBlank, @Size(min=2, max=100)	Customer's full name.
nationalCode	String	national_code	@NotBlank, @Pattern(regexp="^\\d{10}$"), unique=true	10-digit unique national ID.
mobile	String	mobile	@NotBlank, @Pattern(regexp="^09\\d{9}$")	11-digit mobile number.
phone	String	phone	-	Landline phone number.
email	String	email	@Email	Customer's email address.
address	String	address	@Size(max=500)	Customer's physical address.
postalCode	String	postal_code	@Pattern(regexp="^\\d{10}$")	10-digit postal code.
status	CustomerStatus	status	@Enumerated(EnumType.STRING), nullable=false	Customer status (e.g., ACTIVE, INACTIVE). Defaults to ACTIVE.
notes	String	notes	@Size(max=1000)	Internal notes about the customer.
contracts	List<Contract>	-	@OneToMany	List of associated contracts.

Sources: src/main/java/com/paymaster/backend/domain/entity/Customer.java:23-98

Controller (HomeController)

The HomeController manages all HTTP requests related to customers. It maps URLs to specific service methods and prepares the data for the view layer.

Method	HTTP Verb	Path	Description
listCustomers	GET	/customers	Displays a paginated list of customers. Supports search via a keyword parameter.
newCustomerForm	GET	/customers/new	Displays the form to create a new customer.
saveCustomer	POST	/customers/save	Saves a new customer or updates an existing one. Performs validation.
editCustomerForm	GET	/customers/edit/{id}	Displays the form to edit an existing customer's details.
viewCustomer	GET	/customers/view/{id}	Shows a detailed view of a single customer and their contracts.
deleteCustomer	POST	/customers/delete/{id}	Deletes a customer.

Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:70-184

Service (CustomerService)

The CustomerService contains the core business logic for customer management. It acts as an intermediary between the controller and the repository.

Key methods include:

• search(String keyword, int page, int size): Searches for customers by a keyword in their name, national code, or mobile number. If the keyword is empty, it returns all customers.
• save(Customer customer): Saves a new customer after validating that the national code and mobile number are not duplicates.
• update(Long id, Customer updatedCustomer): Updates an existing customer's information, checking for duplicate national code/mobile if they are changed.
• delete(Long id): Deletes a customer only if they have no associated contracts.
• isValidNationalCode(String nationalCode): A utility method to perform algorithmic validation of an Iranian national code.

Sources: src/main/java/com/paymaster/backend/domain/service/CustomerService.java

Repository (CustomerRepository)

CustomerRepository is a Spring Data JPA interface that handles all database operations for the Customer entity.

It defines several custom queries using the @Query annotation, including a general-purpose search method:

@Query("SELECT c FROM Customer c WHERE " +
        "LOWER(c.fullName) LIKE LOWER(CONCAT('%', :keyword, '%')) OR " +
        "c.nationalCode LIKE CONCAT('%', :keyword, '%') OR " +
        "c.mobile LIKE CONCAT('%', :keyword, '%')")
Page<Customer> searchByKeyword(@Param("keyword") String keyword, Pageable pageable);

This query allows searching across multiple fields with a single keyword.

Sources: src/main/java/com/paymaster/backend/domain/repository/CustomerRepository.java:96-100

User Interface (UI)

The UI for customer management consists of several Thymeleaf templates that are rendered server-side.

Customer List (customers/list.html)

This page displays all customers in a paginated table.

• Search: A search bar allows users to filter customers by name, national code, or mobile. The search is triggered by submitting a form with the keyword parameter to /customers.
• Actions: Each row provides buttons to "View", "Edit", and "Delete" a customer.
• Deletion: The delete action is handled via a confirmation modal to prevent accidental deletion.

Sources: src/main/resources/templates/customers/list.html

Customer Form (customers/form.html)

This form is used for both creating and editing customers.

• Fields: It includes inputs for all Customer entity fields. Required fields are marked with an asterisk.
• Client-Side Validation: The form utilizes JavaScript for real-time validation of the National Code and Mobile Number. On blur, an AJAX request is sent to an API endpoint to check for validity and uniqueness.

The following diagram illustrates the client-side validation for the National Code field.

Customer View (customers/view.html)

This page provides a detailed, read-only view of a single customer.

• Customer Details: Displays the customer's personal and contact information.
• Contracts List: Shows a table of all contracts associated with the customer, including their status and progress.
• Summary Stats: Includes a summary of the total number of contracts, active contracts, and total debt for the customer.

Sources: src/main/resources/templates/customers/view.html

Key Workflows

Creating a New Customer

This workflow describes the process of adding a new customer to the system.

Deleting a Customer

The deletion process includes a critical business rule: a customer cannot be deleted if they have existing contracts.

Summary

The Customer Management feature is a well-structured and essential part of the PayMaster application. It effectively uses a layered architecture, server-side rendering with Thymeleaf, and both client-side and server-side validation to provide a reliable and user-friendly experience for managing customer data. The clear separation of concerns between the controller, service, and repository layers makes the feature maintainable and scalable.