Relevant source files

The following files were used as context for generating this wiki page: - [src/main/resources/templates/reports/index.html](https://github.com/tiknet10-byte/paymaster-v3/blob/main/src/main/resources/templates/reports/index.html) - [src/main/java/com/paymaster/backend/presentation/controller/HomeController.java](https://github.com/tiknet10-byte/paymaster-v3/blob/main/src/main/java/com/paymaster/backend/presentation/controller/HomeController.java) - [src/main/resources/static/js/app.js](https://github.com/tiknet10-byte/paymaster-v3/blob/main/src/main/resources/static/js/app.js) - [src/main/java/com/paymaster/backend/domain/repository/InstallmentRepository.java](https://github.com/tiknet10-byte/paymaster-v3/blob/main/src/main/java/com/paymaster/backend/domain/repository/InstallmentRepository.java) - [src/main/resources/templates/fragments/layout.html](https://github.com/tiknet10-byte/paymaster-v3/blob/main/src/main/resources/templates/fragments/layout.html) - [src/main/resources/static/css/style.css](https://github.com/tiknet10-byte/paymaster-v3/blob/main/src/main/resources/static/css/style.css) - [pom.xml](https://github.com/tiknet10-byte/paymaster-v3/blob/main/pom.xml) - [src/main/resources/templates/contracts/form.html](https://github.com/tiknet10-byte/paymaster-v3/blob/main/src/main/resources/templates/contracts/form.html) - [src/main/resources/templates/contracts/list.html](https://github.com/tiknet10-byte/paymaster-v3/blob/main/src/main/resources/templates/contracts/list.html) - [src/main/resources/templates/customers/form.html](https://github.com/tiknet10-byte/paymaster-v3/blob/main/src/main/resources/templates/customers/form.html)

# Feature: Reporting 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. ```mermaid sequenceDiagram participant User participant Browser participant SpringMVC as "Spring MVC" participant HomeController participant DashboardService participant ThymeleafEngine as "Thymeleaf Engine" User->>Browser: Clicks 'Reports' link (/reports) Browser->>SpringMVC: GET /reports SpringMVC->>HomeController: reports(model) HomeController->>DashboardService: getDashboardStats() DashboardService-->>HomeController: Returns DashboardStats object Note right of HomeController: Adds 'stats' object to Model HomeController-->>SpringMVC: Returns "reports/index" view name SpringMVC->>ThymeleafEngine: Process reports/index.html with Model data ThymeleafEngine-->>SpringMVC: Returns rendered HTML SpringMVC-->>Browser: Sends HTML response Browser->>Browser: Renders HTML and executes inline JavaScript Note over Browser: Initializes Chart.js with data from Thymeleaf ``` *Sources: [src/main/java/com/paymaster/backend/presentation/controller/HomeController.java:381-387](), [src/main/resources/templates/reports/index.html:100-143]()* ## 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. ```java // 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. ```html

0

کل مشتریان

``` 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. ```mermaid graph TD A[Thymeleaf Model 'stats'] --> B{reports/index.html}; B --> C[Inline JavaScript]; C --> D[Chart.js Library]; D --> E[Receivables Chart (Bar)]; D --> F[Collection Chart (Doughnut)]; ``` *Sources: [src/main/resources/templates/reports/index.html:100-143]()* #### 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` ```javascript // 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` ```javascript // 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 }); ```