Feature: Entity Status Lifecycle

Relevant source files

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

• src/main/java/com/paymaster/backend/domain/valueobject/CustomerStatus.java
• src/main/java/com/paymaster/backend/domain/valueobject/ContractStatus.java
• src/main/java/com/paymaster/backend/domain/valueobject/InstallmentStatus.java
• src/main/java/com/paymaster/backend/domain/entity/Customer.java
• src/main/java/com/paymaster/backend/domain/entity/Contract.java
• src/main/java/com/paymaster/backend/presentation/controller/HomeController.java
• src/main/resources/templates/customers/list.html
• src/main/resources/templates/contracts/list.html
• src/main/resources/static/css/style.css

The Entity Status Lifecycle feature is a core component of the PayMaster system, responsible for managing and tracking the state of key business entities: Customer, Contract, and Installment. This is achieved through a set of Java enum types that define a finite set of possible statuses for each entity. These statuses are fundamental to the application's business logic, data persistence, and user interface representation.

The system uses these enums to control workflows, filter data, and provide clear visual feedback to the user. For example, only customers with an ACTIVE status can be assigned to new contracts, and contract lists can be filtered by their status (e.g., ACTIVE, FINISHED). Each status enum includes a Persian name (persianName) and a CSS class (badgeClass) for consistent and internationalized UI rendering.

Core Components

The status management system is built around three primary enum value objects, each corresponding to a major domain entity.

This diagram illustrates the relationship between the main entities and their corresponding status enums.

Customer Status

The CustomerStatus enum defines the lifecycle of a customer within the system. The status is stored in the customers table as a string. The default status for a new customer is ACTIVE.

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

States

Status	Persian Name	Badge Class	Description
ACTIVE	فعال	success	The customer is active and can be assigned to new contracts.
INACTIVE	غیرفعال	secondary	The customer is inactive, e.g., after settling all contracts.
BLOCKED	مسدود	danger	The customer is blocked due to policy violations or bad payment history.
PENDING	در انتظار	warning	The customer is in the initial registration or validation process.

Sources: src/main/java/com/paymaster/backend/domain/valueobject/CustomerStatus.java:8-23

State Diagram

This diagram shows the defined states for a customer. The application logic, such as in HomeController, primarily uses the ACTIVE status to determine eligibility for new contracts.

Contract Status

The ContractStatus enum manages the state of a contract from creation to completion. The default status for a new contract is DRAFT.

Sources: src/main/java/com/paymaster/backend/domain/entity/Contract.java:122-125

States

Status	Persian Name	Badge Class	Description
DRAFT	پیش‌نویس	secondary	The contract is created but not yet finalized or active.
ACTIVE	فعال	primary	The contract is active, and installments are being tracked.
FINISHED	خاتمه‌یافته	success	The contract is fully paid and completed.
CANCELED	لغوشده	danger	The contract has been canceled before completion.

Sources: src/main/java/com/paymaster/backend/domain/valueobject/ContractStatus.java

State Diagram & Flow

The status of a contract progresses based on business actions. For example, creating a contract sets it to DRAFT, and after finalization (not explicitly shown but implied), it becomes ACTIVE. It can be CANCELED from either DRAFT or ACTIVE states. Once all payments are made, it moves to FINISHED.

The UI allows users to filter the list of contracts based on these statuses.

This sequence diagram shows the flow for filtering contracts by status.

Installment Status

The InstallmentStatus enum tracks the payment status of each individual installment.

States

Status	Persian Name	Badge Class	Description
PENDING	در انتظار پرداخت	warning	The installment is due but not yet paid.
PAID	پرداخت‌شده	success	The installment has been fully paid.
OVERDUE	معوق	danger	The due date has passed, and the installment is not fully paid.
PARTIALLY_PAID	پرداخت ناقص	info	The installment has been partially paid but is not yet complete.

Sources: src/main/java/com/paymaster/backend/domain/valueobject/InstallmentStatus.java

State Diagram

An installment begins as PENDING. It can become OVERDUE if the due date passes. Payments can transition it to PARTIALLY_PAID and finally to PAID.

UI and Visual Representation

The status enums are designed to integrate directly with the frontend. The badgeClass property is used to apply specific CSS classes for styling status badges, providing immediate visual cues to the user.

Sources: src/main/java/com/paymaster/backend/domain/valueobject/CustomerStatus.java:40-43

The CSS file style.css defines the colors associated with these classes using CSS variables.

/* src/main/resources/static/css/style.css:15-20 */
:root {
    /* ... */
    --pm-success: #2ecc71;
    --pm-warning: #f39c12;
    --pm-danger: #e74c3c;
    --pm-info: #17a2b8;
    /* ... */
}

Sources: src/main/resources/static/css/style.css:15-20

A Thymeleaf template, such as customers/list.html, dynamically generates the badge using the properties from the enum object.

<!-- src/main/resources/templates/customers/list.html:80-82 -->
<span class="badge"
      th:classappend="'bg-' + ${customer.status.badgeClass}"
      th:text="${customer.status.persianName}"></span>

Sources: src/main/resources/templates/customers/list.html:80-82

This approach ensures that the visual representation of a status is consistently managed from the backend, making the UI robust and easy to maintain.

Conclusion

The Entity Status Lifecycle feature is a well-designed and integral part of the PayMaster application. By using Java enums (CustomerStatus, ContractStatus, InstallmentStatus), the system establishes a clear, type-safe, and maintainable way to manage the state of its core entities. This design directly influences business logic, database queries, and provides a rich, consistent user experience through dynamic UI rendering based on entity state. The inclusion of metadata like persianName and badgeClass within the enums is a key design choice that tightly couples the backend state model with its frontend representation, simplifying development and ensuring consistency.