Update readmes and imporve UI

2025-12-19 09:28:36 +01:00
parent a6ae730ef0
commit 71ee2976a2
10 changed files with 1035 additions and 155 deletions
--- a/services/alert_processor/README.md
+++ b/services/alert_processor/README.md
@@ -29,14 +29,17 @@ Services → RabbitMQ → [Alert Processor] → PostgreSQL

 ### Enrichment Pipeline

-1. **Message Generator**: Creates i18n keys and parameters from metadata
-2. **Orchestrator Client**: Queries AI orchestrator for context
-3. **Business Impact Analyzer**: Calculates financial and operational impact
-4. **Urgency Analyzer**: Assesses time sensitivity and deadlines
-5. **User Agency Analyzer**: Determines user's ability to act
-6. **Priority Scorer**: Calculates weighted priority score (0-100)
-7. **Smart Action Generator**: Creates contextual action buttons
-8. **Entity Link Extractor**: Maps metadata to entity references
+1. **Duplicate Detection**: Checks for duplicate alerts within 24-hour window
+2. **Message Generator**: Creates i18n keys and parameters from metadata
+3. **Orchestrator Client**: Queries AI orchestrator for context
+4. **AI Reasoning Extractor**: Extracts AI reasoning details and confidence scores
+5. **Business Impact Analyzer**: Calculates financial and operational impact
+6. **Urgency Analyzer**: Assesses time sensitivity and deadlines
+7. **User Agency Analyzer**: Determines user's ability to act
+8. **Priority Scorer**: Calculates weighted priority score (0-100)
+9. **Type Classifier**: Determines if action needed or issue prevented
+10. **Smart Action Generator**: Creates contextual action buttons
+11. **Entity Link Extractor**: Maps metadata to entity references

 ## Service Structure

