VCST-4474: Improvements for dashboard statistic (#484)

Author: OlegoO

README.md

@@ -39,6 +39,82 @@ Virto Commerce Order module supports the following functionalities:
     * Manage order delivery (status, delivery details);
     * Repeated order creation (order cloning) with possibility to specify the frequency of order re-creation.
 
+Number template format: `<template>@<reset_type>[:<start>:<increment>]`
+- Reset types: `None`, `Daily`, `Weekly`, `Monthly`, `Yearly`
+- Example: `CO{0:yyMMdd}-{1:D5}@Weekly:1:10` (weekly reset, start at 1, increment by 10)
+
+#### Validation Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `Order.Validation.Enable` | `true` | Enable/disable order validation on save |
+| `Order.MaxOrderDocumentCount` | `20` | Maximum child documents per order |
+
+#### Feature Flags
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `Order.SendOrderNotifications` | `true` | Enable order status change notifications |
+| `Order.AdjustInventory` | `false` | Adjust inventory on order status changes |
+| `Order.LogOrderChanges` | `true` | Log changes to platform operation log |
+| `Order.Search.EventBasedIndexation.Enable` | `false` | Auto-update search index on changes |
+| `Order.PurchasedProductIndexation.Enable` | `false` | Enable purchased product indexing |
+| `Order.OrderPaidAndOrderSentNotifications.Enable` | `false` | Use order paid/sent notifications |
+| `Order.PaymentShipmentStatusChangedNotifications.Enable` | `false` | Use payment/shipment status notifications |
+
+#### Dashboard Statistics Settings
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `Order.DashboardStatistics.Enable` | `true` | Enable or disable order statistics widgets on the main dashboard |
+| `Order.DashboardStatistics.RangeMonths` | `12` | Number of months to include in dashboard statistics calculations |
+
+## Architecture
+
+### Project Structure
+
+```
+vc-module-order/
+??? src/
+?   ??? VirtoCommerce.OrdersModule.Core/         # Domain models, interfaces
+?   ??? VirtoCommerce.OrdersModule.Data/         # Data access, services, validators
+?   ??? VirtoCommerce.OrdersModule.Data.SqlServer/   # SQL Server migrations
+?   ??? VirtoCommerce.OrdersModule.Data.PostgreSql/  # PostgreSQL migrations
+?   ??? VirtoCommerce.OrdersModule.Data.MySql/       # MySQL migrations
+?   ??? VirtoCommerce.OrdersModule.Web/          # Web API, controllers
+??? tests/
+?   ??? VirtoCommerce.OrdersModule.Tests/        # Unit and integration tests
+??? docs/                                        # Documentation
+??? samples/                                     # Sample implementations
+```
+
+### Key Components
+
+- **CustomerOrderService**: Core service for order CRUD operations
+- **CustomerOrderSearchService**: Advanced search and filtering
+- **CustomerOrderTotalsCalculator**: Order totals calculation
+- **CustomerOrderValidator**: FluentValidation-based validation
+- **OrderDocumentCountValidator**: Document count limit enforcement
+- **OrderRepository**: Data access layer with EF Core
+
+### Domain Model
+
+```
+CustomerOrder (IOperation)
+??? LineItem[]
+??? Address[]
+??? PaymentIn[] (IOperation)
+?   ??? Capture[]
+?   ??? Refund[]
+??? Shipment[] (IOperation)
+?   ??? ShipmentItem[]
+?   ??? ShipmentPackage[]
+?   ??? Address
+??? DynamicProperties[]
+```
+
+
+
 ## Documentation
 
 * [Order module user documentation](https://docs.virtocommerce.org/platform/user-guide/order-management/overview/)

src/VirtoCommerce.OrdersModule.Core/ModuleConstants.cs

@@ -276,6 +276,30 @@ public static class General
                     IsPublic = true,
                 };
 
+                public static SettingDescriptor MaxOrderDocumentCount { get; } = new SettingDescriptor
+                {
+                    Name = "Order.MaxOrderDocumentCount",
+                    GroupName = "Orders|General",
+                    ValueType = SettingValueType.Integer,
+                    DefaultValue = 20,
+                };
+
+                public static SettingDescriptor DashboardStatisticsEnabled { get; } = new SettingDescriptor
+                {
+                    Name = "Order.DashboardStatistics.Enable",
+                    GroupName = "Orders|General",
+                    ValueType = SettingValueType.Boolean,
+                    DefaultValue = true,
+                };
+
+                public static SettingDescriptor DashboardStatisticsRangeMonths { get; } = new SettingDescriptor
+                {
+                    Name = "Order.DashboardStatistics.RangeMonths",
+                    GroupName = "Orders|General",
+                    ValueType = SettingValueType.PositiveInteger,
+                    DefaultValue = 12,
+                };
+
                 public static IEnumerable<SettingDescriptor> AllSettings
                 {
                     get
@@ -301,6 +325,9 @@ public static IEnumerable<SettingDescriptor> AllSettings
                         yield return PurchasedProductIndexation;
                         yield return EventBasedPurchasedProductIndexation;
                         yield return PurchasedProductStoreFilter;
+                        yield return MaxOrderDocumentCount;
+                        yield return DashboardStatisticsEnabled;
+                        yield return DashboardStatisticsRangeMonths;
                     }
                 }
             }

