docs: Add comprehensive alert system architecture and panel de control documentation

frontend/README.md

@@ -18,10 +18,142 @@ The **Bakery-IA Frontend Dashboard** is a modern, responsive React-based web app
 ### Real-Time Operational Dashboard
 - **Live KPI Cards** - Real-time metrics for sales, inventory, production
 - **Alert Stream (SSE)** - Instant notifications for critical events
+- **AI Impact Showcase** - Celebrate AI wins with handling rate and savings metrics
+- **Prevented Issues Card** - Highlights problems AI automatically resolved
 - **Production Status** - Live view of current production batches
 - **Inventory Levels** - Color-coded stock levels with expiry warnings
 - **Order Pipeline** - Track customer orders from placement to fulfillment
 
+### Enriched Alert System (NEW)
+- **Multi-Dimensional Priority Scoring** - Intelligent 0-100 priority scores with 4 weighted factors
+  - Business Impact (40%): Financial consequences, affected orders
+  - Urgency (30%): Time sensitivity, deadlines
+  - User Agency (20%): Can you take action?
+  - AI Confidence (10%): Prediction certainty
+- **Smart Alert Classification** - 5 alert types for clear user intent
+  - 🔴 ACTION_NEEDED: Requires your decision or action
+  - 🎉 PREVENTED_ISSUE: AI already handled (celebration!)
+  - 📊 TREND_WARNING: Pattern detected, early warning
+  - ⏱️ ESCALATION: Auto-action pending, can cancel
+  - ℹ️ INFORMATION: FYI only, no action needed
+- **3-Tab Alert Hub** - Organized navigation (All Alerts / For Me / Archived)
+- **Auto-Action Countdown** - Real-time timer for escalation alerts with one-click cancel
+- **Priority Score Explainer** - Educational modal showing exact scoring formula
+- **Trend Visualizations** - Inline sparklines and directional indicators for trend warnings
+- **Action Consequence Previews** - See outcomes before taking action (financial impact, affected systems, reversibility)
+- **Response Time Gamification** - Track your alert response performance by priority level with benchmarks
+- **Email Digests** - Daily/weekly summaries with celebration-first messaging
+- **Full Internationalization** - Complete translations (English, Spanish, Basque)
+
+### Panel de Control (Dashboard Redesign - NEW)
+A comprehensive dashboard redesign focused on Jobs-To-Be-Done principles, progressive disclosure, and mobile-first UX.
+
+#### **New Dashboard Components**
+- **GlanceableHealthHero** - Traffic light status system (🟢🟡🔴)
+  - Understand bakery health in 3 seconds (5 AM test)
+  - Collapsible checklist with progressive disclosure
+  - Shows urgent action count prominently
+  - Real-time SSE integration for critical alerts
+  - Mobile-optimized with large touch targets (44x44px minimum)
+- **SetupWizardBlocker** - Full-page setup wizard
+  - Blocks dashboard access when <50% setup complete
+  - Step-by-step wizard interface with numbered steps
+  - Progress bar (0-100%) with completion indicators
+  - Clear CTAs for each configuration section
+  - Ensures critical data exists before AI can function
+- **CollapsibleSetupBanner** - Compact reminder banner
+  - Appears when 50-99% setup complete
+  - Collapsible (default: collapsed) to minimize distraction
+  - Dismissible for 7 days via localStorage
+  - Shows remaining sections with item counts
+  - Links directly to incomplete sections
+- **UnifiedActionQueueCard** - Consolidated action queue
+  - Time-based grouping (Urgent / Today / This Week)
+  - Smart actions with embedded delivery workflows
+  - Escalation badges show pending duration
+  - StockReceiptModal integration for delivery actions
+  - Real-time updates via SSE
+- **ExecutionProgressTracker** - Plan vs actual tracking
+  - Visual progress bars for production, deliveries, approvals
+  - Shows what's on track vs behind schedule
+  - Business impact highlights (orders at risk)
+- **IntelligentSystemSummaryCard** - AI insights dashboard
+  - Shows what AI has done and why
+  - Celebration-focused messaging for prevented issues
+  - Recommendations with confidence scores
+
+#### **Three-State Setup Flow Logic**
+```
+Progress < 50%  → SetupWizardBlocker (BLOCKS dashboard access)
+Progress 50-99% → CollapsibleSetupBanner (REMINDS but allows access)
+Progress 100%   → Hidden (COMPLETE, no reminder)
+```
+
+**Setup Progress Calculation**:
+- **Inventory**: Minimum 3 ingredients, recommended 10
+- **Suppliers**: Minimum 1 supplier, recommended 3
+- **Recipes**: Minimum 1 recipe, recommended 3
+- **Quality**: Optional, recommended 2 templates
+
+**Rationale**: Critical data (ingredients, suppliers, recipes) must exist for AI to function. Recommended data improves AI but isn't required. Progressive disclosure prevents overwhelming new users while reminding them of missing features.
+
+#### **Design Principles**
+- **Glanceable First (5-Second Test)** - User should understand status in 3 seconds at 5 AM on phone
+- **Mobile-First / One-Handed** - All critical actions in thumb zone, 44x44px min touch targets
+- **Progressive Disclosure** - Show 20% that matters 80% of the time, hide complexity until requested
+- **Outcome-Focused** - Show business impact ($€, time saved) not just features
+- **Trust-Building** - Always show AI reasoning, escalation tracking, financial impact transparency
+
+#### **StockReceiptModal Integration Pattern**
+Cross-component communication using CustomEvents for opening stock receipt modal from dashboard alerts:
+
+```typescript
+// Emit from smartActionHandlers.ts
+window.dispatchEvent(new CustomEvent('stock-receipt:open', {
+  detail: {
+    receipt_id?: string,
+    po_id: string,
+    tenant_id: string,
+    mode: 'create' | 'edit'
+  }
+}));
+
+// Listen in UnifiedActionQueueCard.tsx
+useEffect(() => {
+  const handler = (e: CustomEvent) => {
+    setStockReceiptData({
+      isOpen: true,
+      receipt: e.detail
+    });
+  };
+  window.addEventListener('stock-receipt:open', handler);
+  return () => window.removeEventListener('stock-receipt:open', handler);
+}, []);
+```
+
+**Workflow**: Delivery alerts (`DELIVERY_ARRIVING_SOON`, `STOCK_RECEIPT_INCOMPLETE`) trigger modal opening with PO context. User completes stock receipt with lot-level tracking and expiration dates. Confirmation triggers `delivery.received` event, auto-resolving related alerts.
+
+#### **Deleted Components (Cleanup Rationale)**
+The dashboard redesign replaced or merged 7 legacy components:
+- `HealthStatusCard.tsx` → Replaced by **GlanceableHealthHero** (traffic light system)
+- `InsightsGrid.tsx` → Merged into **IntelligentSystemSummaryCard**
+- `ProductionTimelineCard.tsx` → Replaced by **ExecutionProgressTracker**
+- `ActionQueueCard.tsx` → Replaced by **UnifiedActionQueueCard** (time-based grouping)
+- `ConfigurationProgressWidget.tsx` → Replaced by **SetupWizardBlocker** + **CollapsibleSetupBanner**
+- `AlertContextActions.tsx` → Merged into Alert Hub
+- `OrchestrationSummaryCard.tsx` → Merged into system summary
+
+**Net Impact**: Deleted ~1,200 lines of old code, added ~811 lines of new focused components, saved ~390 lines overall while improving UX.
+
+#### **Dashboard Layout Order**
+1. **Setup Flow** - Blocker or banner (contextual)
+2. **GlanceableHealthHero** - Traffic light status
+3. **UnifiedActionQueueCard** - What needs attention
+4. **ExecutionProgressTracker** - Plan vs actual
+5. **AI Impact Showcase** - Celebration cards for prevented issues
+6. **IntelligentSystemSummaryCard** - What AI did and why
+7. **Quick Action Links** - Navigation shortcuts
+
 ### Inventory Management
 - **Stock Overview** - All ingredients with current levels and locations
 - **Low Stock Alerts** - Automatic warnings when stock falls below thresholds