New enterprise feature

services/forecasting/README.md

@@ -37,6 +37,15 @@ The **Forecasting Service** is the AI brain of the Bakery-IA platform, providing
 - **Comprehensive Metrics** - MAE, MAPE, RMSE, R², accuracy percentage by product/location
 - **Audit Trail** - Complete history of all validations and model improvements
 
+### 🆕 Enterprise Tier: Network Demand Aggregation (NEW)
+- **Parent-Level Aggregation** - Consolidated demand forecasts across all child outlets for centralized production planning
+- **Child Contribution Tracking** - Track each outlet's contribution to total network demand
+- **Redis Caching Strategy** - 1-hour TTL for enterprise forecasts to balance freshness vs performance
+- **Intelligent Rollup** - Aggregate child forecasts with parent-specific demand for complete visibility
+- **Network-Wide Insights** - Total production needs, capacity requirements, distribution planning support
+- **Hierarchical Forecasting** - Generate forecasts at both individual outlet and network levels
+- **Subscription Gating** - Enterprise aggregation requires Enterprise tier validation
+
 ### Intelligent Alerting
 - **Low Demand Alerts** - Automatic notifications for unusually low predicted demand
 - **High Demand Alerts** - Warnings for demand spikes requiring extra production
@@ -257,6 +266,11 @@ Event-Driven Validation
 - `POST /webhooks/pos-sync-completed` - Receive POS sync completion events
 - `GET /webhooks/health` - Webhook health check
 
+### 🆕 Enterprise Aggregation (NEW)
+- `GET /api/v1/{parent_tenant}/forecasting/enterprise/network-forecast` - Get aggregated network forecast (parent + all children)
+- `GET /api/v1/{parent_tenant}/forecasting/enterprise/child-contributions` - Get each child's contribution to total demand
+- `GET /api/v1/{parent_tenant}/forecasting/enterprise/production-requirements` - Calculate total production needs for network
+
 ### Predictions
 - `GET /api/v1/forecasting/predictions/daily` - Get today's predictions
 - `GET /api/v1/forecasting/predictions/daily/{date}` - Get predictions for specific date
@@ -391,6 +405,53 @@ TTL: 86400  # 24 hours
 }
 ```
 
+### 🆕 Enterprise Network Events (NEW)
+
+**Exchange**: `forecasting.enterprise`
+**Routing Key**: `forecasting.enterprise.network_forecast_generated`
+
+**Network Forecast Generated Event** - Published when aggregated network forecast is calculated
+```json
+{
+    "event_id": "uuid",
+    "event_type": "network_forecast_generated",
+    "service_name": "forecasting",
+    "timestamp": "2025-11-12T10:30:00Z",
+    "data": {
+        "parent_tenant_id": "uuid",
+        "forecast_date": "2025-11-14",
+        "total_network_demand": {
+            "product_id": "uuid",
+            "product_name": "Pan de Molde",
+            "total_quantity": 250.0,
+            "unit": "kg"
+        },
+        "child_contributions": [
+            {
+                "child_tenant_id": "uuid",
+                "child_name": "Outlet Centro",
+                "quantity": 80.0,
+                "percentage": 32.0
+            },
+            {
+                "child_tenant_id": "uuid",
+                "child_name": "Outlet Norte",
+                "quantity": 90.0,
+                "percentage": 36.0
+            },
+            {
+                "child_tenant_id": "uuid",
+                "child_name": "Outlet Sur",
+                "quantity": 80.0,
+                "percentage": 32.0
+            }
+        ],
+        "parent_demand": 50.0,
+        "cache_ttl_seconds": 3600
+    }
+}
+```
+
 ## Custom Metrics (Prometheus)
 
 ```python
@@ -567,6 +628,7 @@ poi_features = await poi_service.fetch_poi_features(tenant_id)
 - **Sales Service** - Fetch historical sales data for training
 - **External Service** - Fetch weather, traffic, holiday, and POI feature data
 - **Training Service** - Load trained Prophet models
+- **🆕 Tenant Service** (NEW) - Fetch tenant hierarchy for enterprise aggregation (parent/child relationships)
 - **Redis** - Cache predictions and session data
 - **PostgreSQL** - Store forecasts and performance metrics
 - **RabbitMQ** - Publish alert events
@@ -577,6 +639,8 @@ poi_features = await poi_service.fetch_poi_features(tenant_id)
 - **Orchestrator Service** - Trigger daily forecast generation
 - **Frontend Dashboard** - Display forecasts and charts
 - **AI Insights Service** - Analyze forecast patterns
+- **🆕 Distribution Service** (NEW) - Network forecasts inform delivery route capacity planning
+- **🆕 Orchestrator Enterprise Dashboard** (NEW) - Displays aggregated network demand for parent tenants
 
 ## ML Model Performance