docs: Add comprehensive alert system architecture and panel de control documentation
This commit is contained in:
Urtzi Alfaro
2119
docs/ALERT-SYSTEM-ARCHITECTURE.md
Normal file
2119
docs/ALERT-SYSTEM-ARCHITECTURE.md
Normal file
File diff suppressed because it is too large
Load Diff
@@ -18,10 +18,142 @@ The **Bakery-IA Frontend Dashboard** is a modern, responsive React-based web app
|
|||||||
### Real-Time Operational Dashboard
|
### Real-Time Operational Dashboard
|
||||||
- **Live KPI Cards** - Real-time metrics for sales, inventory, production
|
- **Live KPI Cards** - Real-time metrics for sales, inventory, production
|
||||||
- **Alert Stream (SSE)** - Instant notifications for critical events
|
- **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
|
- **Production Status** - Live view of current production batches
|
||||||
- **Inventory Levels** - Color-coded stock levels with expiry warnings
|
- **Inventory Levels** - Color-coded stock levels with expiry warnings
|
||||||
- **Order Pipeline** - Track customer orders from placement to fulfillment
|
- **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
|
### Inventory Management
|
||||||
- **Stock Overview** - All ingredients with current levels and locations
|
- **Stock Overview** - All ingredients with current levels and locations
|
||||||
- **Low Stock Alerts** - Automatic warnings when stock falls below thresholds
|
- **Low Stock Alerts** - Automatic warnings when stock falls below thresholds
|
||||||
|
|||||||
Reference in New Issue
Block a user