@@ -177,12 +180,15 @@ await publisher.publish_alert(

 ### 2. Alert Processor Enriches

+- **Checks for duplicates**: Searches 24-hour window for similar alerts
 - Generates i18n: `alerts.critical_stock_shortage.title` with params
 - Queries orchestrator for AI context
+- Extracts AI reasoning and confidence scores (if available)
 - Analyzes business impact: €197.50 financial impact
 - Assesses urgency: 12 hours until consequence
 - Determines user agency: Can create PO, requires supplier
 - Calculates priority: Score 78 → "important"
+- Classifies type: `action_needed` or `prevented_issue`
 - Generates smart actions: [Create PO, Call Supplier, Dismiss]
 - Extracts entity links: `{ingredient: "..."}`

@@ -192,8 +198,12 @@ await publisher.publish_alert(
 {
  "id": "...",
  "event_type": "critical_stock_shortage",
+  "event_domain": "inventory",
+  "severity": "urgent",
+  "type_class": "action_needed",
  "priority_score": 78,
  "priority_level": "important",
+  "confidence_score": 95,
  "i18n": {
    "title_key": "alerts.critical_stock_shortage.title",
    "title_params": {"ingredient_name": "Flour"},
@@ -206,7 +216,10 @@ await publisher.publish_alert(
  "business_impact": {...},
  "urgency": {...},
  "user_agency": {...},
-  "smart_actions": [...]
+  "ai_reasoning_details": {...},
+  "orchestrator_context": {...},
+  "smart_actions": [...],
+  "entity_links": {"ingredient": "..."}
 }
 ```

@@ -249,30 +262,83 @@ Publishes to Redis channel `alerts:{tenant_id}` for real-time frontend updates.

 See [app/utils/message_templates.py](app/utils/message_templates.py) for complete list.

-Key alert types:
- `critical_stock_shortage`
- `low_stock_warning`
- `production_delay`
- `equipment_failure`
- `po_approval_needed`
- `temperature_breach`
- `delivery_overdue`
- `expired_products`
+### Standard Alerts
+- `critical_stock_shortage` - Urgent stock shortages
+- `low_stock_warning` - Stock running low
+- `production_delay` - Production behind schedule
+- `equipment_failure` - Equipment issues
+- `po_approval_needed` - Purchase order approval required
+- `temperature_breach` - Temperature control violations
+- `delivery_overdue` - Late deliveries
+- `expired_products` - Product expiration warnings
+
+### AI Recommendations
+- `ai_yield_prediction` - AI-predicted production yields
+- `ai_safety_stock_optimization` - AI stock level recommendations
+- `ai_supplier_recommendation` - AI supplier suggestions
+- `ai_price_forecast` - AI price predictions
+- `ai_demand_forecast` - AI demand forecasts
+- `ai_business_rule` - AI-suggested business rules

 ## Database Schema

 **events table** with JSONB enrichment:
- Core: `id`, `tenant_id`, `created_at`, `event_type`
+- Core: `id`, `tenant_id`, `created_at`, `event_type`, `event_domain`, `severity`
 - i18n: `i18n_title_key`, `i18n_title_params`, `i18n_message_key`, `i18n_message_params`
 - Priority: `priority_score` (0-100), `priority_level` (critical/important/standard/info)
 - Enrichment: `orchestrator_context`, `business_impact`, `urgency`, `user_agency` (JSONB)
+- AI Fields: `ai_reasoning_details`, `confidence_score`, `ai_reasoning_summary_key`, `ai_reasoning_summary_params`
+- Classification: `type_class` (action_needed/prevented_issue)
 - Actions: `smart_actions` (JSONB array)
+- Entities: `entity_links` (JSONB)
 - Status: `status` (active/acknowledged/resolved/dismissed)
+- Metadata: `raw_metadata` (JSONB)
+
+## Key Features
+
+### Duplicate Alert Detection
+
+The service automatically detects and prevents duplicate alerts:
+- **24-hour window**: Checks for similar alerts in the past 24 hours
+- **Smart matching**: Compares `tenant_id`, `event_type`, and key metadata fields
+- **Update strategy**: Updates existing alert instead of creating duplicates
+- **Metadata preservation**: Keeps enriched data while preventing alert fatigue
+
+### Type Classification
+
+Events are classified into two types:
+- **action_needed**: User action required (default for alerts)
+- **prevented_issue**: AI already handled the situation (for AI recommendations)
+
+This helps the frontend display appropriate UI and messaging.
+
+### AI Reasoning Integration
+
+When AI orchestrator has acted on an event:
+- Extracts complete reasoning data structure
+- Stores confidence scores (0-100)
+- Generates i18n-friendly reasoning summaries
+- Links to orchestrator context for full details
+
+### Notification Service Integration
+
+Enriched events are automatically sent to the notification service for delivery via:
+- WhatsApp
+- Email
+- Push notifications
+- SMS
+
+Priority mapping:
+- `critical` → urgent priority
+- `important` → high priority
+- `standard` → medium priority
+- `info` → low priority

 ## Monitoring

 Structured JSON logs with:
 - `enrichment_started` - Event received
+- `duplicate_detected` - Duplicate alert found and updated
 - `enrichment_completed` - Enrichment pipeline finished
 - `event_stored` - Saved to database
 - `notification_sent` - Notification queued
--- a/services/demo_session/README.md
+++ b/services/demo_session/README.md
@@ -172,30 +172,98 @@ graph TD
 - **Use Case**: Central obrador + 3 retail outlets
 - **Features**: VRP-optimized routes, multi-location inventory

+## 🎯 API Endpoints
+
+### Atomic Operations
+- `GET /api/v1/demo/accounts` - List available demo account types
+- `POST /api/v1/demo/sessions` - Create new demo session
+- `GET /api/v1/demo/sessions/{session_id}` - Get session details
+- `GET /api/v1/demo/sessions/{session_id}/status` - Poll cloning status
+- `GET /api/v1/demo/sessions/{session_id}/errors` - Get detailed errors
+- `DELETE /api/v1/demo/sessions/{session_id}` - Destroy session
+
+### Business Operations
+- `POST /api/v1/demo/sessions/{session_id}/extend` - Extend session TTL
+- `POST /api/v1/demo/sessions/{session_id}/retry` - Retry failed cloning
+- `GET /api/v1/demo/stats` - Session statistics
+- `POST /api/v1/demo/operations/cleanup` - Cleanup expired sessions
+- `POST /api/v1/demo/sessions/{session_id}/seed-alerts` - Seed demo alerts
+
+### Session Lifecycle
+
+**Statuses:**
+- `PENDING` - Data cloning in progress
+- `READY` - All data loaded, ready to use
+- `PARTIAL` - Some services failed, others succeeded
+- `FAILED` - One or more services failed completely
+- `EXPIRED` - Session TTL exceeded
+- `DESTROYED` - Session terminated
+
+**Session Duration:**
+- Default: 2 hours
+- Extendable via `/extend` endpoint
+- Extension limit: Configurable per environment
+
+**Estimated Load Times:**
+- Professional: ~40 seconds
+- Enterprise: ~75 seconds (includes child tenants)
+
 ## 🔧 Usage

 ### Create Demo Session via API

 ```bash
 # Professional demo
-curl -X POST http://localhost:8000/api/v1/demo-sessions \
+curl -X POST http://localhost:8000/api/v1/demo/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "demo_account_type": "professional",
-    "email": "test@example.com",
-    "subscription_tier": "professional"
+    "email": "test@example.com"
  }'

-# Enterprise demo  
-curl -X POST http://localhost:8000/api/v1/demo-sessions \
+# Enterprise demo
+curl -X POST http://localhost:8000/api/v1/demo/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "demo_account_type": "enterprise",
-    "email": "test@example.com",
-    "subscription_tier": "enterprise"
+    "email": "test@example.com"
  }'
 ```

+### Poll Session Status
+
+```bash
+# Check if session is ready
+curl http://localhost:8000/api/v1/demo/sessions/{session_id}/status
+
+# Response includes per-service progress
+{
+  "session_id": "demo_xxx",
+  "status": "ready|pending|failed|partial",
+  "progress": {
+    "orders": {"status": "completed", "records": 42},
+    "production": {"status": "in_progress", "records": 15}
+  },
+  "estimated_remaining_seconds": 30
+}
+```
+
+### Session Management
+
+```bash
+# Extend session (add more time)
+curl -X POST http://localhost:8000/api/v1/demo/sessions/{session_id}/extend
+
+# Retry failed services
+curl -X POST http://localhost:8000/api/v1/demo/sessions/{session_id}/retry
+
+# Get session details
+curl http://localhost:8000/api/v1/demo/sessions/{session_id}
+
+# Destroy session (cleanup)
+curl -X DELETE http://localhost:8000/api/v1/demo/sessions/{session_id}
+```
+
 ### Implementation Example

 Here's how the Orders service implements direct loading:
@@ -392,11 +460,12 @@ def adjust_date_for_demo(original_date: datetime, session_time: datetime) -> dat

 ### Step-by-Step Demo Session Creation

-1. **User Request**: Frontend calls `/api/v1/demo-sessions` with demo type
+1. **User Request**: Frontend calls `/api/v1/demo/sessions` with demo type
 2. **Session Setup**: Demo Session Service:
   - Generates virtual tenant UUID
-   - Records session metadata
-   - Calculates session creation timestamp
+   - Records session metadata (session_id, ip_address, user_agent)
+   - Calculates session creation timestamp and expiration
+   - For enterprise: Generates child tenant IDs
 3. **Parallel Service Calls**: Demo Session Service calls each service's `/internal/demo/clone` endpoint with:
   - `virtual_tenant_id` - Virtual tenant UUID
   - `demo_account_type` - Profile (professional/enterprise)
@@ -406,8 +475,10 @@ def adjust_date_for_demo(original_date: datetime, session_time: datetime) -> dat
   - Transforms all IDs using XOR with virtual tenant ID
   - Adjusts all dates relative to session creation time
   - Inserts data into its database within a transaction
-   - Returns success/failure status
-5. **Response**: Demo Session Service returns credentials and session info
+   - Returns success/failure status with record count
+5. **Status Tracking**: Per-service progress stored in JSONB field with timestamps and error details
+6. **Response**: Demo Session Service returns credentials and session info
+7. **Frontend Polling**: Frontend polls `/api/v1/demo/sessions/{session_id}/status` until status is READY or FAILED

 ### Example: Orders Service Clone Endpoint

--- a/services/orders/README.md
+++ b/services/orders/README.md
@@ -648,6 +648,133 @@ async def calculate_customer_rfm(customer_id: UUID) -> dict:
 }
 ```

+### Alert Events
+
+The Orders service also publishes procurement-related alerts through the alert processor.
+
+**Exchange**: `events.exchange`
+**Domain**: `procurement`
+
+#### 1. POs Pending Approval Alert
+**Event Type**: `procurement.pos_pending_approval`
+**Severity**: urgent (>€10,000), high (>€5,000 or critical POs), medium (otherwise)
+**Trigger**: New purchase orders created and awaiting approval
+
+```json
+{
+    "event_type": "procurement.pos_pending_approval",
+    "severity": "high",
+    "metadata": {
+        "tenant_id": "uuid",
+        "pos_count": 3,
+        "total_amount": 6500.00,
+        "critical_count": 1,
+        "pos": [
+            {
+                "po_id": "uuid",
+                "po_number": "PO-001",
+                "supplier_id": "uuid",
+                "total_amount": 3000.00,
+                "auto_approved": false
+            }
+        ],
+        "action_required": true,
+        "action_url": "/app/comprar"
+    }
+}
+```
+
+#### 2. Approval Reminder Alert
+**Event Type**: `procurement.approval_reminder`
+**Severity**: high (>36 hours pending), medium (otherwise)
+**Trigger**: PO not approved within threshold time
+
+```json
+{
+    "event_type": "procurement.approval_reminder",
+    "severity": "high",
+    "metadata": {
+        "tenant_id": "uuid",
+        "po_id": "uuid",
+        "po_number": "PO-001",
+        "supplier_name": "Supplier ABC",
+        "total_amount": 3000.00,
+        "hours_pending": 40,
+        "created_at": "2025-12-18T10:00:00Z",
+        "action_required": true,
+        "action_url": "/app/comprar?po=uuid"
+    }
+}
+```
+
+#### 3. Critical PO Escalation Alert
+**Event Type**: `procurement.critical_po_escalation`
+**Severity**: urgent
+**Trigger**: Critical/urgent PO not approved in time
+
+```json
+{
+    "event_type": "procurement.critical_po_escalation",
+    "severity": "urgent",
+    "metadata": {
+        "tenant_id": "uuid",
+        "po_id": "uuid",
+        "po_number": "PO-001",
+        "supplier_name": "Supplier ABC",
+        "total_amount": 5000.00,
+        "priority": "urgent",
+        "required_delivery_date": "2025-12-22",
+        "hours_pending": 48,
+        "escalated": true,
+        "action_required": true,
+        "action_url": "/app/comprar?po=uuid"
+    }
+}
+```
+
+#### 4. Auto-Approval Summary (Notification)
+**Event Type**: `procurement.auto_approval_summary`
+**Type**: Notification (not alert)
+**Trigger**: Daily summary of auto-approved POs
+
+```json
+{
+    "event_type": "procurement.auto_approval_summary",
+    "metadata": {
+        "tenant_id": "uuid",
+        "auto_approved_count": 5,
+        "total_auto_approved_amount": 8500.00,
+        "manual_approval_count": 2,
+        "summary_date": "2025-12-19",
+        "auto_approved_pos": [...],
+        "pending_approval_pos": [...],
+        "action_url": "/app/comprar"
+    }
+}
+```
+
+#### 5. PO Approved Confirmation (Notification)
+**Event Type**: `procurement.po_approved_confirmation`
+**Type**: Notification (not alert)
+**Trigger**: Purchase order approved
+
+```json
+{
+    "event_type": "procurement.po_approved_confirmation",
+    "metadata": {
+        "tenant_id": "uuid",
+        "po_id": "uuid",
+        "po_number": "PO-001",
+        "supplier_name": "Supplier ABC",
+        "total_amount": 3000.00,
+        "approved_by": "user@example.com",
+        "auto_approved": false,
+        "approved_at": "2025-12-19T14:30:00Z",
+        "action_url": "/app/comprar?po=uuid"
+    }
+}
+```
+
 ### Consumed Events
 - **From Production**: Batch completion updates order fulfillment status
 - **From Inventory**: Stock availability affects order confirmation
--- a/services/production/README.md
+++ b/services/production/README.md
@@ -224,8 +224,10 @@ CREATE TABLE production_capacity (

 ### Published Events (RabbitMQ)

-**Exchange**: `production`
-**Routing Keys**: `production.batch.completed`, `production.quality.issue`, `production.equipment.maintenance`
+**Exchange**: `events.exchange`
+**Domain**: `production`
+
+### Business Events

 **Batch Completed Event**
 ```json
@@ -247,22 +249,177 @@ CREATE TABLE production_capacity (
 }
 ```

-**Quality Issue Alert**
+### Alert Events
+
+All alerts are published to the alert processor for enrichment and notification.
+
+#### 1. Production Delay Alert
+**Event Type**: `production.production_delay`
+**Severity**: urgent (>120 min), high (>60 min), medium (otherwise)
+**Trigger**: Batch delayed past scheduled start time
+
 ```json
 {
-    "event_type": "quality_issue",
-    "tenant_id": "uuid",
-    "batch_id": "uuid",
-    "product_name": "Croissant",
-    "quality_score": 65,
-    "passing_score": 80,
-    "issues_found": "Color too dark, texture inconsistent",
-    "severity": "high",
-    "corrective_actions": "Adjust oven temperature, check proofing time",
-    "timestamp": "2025-11-06T10:30:00Z"
+    "event_type": "production.production_delay",
+    "severity": "urgent",
+    "metadata": {
+        "batch_id": "uuid",
+        "product_name": "Baguette",
+        "batch_number": "BATCH-001",
+        "delay_minutes": 135,
+        "affected_orders": 5,
+        "customer_names": ["Café A", "Café B"]
+    }
 }
 ```

+#### 2. Equipment Failure Alert
+**Event Type**: `production.equipment_failure`
+**Severity**: urgent
+**Trigger**: Equipment malfunction detected
+
+```json
+{
+    "event_type": "production.equipment_failure",
+    "severity": "urgent",
+    "metadata": {
+        "equipment_id": "uuid",
+        "equipment_name": "Oven #1",
+        "equipment_type": "oven",
+        "affected_batches": 3
+    }
+}
+```
+
+#### 3. Capacity Overload Alert
+**Event Type**: `production.capacity_overload`
+**Severity**: urgent (>120%), high (>100%), medium (otherwise)
+**Trigger**: Production capacity exceeded
+
+```json
+{
+    "event_type": "production.capacity_overload",
+    "severity": "urgent",
+    "metadata": {
+        "current_load_percent": 125,
+        "planned_batches": 15,
+        "available_capacity": 12,
+        "affected_date": "2025-12-20"
+    }
+}
+```
+
+#### 4. Quality Issue Alert
+**Event Type**: `production.quality_issue`
+**Severity**: high
+**Trigger**: Batch quality below threshold
+
+```json
+{
+    "event_type": "production.quality_issue",
+    "severity": "high",
+    "metadata": {
+        "batch_id": "uuid",
+        "product_name": "Croissant",
+        "issue_type": "quality_below_threshold",
+        "issue_description": "Color too dark, texture inconsistent",
+        "affected_quantity": 50
+    }
+}
+```
+
+#### 5. Production Start Alert
+**Event Type**: `production.start_production`
+**Severity**: medium
+**Trigger**: Production batch created
+
+```json
+{
+    "event_type": "production.start_production",
+    "severity": "medium",
+    "metadata": {
+        "batch_id": "uuid",
+        "product_name": "Baguette",
+        "batch_number": "BATCH-001",
+        "planned_start_time": "2025-12-20T06:00:00Z",
+        "reasoning_data": {...}
+    }
+}
+```
+
+#### 6. Batch Start Delayed Alert
+**Event Type**: `production.batch_start_delayed`
+**Severity**: high
+**Trigger**: Batch start delayed for specific reason
+
+```json
+{
+    "event_type": "production.batch_start_delayed",
+    "severity": "high",
+    "metadata": {
+        "batch_id": "uuid",
+        "product_name": "Pain au Chocolat",
+        "batch_number": "BATCH-002",
+        "scheduled_start": "2025-12-20T07:00:00Z",
+        "delay_reason": "Missing ingredients"
+    }
+}
+```
+
+#### 7. Missing Ingredients Alert
+**Event Type**: `production.missing_ingredients`
+**Severity**: urgent
+**Trigger**: Required ingredients unavailable
+
+```json
+{
+    "event_type": "production.missing_ingredients",
+    "severity": "urgent",
+    "metadata": {
+        "batch_id": "uuid",
+        "product_name": "Baguette",
+        "batch_number": "BATCH-001",
+        "missing_ingredients": [
+            {"name": "Flour", "required": 50, "available": 10},
+            {"name": "Yeast", "required": 2, "available": 0}
+        ],
+        "missing_count": 2
+    }
+}
+```
+
+#### 8. Equipment Maintenance Due Alert
+**Event Type**: `production.equipment_maintenance_due`
+**Severity**: high (>30 days overdue), medium (otherwise)
+**Trigger**: Equipment maintenance overdue
+
+```json
+{
+    "event_type": "production.equipment_maintenance_due",
+    "severity": "high",
+    "metadata": {
+        "equipment_id": "uuid",
+        "equipment_name": "Mixer #2",
+        "last_maintenance_date": "2024-10-15",
+        "days_overdue": 45
+    }
+}
+```
+
+### AI Recommendations
+
+#### Efficiency Recommendation
+**Event Type**: `production.efficiency_recommendation`
+**Severity**: medium
+
+#### Energy Optimization
+**Event Type**: `production.energy_optimization`
+**Severity**: medium
+
+#### Batch Sequence Optimization
+**Event Type**: `production.batch_sequence_optimization`
+**Severity**: medium
+
 ### Consumed Events
 - **From Forecasting**: Daily forecasts for production planning
 - **From Orchestrator**: Scheduled production triggers