Add new alert architecture

2025-08-23 10:19:58 +02:00
parent 1a9839240e
commit 4b4268d640
45 changed files with 6518 additions and 1590 deletions
--- a/services/notification/README.md
+++ b/services/notification/README.md
@@ -1,321 +0,0 @@
-## 🎯 **Complete Notification Service Implementation**
-
-### **📁 File Structure Created**
-
-```
-services/notification/
-├── app/
-│   ├── main.py                     ✅ Complete FastAPI application
-│   ├── core/
-│   │   ├── config.py              ✅ Configuration settings
-│   │   └── database.py            ✅ Database initialization
-│   ├── models/
-│   │   ├── notifications.py       ✅ Core notification models
-│   │   └── templates.py           ✅ Template-specific models
-│   ├── schemas/
-│   │   └── notifications.py       ✅ Pydantic schemas
-│   ├── services/
-│   │   ├── notification_service.py ✅ Main business logic
-│   │   ├── email_service.py        ✅ Email delivery
-│   │   ├── whatsapp_service.py     ✅ WhatsApp delivery
-│   │   └── messaging.py           ✅ RabbitMQ integration
-│   └── api/
-│       └── notifications.py       ✅ Complete API routes
-├── requirements.txt               ✅ Python dependencies
-├── Dockerfile                     ✅ Container configuration
-└── .env.example                   ✅ Environment variables
-```
-
-### **🔧 Key Features Implemented**
-
-#### **1. Complete Business Logic**
-
- ✅ **NotificationService**: Core orchestration of all notification operations
- ✅ **Multi-channel support**: Email, WhatsApp, Push (extensible)
- ✅ **Template processing**: Jinja2-based template rendering
- ✅ **Bulk notifications**: Batch processing with rate limiting
- ✅ **User preferences**: Granular notification controls
- ✅ **Scheduling**: Delayed notification delivery
-
-#### **2. Email Service Integration**
-
- ✅ **SMTP support**: Configurable email providers (Gmail, SendGrid, etc
- ✅ **HTML + Text emails**: Rich email templates with fallbacks
- ✅ **Bulk email processing**: Rate-limited batch sending
- ✅ **Template system**: Pre-built Spanish templates for bakeries
- ✅ **Health checks**: SMTP connection monitoring
- ✅ **Attachment support**: File attachment capabilities
-
-#### **3. WhatsApp Service Integration**
-
- ✅ **Twilio integration**: WhatsApp Business API support
- ✅ **Spanish phone formatting**: Automatic +34 country code handling
- ✅ **Template messages**: WhatsApp Business template support
- ✅ **Bulk WhatsApp**: Rate-limited batch messaging
- ✅ **Delivery status**: Webhook handling for delivery confirmations
-
-#### **4. Database Models & Schemas**
-
- ✅ **Complete data model**: Notifications, templates, preferences, logs
- ✅ **Multi-tenant support**: Tenant-scoped notifications
- ✅ **Audit trail**: Detailed delivery attempt logging
- ✅ **Template management**: System and custom templates
- ✅ **User preferences**: Granular notification controls
-
-#### **5. API Integration with Gateway**
-
- ✅ **Gateway authentication**: Uses shared auth decorators
- ✅ **Tenant isolation**: Automatic tenant scoping
- ✅ **Role-based access**: Admin/manager/user permissions
- ✅ **Complete CRUD**: Full notification management API
- ✅ **Webhook endpoints**: External delivery status handling
-
-#### **6. RabbitMQ Event Integration**
-
- ✅ **Event consumers**: Listens for user registration, forecasts, training
- ✅ **Event publishers**: Publishes notification status events
- ✅ **Auto-notifications**: Triggers welcome emails, alerts, reports
- ✅ **Error handling**: Robust message processing with retry logic
-
-#### **7. Spanish Bakery Templates**
-
- ✅ **Welcome email**: Professional onboarding email
- ✅ **Forecast alerts**: Demand variation notifications
- ✅ **Weekly reports**: Performance summary emails
- ✅ **Responsive HTML**: Mobile-optimized email designs
- ✅ **Spanish localization**: All content in Spanish
-
-### **🚀 Integration with Your Architecture**
-
-#### **Seamless Gateway Integration**
-
-```python
-# Gateway already routes to notification service
-app.include_router(notification.router, prefix="/api/v1/notifications", tags=["notifications"])
-
-# Authentication handled by gateway middleware
-# Tenant isolation automatic
-# User context passed via headers
-```
-
-#### **Shared Library Usage**
-
-```python
-# Uses your existing shared components
-from shared.auth.decorators import get_current_user_dep, get_current_tenant_id_dep
-from shared.messaging.rabbitmq import RabbitMQClient
-from shared.monitoring.metrics import MetricsCollector
-from shared.database.base import DatabaseManager
-```
-
-#### **Event-Driven Architecture**
-
-```python
-# Automatic notifications triggered by:
-# - User registration → Welcome email
-# - Forecast alerts → Alert emails + WhatsApp
-# - Training completion → Status notifications
-# - Data imports → Import confirmations
-```
-
-### **📊 Production Features**
-
-#### **Health Monitoring**
-
- ✅ **Database health checks**: Connection monitoring
- ✅ **SMTP health checks**: Email service validation
- ✅ **WhatsApp health checks**: API connectivity tests
- ✅ **Prometheus metrics**: Delivery rates, response times
- ✅ **Structured logging**: Comprehensive error tracking
-
-#### **Rate Limiting & Scaling**
-
- ✅ **Email rate limits**: 1000/hour configurable
- ✅ **WhatsApp rate limits**: 100/hour (Twilio limits)
- ✅ **Batch processing**: Configurable batch sizes
- ✅ **Retry logic**: Automatic retry with exponential backoff
- ✅ **Queue management**: Background task processing
-
-#### **Security & Compliance**
-
- ✅ **User consent**: Preference-based opt-in/out
- ✅ **Tenant isolation**: Multi-tenant data separation
- ✅ **GDPR compliance**: User data control
- ✅ **Rate limiting**: DoS protection
- ✅ **Input validation**: Pydantic schema validation
-
-### **🎯 Business-Specific Features**
-
-#### **Bakery Use Cases**
-
-```python
-# Forecast alerts when demand varies >20%
-# Daily production recommendations
-# Weekly performance reports
-# Stock shortage notifications
-# Weather impact alerts
-# Holiday/event notifications
-```
-
-#### **Spanish Localization**
-
- ✅ **Spanish templates**: Native Spanish content
- ✅ **Madrid timezone**: Europe/Madrid default
- ✅ **Spanish phone format**: +34 prefix handling
- ✅ **Local business hours**: Quiet hours support
- ✅ **Cultural context**: Bakery-specific terminology
-
-### **🔄 How to Deploy**
-
-#### **1. Add to Docker Compose**
-
-```yaml
-# Already integrated in your docker-compose.yml
-notification-service:
-  build: ./services/notification
-  ports:
-    - "8006:8000"
-  environment:
-    - DATABASE_URL=postgresql+asyncpg://notification_user:notification_pass123@notification-db:5432/notification_db
-  depends_on:
-    - notification-db
-    - redis
-    - rabbitmq
-```
-
-#### **2. Environment Setup**
-
-```bash
-# Copy environment template
-cp services/notification/.env.example services/notification/.env
-
-# Configure email provider
-SMTP_USER=your-email@gmail.com
-SMTP_PASSWORD=your-app-password
-
-# Configure WhatsApp (optional)
-WHATSAPP_API_KEY=your-twilio-sid:your-twilio-token
-```
-
-#### **3. Start Service**
-
-```bash
-# Service starts automatically with
-docker-compose up -d
-
-# Check health
-curl http://localhost:8006/health
-
-# View API docs
-open http://localhost:8006/docs
-```
-
-### **📈 API Usage Examples**
-
-#### **Send Welcome Email**
-
-```python
-POST /api/v1/notifications/send
-{
-  "type": "email",
-  "recipient_email": "usuario@panaderia.com",
-  "template_id": "welcome_email",
-  "template_data": {
-    "user_name": "Juan Carlos",
-    "dashboard_url": "https://app.bakeryforecast.es/dashboard"
-  }
-}
-```
-
-#### **Send Forecast Alert**
-
-```python
-POST /api/v1/notifications/send
-{
-  "type": "email",
-  "template_id": "forecast_alert_email",
-  "template_data": {
-    "bakery_name": "Panadería San Miguel",
-    "product_name": "Pan integral",
-    "forecast_date": "2025-01-25",
-    "predicted_demand": 120,
-    "variation_percentage": 35,
-    "alert_message": "Aumento significativo esperado. Se recomienda incrementar producción."
-  },
-  "broadcast": true,
-  "priority": "high"
-}
-```
-
-#### **Update User Preferences**
-
-```python
-PATCH /api/v1/notifications/preferences
-{
-  "email_alerts": true,
-  "whatsapp_enabled": false,
-  "quiet_hours_start": "22:00",
-  "quiet_hours_end": "08:00",
-  "language": "es"
-}
-```
-
-### **🎉 Key Benefits**
-
-#### **✅ Production Ready**
-
- Complete error handling and logging
- Health checks and monitoring
- Rate limiting and security
- Multi-tenant architecture
- Scalable event-driven design
-
-#### **✅ Business Focused**
-
- Spanish bakery templates
- Madrid timezone/localization
- Forecast-specific notifications
- Professional email designs
- WhatsApp support for urgent alerts
-
-#### **✅ Developer Friendly**
-
- Comprehensive API documentation
- Type-safe Pydantic schemas
- Async/await throughout
- Structured logging
- Easy testing and debugging
-
-#### **✅ Seamless Integration**
-
- Uses your shared libraries
- Integrates with gateway auth
- Follows your architectural patterns
- Maintains tenant isolation
- Publishes events to RabbitMQ
-
-### **🚀 Next Steps**
-
-#### **Immediate (Week 2)**
-
-1. **Deploy the service**: Add to your docker-compose and start
-2. **Configure SMTP**: Set up email provider credentials
-3. **Test integration**: Send test notifications via API
-4. **Event integration**: Verify RabbitMQ event handling
-
-#### **Production Optimization**
-
-1. **Email provider**: Consider SendGrid/Mailgun for production
-2. **WhatsApp setup**: Configure Twilio Business API
-3. **Template customization**: Add tenant-specific templates
-4. **Analytics dashboard**: Add notification analytics to frontend
-
-### **💡 Advanced Features Ready for Extension**
-
- ✅ **Push notifications**: Framework ready for mobile push
- ✅ **SMS support**: Easy to add SMS providers
- ✅ **A/B testing**: Template variant testing
- ✅ **Scheduled campaigns**: Marketing email campaigns
- ✅ **Analytics integration**: Detailed delivery analytics
-
-**This notification service is now a complete, production-ready microservice that fully integrates with your bakery forecasting platform! It handles all notification needs from welcome emails to urgent forecast alerts, with proper Spanish localization and bakery-specific templates.** 🎯