feat: implement metrics provider pattern for modular dashboard statistics
This commit introduces a protocol-based metrics architecture that allows each module to provide its own statistics for dashboards without creating cross-module dependencies. Key changes: - Add MetricsProviderProtocol and MetricValue dataclass in contracts module - Add StatsAggregatorService in core module that discovers and aggregates metrics from all enabled modules - Implement metrics providers for all modules: - tenancy: vendor/user counts, team members, domains - customers: customer counts - cms: pages, media files - catalog: products - inventory: stock levels - orders: order counts, revenue - marketplace: import jobs, staging products - Update dashboard routes to use StatsAggregator instead of direct imports - Fix VendorPlatform junction table usage (Vendor.platform_id doesn't exist) - Add comprehensive documentation for the pattern This architecture ensures: - Dashboards always work (aggregator in core) - Each module owns its metrics (no cross-module coupling) - Optional modules are truly optional (can be removed without breaking app) - Multi-platform vendors are properly supported via VendorPlatform table Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -29,6 +29,13 @@ def _get_vendor_router():
|
||||
return vendor_router
|
||||
|
||||
|
||||
def _get_metrics_provider():
|
||||
"""Lazy import of metrics provider to avoid circular imports."""
|
||||
from app.modules.orders.services.order_metrics import order_metrics_provider
|
||||
|
||||
return order_metrics_provider
|
||||
|
||||
|
||||
# Orders module definition
|
||||
orders_module = ModuleDefinition(
|
||||
code="orders",
|
||||
@@ -133,6 +140,8 @@ orders_module = ModuleDefinition(
|
||||
models_path="app.modules.orders.models",
|
||||
schemas_path="app.modules.orders.schemas",
|
||||
exceptions_path="app.modules.orders.exceptions",
|
||||
# Metrics provider for dashboard statistics
|
||||
metrics_provider=_get_metrics_provider,
|
||||
)
|
||||
|
||||
|
||||
|
||||
308
app/modules/orders/services/order_metrics.py
Normal file
308
app/modules/orders/services/order_metrics.py
Normal file
@@ -0,0 +1,308 @@
|
||||
# app/modules/orders/services/order_metrics.py
|
||||
"""
|
||||
Metrics provider for the orders module.
|
||||
|
||||
Provides metrics for:
|
||||
- Order counts and status
|
||||
- Revenue metrics
|
||||
- Invoice statistics
|
||||
"""
|
||||
|
||||
import logging
|
||||
from datetime import datetime, timedelta
|
||||
from typing import TYPE_CHECKING
|
||||
|
||||
from sqlalchemy import func
|
||||
from sqlalchemy.orm import Session
|
||||
|
||||
from app.modules.contracts.metrics import (
|
||||
MetricValue,
|
||||
MetricsContext,
|
||||
MetricsProviderProtocol,
|
||||
)
|
||||
|
||||
if TYPE_CHECKING:
|
||||
pass
|
||||
|
||||
logger = logging.getLogger(__name__)
|
||||
|
||||
|
||||
class OrderMetricsProvider:
|
||||
"""
|
||||
Metrics provider for orders module.
|
||||
|
||||
Provides order and revenue metrics for vendor and platform dashboards.
|
||||
"""
|
||||
|
||||
@property
|
||||
def metrics_category(self) -> str:
|
||||
return "orders"
|
||||
|
||||
def get_vendor_metrics(
|
||||
self,
|
||||
db: Session,
|
||||
vendor_id: int,
|
||||
context: MetricsContext | None = None,
|
||||
) -> list[MetricValue]:
|
||||
"""
|
||||
Get order metrics for a specific vendor.
|
||||
|
||||
Provides:
|
||||
- Total orders
|
||||
- Orders by status
|
||||
- Revenue metrics
|
||||
"""
|
||||
from app.modules.orders.models import Order, OrderItem
|
||||
|
||||
try:
|
||||
# Total orders
|
||||
total_orders = (
|
||||
db.query(Order).filter(Order.vendor_id == vendor_id).count()
|
||||
)
|
||||
|
||||
# Orders in period (default to last 30 days)
|
||||
date_from = context.date_from if context else None
|
||||
if date_from is None:
|
||||
date_from = datetime.utcnow() - timedelta(days=30)
|
||||
|
||||
orders_in_period_query = db.query(Order).filter(
|
||||
Order.vendor_id == vendor_id,
|
||||
Order.created_at >= date_from,
|
||||
)
|
||||
if context and context.date_to:
|
||||
orders_in_period_query = orders_in_period_query.filter(
|
||||
Order.created_at <= context.date_to
|
||||
)
|
||||
orders_in_period = orders_in_period_query.count()
|
||||
|
||||
# Total order items
|
||||
total_order_items = (
|
||||
db.query(OrderItem)
|
||||
.join(Order, Order.id == OrderItem.order_id)
|
||||
.filter(Order.vendor_id == vendor_id)
|
||||
.count()
|
||||
)
|
||||
|
||||
# Revenue (sum of order totals) - if total_amount field exists
|
||||
try:
|
||||
total_revenue = (
|
||||
db.query(func.sum(Order.total_amount))
|
||||
.filter(Order.vendor_id == vendor_id)
|
||||
.scalar()
|
||||
or 0
|
||||
)
|
||||
|
||||
revenue_in_period = (
|
||||
db.query(func.sum(Order.total_amount))
|
||||
.filter(
|
||||
Order.vendor_id == vendor_id,
|
||||
Order.created_at >= date_from,
|
||||
)
|
||||
.scalar()
|
||||
or 0
|
||||
)
|
||||
except Exception:
|
||||
# Field may not exist
|
||||
total_revenue = 0
|
||||
revenue_in_period = 0
|
||||
|
||||
# Average order value
|
||||
avg_order_value = round(total_revenue / total_orders, 2) if total_orders > 0 else 0
|
||||
|
||||
return [
|
||||
MetricValue(
|
||||
key="orders.total",
|
||||
value=total_orders,
|
||||
label="Total Orders",
|
||||
category="orders",
|
||||
icon="shopping-cart",
|
||||
description="Total orders received",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.in_period",
|
||||
value=orders_in_period,
|
||||
label="Recent Orders",
|
||||
category="orders",
|
||||
icon="clock",
|
||||
description="Orders in the selected period",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.total_items",
|
||||
value=total_order_items,
|
||||
label="Total Items Sold",
|
||||
category="orders",
|
||||
icon="box",
|
||||
description="Total order items",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.total_revenue",
|
||||
value=float(total_revenue),
|
||||
label="Total Revenue",
|
||||
category="orders",
|
||||
icon="currency-euro",
|
||||
unit="EUR",
|
||||
description="Total revenue from orders",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.revenue_period",
|
||||
value=float(revenue_in_period),
|
||||
label="Period Revenue",
|
||||
category="orders",
|
||||
icon="trending-up",
|
||||
unit="EUR",
|
||||
description="Revenue in the selected period",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.avg_value",
|
||||
value=avg_order_value,
|
||||
label="Avg Order Value",
|
||||
category="orders",
|
||||
icon="calculator",
|
||||
unit="EUR",
|
||||
description="Average order value",
|
||||
),
|
||||
]
|
||||
except Exception as e:
|
||||
logger.warning(f"Failed to get order vendor metrics: {e}")
|
||||
return []
|
||||
|
||||
def get_platform_metrics(
|
||||
self,
|
||||
db: Session,
|
||||
platform_id: int,
|
||||
context: MetricsContext | None = None,
|
||||
) -> list[MetricValue]:
|
||||
"""
|
||||
Get order metrics aggregated for a platform.
|
||||
|
||||
Aggregates order data across all vendors.
|
||||
"""
|
||||
from app.modules.orders.models import Order
|
||||
from app.modules.tenancy.models import VendorPlatform
|
||||
|
||||
try:
|
||||
# Get all vendor IDs for this platform using VendorPlatform junction table
|
||||
vendor_ids = (
|
||||
db.query(VendorPlatform.vendor_id)
|
||||
.filter(
|
||||
VendorPlatform.platform_id == platform_id,
|
||||
VendorPlatform.is_active == True,
|
||||
)
|
||||
.subquery()
|
||||
)
|
||||
|
||||
# Total orders
|
||||
total_orders = (
|
||||
db.query(Order).filter(Order.vendor_id.in_(vendor_ids)).count()
|
||||
)
|
||||
|
||||
# Orders in period (default to last 30 days)
|
||||
date_from = context.date_from if context else None
|
||||
if date_from is None:
|
||||
date_from = datetime.utcnow() - timedelta(days=30)
|
||||
|
||||
orders_in_period_query = db.query(Order).filter(
|
||||
Order.vendor_id.in_(vendor_ids),
|
||||
Order.created_at >= date_from,
|
||||
)
|
||||
if context and context.date_to:
|
||||
orders_in_period_query = orders_in_period_query.filter(
|
||||
Order.created_at <= context.date_to
|
||||
)
|
||||
orders_in_period = orders_in_period_query.count()
|
||||
|
||||
# Vendors with orders
|
||||
vendors_with_orders = (
|
||||
db.query(func.count(func.distinct(Order.vendor_id)))
|
||||
.filter(Order.vendor_id.in_(vendor_ids))
|
||||
.scalar()
|
||||
or 0
|
||||
)
|
||||
|
||||
# Revenue metrics
|
||||
try:
|
||||
total_revenue = (
|
||||
db.query(func.sum(Order.total_amount))
|
||||
.filter(Order.vendor_id.in_(vendor_ids))
|
||||
.scalar()
|
||||
or 0
|
||||
)
|
||||
|
||||
revenue_in_period = (
|
||||
db.query(func.sum(Order.total_amount))
|
||||
.filter(
|
||||
Order.vendor_id.in_(vendor_ids),
|
||||
Order.created_at >= date_from,
|
||||
)
|
||||
.scalar()
|
||||
or 0
|
||||
)
|
||||
except Exception:
|
||||
total_revenue = 0
|
||||
revenue_in_period = 0
|
||||
|
||||
# Average order value
|
||||
avg_order_value = round(total_revenue / total_orders, 2) if total_orders > 0 else 0
|
||||
|
||||
return [
|
||||
MetricValue(
|
||||
key="orders.total",
|
||||
value=total_orders,
|
||||
label="Total Orders",
|
||||
category="orders",
|
||||
icon="shopping-cart",
|
||||
description="Total orders across all vendors",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.in_period",
|
||||
value=orders_in_period,
|
||||
label="Recent Orders",
|
||||
category="orders",
|
||||
icon="clock",
|
||||
description="Orders in the selected period",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.vendors_with_orders",
|
||||
value=vendors_with_orders,
|
||||
label="Vendors with Orders",
|
||||
category="orders",
|
||||
icon="store",
|
||||
description="Vendors that have received orders",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.total_revenue",
|
||||
value=float(total_revenue),
|
||||
label="Total Revenue",
|
||||
category="orders",
|
||||
icon="currency-euro",
|
||||
unit="EUR",
|
||||
description="Total revenue across platform",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.revenue_period",
|
||||
value=float(revenue_in_period),
|
||||
label="Period Revenue",
|
||||
category="orders",
|
||||
icon="trending-up",
|
||||
unit="EUR",
|
||||
description="Revenue in the selected period",
|
||||
),
|
||||
MetricValue(
|
||||
key="orders.avg_value",
|
||||
value=avg_order_value,
|
||||
label="Avg Order Value",
|
||||
category="orders",
|
||||
icon="calculator",
|
||||
unit="EUR",
|
||||
description="Average order value",
|
||||
),
|
||||
]
|
||||
except Exception as e:
|
||||
logger.warning(f"Failed to get order platform metrics: {e}")
|
||||
return []
|
||||
|
||||
|
||||
# Singleton instance
|
||||
order_metrics_provider = OrderMetricsProvider()
|
||||
|
||||
__all__ = ["OrderMetricsProvider", "order_metrics_provider"]
|
||||
Reference in New Issue
Block a user