Feature: Reporting

Relevant source files

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

• src/main/resources/templates/reports/index.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/repository/InstallmentRepository.java
• src/main/resources/templates/fragments/layout.html
• src/main/resources/static/css/style.css
• pom.xml
• src/main/resources/templates/contracts/form.html
• src/main/resources/templates/contracts/list.html
• src/main/resources/templates/customers/form.html

The Reporting feature provides a high-level, visual overview of the system's key metrics. It consists of a dedicated page that displays statistical summaries and graphical charts related to customers, contracts, and financial receivables. This allows users to quickly assess the overall health and performance of the installment management operations.

The feature is accessible via the "گزارش‌ها" (Reports) link in the main navigation bar.

Sources: src/main/resources/templates/fragments/layout.html:66-68, src/main/resources/templates/reports/index.html:12-14

Architecture

The reporting feature follows a standard Model-View-Controller (MVC) pattern. A user request to the /reports endpoint is handled by the HomeController, which gathers the necessary statistics via the DashboardService. This data is then passed to a Thymeleaf template (reports/index.html) for rendering. On the client-side, JavaScript using the Chart.js library visualizes the data.

Sources: src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:381-387, src/main/resources/templates/reports/index.html

Data Flow

The following diagram illustrates the data flow for the reporting page.

Backend Components

HomeController

The HomeController is responsible for handling the web request for the reporting page.

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

/reports Endpoint

This endpoint handles GET requests to /reports. It retrieves the DashboardStats object from the DashboardService, adds it to the Spring Model, and returns the logical view name reports/index to be rendered by Thymeleaf.

// src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:381-387
@GetMapping("/reports")
public String reports(Model model) {
    DashboardService.DashboardStats stats = dashboardService.getDashboardStats();
    model.addAttribute("stats", stats);
    model.addAttribute("dateUtils", dateUtils);
    return "reports/index";
}

DashboardService.DashboardStats

This is a data transfer object used to pass aggregated statistics from the backend to the frontend. While the class definition is not present, its structure can be inferred from its usage in HomeController and reports/index.html.

Field	Type	Description	Source -
totalCustomers	long	The total number of customers in the system.	src/main/resources/templates/reports/index.html:23 -
activeContracts	long	The number of contracts that are currently active.	src/main/resources/templates/reports/index.html:31 -
totalReceivedFormatted	String	The total amount received from paid installments, formatted as a string.	src/main/resources/templates/reports/index.html:39 -
overdueInstallments	long	The number of installments that are past their due date and unpaid.	src/main/resources/templates/reports/index.html:48 -
totalReceivable	long	The total amount of all installments (paid and unpaid).	src/main/resources/templates/reports/index.html:110 -
totalReceived	long	The total amount received from paid installments (raw number).	src/main/resources/templates/reports/index.html:111, src/main/resources/templates/reports/index.html:129 -
totalOverdue	long	The total monetary value of all overdue installments.	src/main/resources/templates/reports/index.html:112 -

Frontend Components

The frontend is built using Thymeleaf for server-side rendering, HTML, and JavaScript for client-side interactivity, specifically for rendering charts.

Sources: src/main/resources/templates/reports/index.html, src/main/resources/static/js/app.js, src/main/resources/static/css/style.css

reports/index.html

This is the main view file for the reporting feature. It defines the structure of the page, including summary cards and chart canvases.

Summary Cards

The page displays four main summary cards, providing a quick snapshot of key metrics. Each card uses data from the stats object passed by the controller.

<!-- src/main/resources/templates/reports/index.html:18-26 -->
<div class="col-md-3">
    <div class="card border-0 shadow-sm text-center py-4">
        <div class="card-body">
            <i class="bi bi-people fs-1 text-primary mb-3 d-block"></i>
            <h3 th:text="${stats.totalCustomers}">0</h3>
            <p class="text-muted mb-0">کل مشتریان</p>
        </div>
    </div>
</div>

The four cards display:

1. Total Customers (stats.totalCustomers)
2. Active Contracts (stats.activeContracts)
3. Total Received (stats.totalReceivedFormatted)
4. Overdue Installments (stats.overdueInstallments)

Sources: src/main/resources/templates/reports/index.html:18-52

Chart Visualizations

The page includes two charts rendered using the Chart.js library. The chart data is injected directly into the JavaScript via Thymeleaf's inline script capabilities.

Sources: pom.xml:29, src/main/resources/templates/fragments/layout.html:125, src/main/resources/templates/reports/index.html:100-143

The following diagram shows the components involved in rendering the charts on the frontend.

Receivables Chart

• Type: Bar Chart
• ID: receivablesChart
• Description: This chart provides a financial breakdown of receivables.
• Data:
  • Total Receivables: stats.totalReceivable
  • Received: stats.totalReceived
  • Overdue: stats.totalOverdue

// src/main/resources/templates/reports/index.html:102-121
new Chart(document.getElementById('receivablesChart'), {
    type: 'bar',
    data: {
        labels: ['کل مطالبات', 'وصول شده', 'معوق'],
        datasets: [{
            label: 'مبلغ (ریال)',
            data: [
                [[${stats.totalReceivable}]],
                [[${stats.totalReceived}]],
                [[${stats.totalOverdue}]]
            ],
            backgroundColor: ['#3498db', '#2ecc71', '#e74c3c']
        }]
    },
    // ... options
});

Collection Chart

• Type: Doughnut Chart
• ID: collectionChart
• Description: This chart shows the proportion of collected funds versus remaining funds.
• Data:
  • Received: stats.totalReceived
  • Remaining: stats.totalReceivable - stats.totalReceived

// src/main/resources/templates/reports/index.html:124-142
new Chart(document.getElementById('collectionChart'), {
    type: 'doughnut',
    data: {
        labels: ['وصول شده', 'باقیمانده'],
        datasets: [{
            data: [
                [[${stats.totalReceived}]],
                [[${stats.totalReceivable - stats.totalReceived}]]
            ],
            backgroundColor: ['#2ecc71', '#95a5a6']
        }]
    },
    // ... options
});