src/VirtoCommerce.OrdersModule.Web/Controllers/Api/OrderModuleController.cs

@@ -487,6 +487,24 @@ public async Task<ActionResult> DeleteOrdersByIds([FromQuery] string[] ids)
             return unauthorizedRequest ? Forbid() : NoContent();
         }
 
+        /// <summary>
+        /// Get dashboard statistics settings
+        /// </summary>
+        [HttpGet]
+        [Route("~/api/order/dashboardStatistics/settings")]
+        [Authorize(ModuleConstants.Security.Permissions.ViewDashboardStatistics)]
+        public async Task<ActionResult<object>> GetDashboardStatisticsSettingsAsync()
+        {
+            var enabled = await settingsManager.GetValueAsync<bool>(ModuleConstants.Settings.General.DashboardStatisticsEnabled);
+            var rangeMonths = await settingsManager.GetValueAsync<int>(ModuleConstants.Settings.General.DashboardStatisticsRangeMonths);
+
+            return Ok(new
+            {
+                Enabled = enabled,
+                RangeMonths = rangeMonths
+            });
+        }
+
         /// <summary>
         ///  Get a some order statistic information for Commerce manager dashboard
         /// </summary>
@@ -497,7 +515,18 @@ public async Task<ActionResult> DeleteOrdersByIds([FromQuery] string[] ids)
         [Authorize(ModuleConstants.Security.Permissions.ViewDashboardStatistics)]
         public async Task<ActionResult<DashboardStatisticsResult>> GetDashboardStatisticsAsync([FromQuery] DateTime? start = null, [FromQuery] DateTime? end = null)
         {
-            start ??= DateTime.UtcNow.AddYears(-1);
+            var dashboardEnabled = await settingsManager.GetValueAsync<bool>(ModuleConstants.Settings.General.DashboardStatisticsEnabled);
+            if (!dashboardEnabled)
+            {
+                return Ok(new DashboardStatisticsResult());
+            }
+
+            if (start == null)
+            {
+                var rangeMonths = await settingsManager.GetValueAsync<int>(ModuleConstants.Settings.General.DashboardStatisticsRangeMonths);
+                start = DateTime.UtcNow.AddMonths(-rangeMonths);
+            }
+
             end ??= DateTime.UtcNow;
 
             // Hack: to compensate for incorrect Local dates to UTC

src/VirtoCommerce.OrdersModule.Web/Localizations/de.VirtoCommerce.Orders.json

@@ -620,6 +620,18 @@
     "Order.PurchasedProductStoreFilter.Enable": {
       "title": "Aktivierung des Store-Filters für gekaufte Produkte",
       "description": "Zeigt den Filter für gekaufte Produkte im Store an."
+    },
+    "Order.MaxOrderDocumentCount": {
+      "title": "Maximale Anzahl von Unterdokumenten pro Bestellung",
+      "description": "Definiert die maximale Anzahl von Unterdokumenten (Zahlungen, Sendungen, Captures, Rückerstattungen usw.), die pro Bestellung erstellt oder gespeichert werden können. Dies gewährleistet Systemleistung, Speicheroptimierung und Datenkonsistenz. Bei Überschreitung dieser Grenze wird beim Speichern eine Ausnahme ausgelöst"
+    },
+    "Order.DashboardStatistics.Enable": {
+      "title": "Dashboard-Statistiken aktivieren",
+      "description": "Aktiviert oder deaktiviert die Bestellstatistik-Widgets auf dem Haupt-Dashboard"
+    },
+    "Order.DashboardStatistics.RangeMonths": {
+      "title": "Dashboard-Statistik Zeitraum (Monate)",
+      "description": "Definiert die Anzahl der Monate, die in die Dashboard-Statistikberechnungen einbezogen werden. Standard ist 12 Monate"
     }
   },
   "module": {

src/VirtoCommerce.OrdersModule.Web/Localizations/en.VirtoCommerce.Orders.json

@@ -620,6 +620,18 @@
     "Order.PurchasedProductStoreFilter.Enable": {
       "title": "Enable purchased product store filter",
       "description": "Display the purchased product filter for the store"
+    },
+    "Order.MaxOrderDocumentCount": {
+      "title": "Maximum number of child documents per order",
+      "description": "Defines the maximum number of child documents (payments, shipments, captures, refunds, etc.) that can be created or stored per order. This ensures system performance, storage optimization, and data consistency. An exception will be thrown on save if this limit is exceeded"
+    },
+    "Order.DashboardStatistics.Enable": {
+      "title": "Enable dashboard statistics",
+      "description": "Turn on or off the order statistics dashboard widgets on the main dashboard"
+    },
+    "Order.DashboardStatistics.RangeMonths": {
+      "title": "Dashboard statistics range (months)",
+      "description": "Defines the number of months to include in the dashboard statistics calculations. Default is 12 months"
     }
   },
   "module": {

src/VirtoCommerce.OrdersModule.Web/Localizations/es.VirtoCommerce.Orders.json

@@ -620,6 +620,18 @@
     "Order.PurchasedProductStoreFilter.Enable": {
       "title": "Habilitar el filtro de productos comprados en la tienda",
       "description": "Muestra el filtro de productos comprados en la tienda."
+    },
+    "Order.MaxOrderDocumentCount": {
+      "title": "Número máximo de documentos secundarios por pedido",
+      "description": "Define el número máximo de documentos secundarios (pagos, envíos, capturas, reembolsos, etc.) que se pueden crear o almacenar por pedido. Esto garantiza el rendimiento del sistema, la optimización del almacenamiento y la consistencia de los datos. Se generará una excepción al guardar si se excede este límite"
+    },
+    "Order.DashboardStatistics.Enable": {
+      "title": "Habilitar estadísticas del panel",
+      "description": "Activa o desactiva los widgets de estadísticas de pedidos en el panel principal"
+    },
+    "Order.DashboardStatistics.RangeMonths": {
+      "title": "Período de estadísticas del panel (meses)",
+      "description": "Define el número de meses a incluir en los cálculos de estadísticas del panel. El valor predeterminado es 12 meses"
     }
   },
   "module": {

src/VirtoCommerce.OrdersModule.Web/Localizations/fr.VirtoCommerce.Orders.json

@@ -621,6 +621,18 @@
     "Order.PurchasedProductStoreFilter.Enable": {
       "title": "Activer le filtre de produits achetés en magasin",
       "description": "Affiche le filtre de produits achetés pour le magasin."
+    },
+    "Order.MaxOrderDocumentCount": {
+      "title": "Nombre maximum de documents enfants par commande",
+      "description": "Définit le nombre maximum de documents enfants (paiements, expéditions, captures, remboursements, etc.) qui peuvent être créés ou stockés par commande. Cela garantit les performances du système, l'optimisation du stockage et la cohérence des données. Une exception sera levée lors de la sauvegarde si cette limite est dépassée"
+    },
+    "Order.DashboardStatistics.Enable": {
+      "title": "Activer les statistiques du tableau de bord",
+      "description": "Active ou désactive les widgets de statistiques de commandes sur le tableau de bord principal"
+    },
+    "Order.DashboardStatistics.RangeMonths": {
+      "title": "Période des statistiques du tableau de bord (mois)",
+      "description": "Définit le nombre de mois à inclure dans les calculs des statistiques du tableau de bord. La valeur par défaut est de 12 mois"
     }
   },
   "module": {

src/VirtoCommerce.OrdersModule.Web/Localizations/it.VirtoCommerce.Orders.json

@@ -620,6 +620,18 @@
     "Order.PurchasedProductStoreFilter.Enable": {
       "title": "Abilita il filtro dei prodotti acquistati nel negozio",
       "description": "Visualizza il filtro dei prodotti acquistati per il negozio."
+    },
+    "Order.MaxOrderDocumentCount": {
+      "title": "Numero massimo di documenti secondari per ordine",
+      "description": "Definisce il numero massimo di documenti secondari (pagamenti, spedizioni, acquisizioni, rimborsi, ecc.) che possono essere creati o memorizzati per ordine. Ciò garantisce le prestazioni del sistema, l'ottimizzazione dello storage e la coerenza dei dati. Verrà generata un'eccezione durante il salvataggio se questo limite viene superato"
+    },
+    "Order.DashboardStatistics.Enable": {
+      "title": "Abilita statistiche dashboard",
+      "description": "Attiva o disattiva i widget delle statistiche ordini sulla dashboard principale"
+    },
+    "Order.DashboardStatistics.RangeMonths": {
+      "title": "Intervallo statistiche dashboard (mesi)",
+      "description": "Definisce il numero di mesi da includere nei calcoli delle statistiche della dashboard. Il valore predefinito è 12 mesi"
     }
   },
   "module": {

src/VirtoCommerce.OrdersModule.Web/Localizations/ja.VirtoCommerce.Orders.json

@@ -620,6 +620,18 @@
     "Order.PurchasedProductStoreFilter.Enable": {
       "title": "購入済み商品ストアフィルターを有効にする",
       "description": "ストアで購入済み商品フィルターを表示します。"
+    },
+    "Order.MaxOrderDocumentCount": {
+      "title": "注文あたりの子ドキュメントの最大数",
+      "description": "注文ごとに作成または保存できる子ドキュメント（支払い、配送、キャプチャ、返金など）の最大数を定義します。これにより、システムパフォーマンス、ストレージの最適化、データの整合性が確保されます。この制限を超えた場合、保存時に例外がスローされます"
+    },
+    "Order.DashboardStatistics.Enable": {
+      "title": "ダッシュボード統計を有効にする",
+      "description": "メインダッシュボードの注文統計ウィジェットを有効または無効にします"
+    },
+    "Order.DashboardStatistics.RangeMonths": {
+      "title": "ダッシュボード統計の範囲（月）",
+      "description": "ダッシュボード統計計算に含める月数を定義します。デフォルトは12ヶ月です"
     }
   },
   "module": {

src/VirtoCommerce.OrdersModule.Web/Localizations/pl.VirtoCommerce.Orders.json

@@ -620,6 +620,18 @@
     "Order.PurchasedProductStoreFilter.Enable": {
       "title": "Włącz filtr zakupionych produktów w sklepie",
       "description": "Wyświetla filtr zakupionych produktów w sklepie."
+    },
+    "Order.MaxOrderDocumentCount": {
+      "title": "Maksymalna liczba dokumentów podrzędnych na zamówienie",
+      "description": "Określa maksymalną liczbę dokumentów podrzędnych (płatności, przesyłki, przechwycenia, zwroty itp.), które można utworzyć lub przechowywać dla jednego zamówienia. Zapewnia to wydajność systemu, optymalizację przechowywania i spójność danych. Jeśli ten limit zostanie przekroczony, podczas zapisywania zostanie zgłoszony wyjątek"
+    },
+    "Order.DashboardStatistics.Enable": {
+      "title": "Włącz statystyki pulpitu",
+      "description": "Włącza lub wyłącza widżety statystyk zamówień na głównym pulpicie"
+    },
+    "Order.DashboardStatistics.RangeMonths": {
+      "title": "Zakres statystyk pulpitu (miesiące)",
+      "description": "Określa liczbę miesięcy do uwzględnienia w obliczeniach statystyk pulpitu. Domyślnie 12 miesięcy"
     }
   },
   "module": {