bc43c9e772
✨ Características: - 45 ejercicios universitarios (Basic → Advanced) - Renderizado LaTeX profesional - IA generativa (Z.ai/DashScope) - Docker 9 servicios - Tests 123/123 pasando - Seguridad enterprise (JWT, XSS, Rate limiting) 🐳 Infraestructura: - Next.js 14 + Node.js 20 - PostgreSQL 15 + Redis 7 - Docker Compose completo - Nginx + SSL ready 📚 Documentación: - 5 informes técnicos completos - README profesional - Scripts de deployment automatizados Estado: Producción lista ✅
384 lines
18 KiB
Markdown
384 lines
18 KiB
Markdown
# Telegram Notifications Module - Architecture Diagram
|
|
|
|
## System Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ Math Platform Backend │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────────────┐│
|
|
│ │ Application Modules ││
|
|
│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ││
|
|
│ │ │ User │ │ Exercise │ │ Progress │ │ Ranking │ ││
|
|
│ │ │ Module │ │ Module │ │ Module │ │ Module │ ││
|
|
│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ ││
|
|
│ │ │ │ │ │ ││
|
|
│ │ └─────────────┴─────────────┴─────────────┘ ││
|
|
│ │ │ ││
|
|
│ │ ▼ ││
|
|
│ │ ┌───────────────────────────┐ ││
|
|
│ │ │ Notification Service │ ││
|
|
│ │ │ - sendNotification() │ ││
|
|
│ │ │ - notifyNewUser() │ ││
|
|
│ │ │ - notifySystemError() │ ││
|
|
│ │ │ - notifyModuleCompleted()│ ││
|
|
│ │ └─────────────┬─────────────┘ ││
|
|
│ │ │ ││
|
|
│ └────────────────────────────┼──────────────────────────────────────┘┘
|
|
│ │
|
|
│ ▼
|
|
│ ┌────────────────────────────────────────────────────────────────────┐│
|
|
│ │ Notification Layer ││
|
|
│ │ ││
|
|
│ │ ┌──────────────────────────────────────────────────────────────┐ ││
|
|
│ │ │ Message Templates (templates/) │ ││
|
|
│ │ │ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ ││
|
|
│ │ │ │ Alert │ │ Progress │ │ Achievement │ │ ││
|
|
│ │ │ │ Templates │ │ Templates │ │ Templates │ │ ││
|
|
│ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ ││
|
|
│ │ │ │ ││
|
|
│ │ │ - System Notifications - User Registration │ ││
|
|
│ │ │ - Error Notifications - Exercise Completion │ ││
|
|
│ │ │ - Security Alerts - Module Completion │ ││
|
|
│ │ │ - Performance Metrics - Achievements │ ││
|
|
│ │ └──────────────────────────────────────────────────────────────┘ ││
|
|
│ │ │ ││
|
|
│ │ ▼ ││
|
|
│ │ ┌──────────────────────────────────────────────────────────────┐ ││
|
|
│ │ │ Telegram Client (telegram.client.ts) │ ││
|
|
│ │ │ │ ││
|
|
│ │ │ - sendMessage() - sendPhoto() - sendDocument() │ ││
|
|
│ │ │ - getMe() - healthCheck() - Error Handling │ ││
|
|
│ │ │ │ ││
|
|
│ │ │ Axios HTTP Client with Retry Logic │ ││
|
|
│ │ └──────────────────────────────────────────────────────────────┘ ││
|
|
│ └──────────────────────────────┬───────────────────────────────────┘┘
|
|
│ │
|
|
│ ▼
|
|
│ ┌────────────────────────────────────────────────────────────────────┐│
|
|
│ │ Queue & Worker Layer ││
|
|
│ │ ││
|
|
│ │ ┌──────────────────────────────────────────────────────────────┐ ││
|
|
│ │ │ Bull Queue (notification-sender.worker.ts) │ ││
|
|
│ │ │ │ ││
|
|
│ │ │ ┌────────────┐ ┌────────────┐ ┌────────────┐ │ ││
|
|
│ │ │ │ Queue │ │ Worker │ │ Retry │ │ ││
|
|
│ │ │ │ Management │ │ Processor │ │ Logic │ │ ││
|
|
│ │ │ └────────────┘ └────────────┘ └────────────┘ │ ││
|
|
│ │ │ │ ││
|
|
│ │ │ - Job Priority - Rate Limiting - Auto Cleanup │ ││
|
|
│ │ │ - Concurrency - Exponential Backoff │ ││
|
|
│ │ └──────────────────────────────────────────────────────────────┘ ││
|
|
│ └──────────────────────────────┬───────────────────────────────────┘┘
|
|
│ │
|
|
└───────────────────────────────────┼───────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────────────┐
|
|
│ External Services │
|
|
├─────────────────────────────────────────────────────────────────────────┤
|
|
│ │
|
|
│ ┌──────────────────────┐ ┌──────────────────────┐ │
|
|
│ │ │ │ │ │
|
|
│ │ Redis Queue │ │ Telegram API │ │
|
|
│ │ │ │ │ │
|
|
│ │ - Job Storage │ │ - Bot API │ │
|
|
│ │ - State Management │ │ - Message Delivery │ │
|
|
│ │ - Retry Tracking │ │ - Webhooks (optional)│ │
|
|
│ │ │ │ │ │
|
|
│ └──────────────────────┘ └──────────────────────┘ │
|
|
│ │
|
|
└───────────────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────┐
|
|
│ │
|
|
│ Admin Telegram │
|
|
│ Chat │
|
|
│ │
|
|
│ - Notifications │
|
|
│ - Alerts │
|
|
│ - Reports │
|
|
│ │
|
|
└─────────────────────┘
|
|
```
|
|
|
|
## Data Flow
|
|
|
|
### 1. Notification Creation Flow
|
|
|
|
```
|
|
User Action
|
|
│
|
|
▼
|
|
Module Event (e.g., User Registration)
|
|
│
|
|
▼
|
|
Notification Service
|
|
│
|
|
├─→ Create Notification in Database
|
|
│ (status: PENDING)
|
|
│
|
|
├─→ Format Message (Templates)
|
|
│ - HTML formatting
|
|
│ - Data sanitization
|
|
│ - Emoji addition
|
|
│
|
|
└─→ Queue for Processing
|
|
(Bull Queue + Redis)
|
|
```
|
|
|
|
### 2. Notification Processing Flow
|
|
|
|
```
|
|
Worker Process
|
|
│
|
|
├─→ Get Job from Queue
|
|
│ (Priority-based)
|
|
│
|
|
├─→ Update Attempt Count
|
|
│
|
|
├─→ Send via Telegram Client
|
|
│ │
|
|
│ ├─→ Success?
|
|
│ │ │
|
|
│ │ ├─→ Yes: Mark as SENT
|
|
│ │ │ - Update DB
|
|
│ │ │ - Log success
|
|
│ │ │ - Remove from queue
|
|
│ │ │
|
|
│ │ └─→ No: Handle Error
|
|
│ │ - Check retry limit
|
|
│ │ - Exponential backoff
|
|
│ │ - Requeue or mark FAILED
|
|
│ │
|
|
│ └─→ HTTP Request
|
|
│ (Axios with retry)
|
|
│
|
|
└─→ Next Job
|
|
```
|
|
|
|
### 3. Error Handling Flow
|
|
|
|
```
|
|
Error Occurs
|
|
│
|
|
▼
|
|
Error Type Detection
|
|
│
|
|
├─→ Rate Limit (429)?
|
|
│ └─→ Wait retry_after seconds
|
|
│ └─→ Retry
|
|
│
|
|
├─→ Client Error (400, 403)?
|
|
│ └─→ Log and mark FAILED
|
|
│ └─→ Don't retry
|
|
│
|
|
├─→ Server Error (500, 502)?
|
|
│ └─→ Exponential backoff
|
|
│ └─→ Retry up to limit
|
|
│
|
|
└─→ Network Error?
|
|
└─→ Exponential backoff
|
|
└─→ Retry up to limit
|
|
```
|
|
|
|
## Component Details
|
|
|
|
### 1. Configuration (config/telegram.ts)
|
|
|
|
**Responsibilities:**
|
|
- Bot token management
|
|
- Admin chat ID storage
|
|
- API endpoint configuration
|
|
- Priority filtering
|
|
- Validation
|
|
|
|
**Key Functions:**
|
|
- `getConfig()` - Get current configuration
|
|
- `getBotToken()` - Get bot token
|
|
- `getAdminChatId()` - Get admin chat ID
|
|
- `shouldSendByPriority()` - Check priority filter
|
|
- `healthCheck()` - Validate configuration
|
|
|
|
### 2. Telegram Client (telegram/telegram.client.ts)
|
|
|
|
**Responsibilities:**
|
|
- HTTP communication with Telegram API
|
|
- Request retry logic
|
|
- Error handling and mapping
|
|
- Message formatting
|
|
|
|
**Key Functions:**
|
|
- `sendMessage()` - Send text message
|
|
- `sendPhoto()` - Send photo
|
|
- `sendDocument()` - Send document
|
|
- `getMe()` - Get bot info
|
|
- `healthCheck()` - Test connection
|
|
|
|
**Error Handling:**
|
|
- 429: Rate limiting (wait and retry)
|
|
- 401: Invalid token (don't retry)
|
|
- 403: Bot blocked (don't retry)
|
|
- 400: Bad request (don't retry)
|
|
- 500+: Server errors (retry with backoff)
|
|
|
|
### 3. Templates (telegram/templates/)
|
|
|
|
**Alert Template:**
|
|
- System notifications
|
|
- Error alerts
|
|
- Daily summaries
|
|
- Security alerts
|
|
|
|
**Progress Template:**
|
|
- Exercise completion
|
|
- Module completion
|
|
- Streak updates
|
|
- Progress summaries
|
|
|
|
**Achievement Template:**
|
|
- Badge unlocks
|
|
- Ranking milestones
|
|
- Top 10 entries
|
|
- Achievement summaries
|
|
|
|
### 4. Notification Service (notification.service.ts)
|
|
|
|
**Responsibilities:**
|
|
- Business logic for notifications
|
|
- Queue management
|
|
- Statistics tracking
|
|
- Convenience methods
|
|
|
|
**Key Functions:**
|
|
- `sendNotification()` - Generic notification sender
|
|
- `notifyNewUser()` - User registration alert
|
|
- `notifySystemError()` - Error reporting
|
|
- `notifyModuleCompleted()` - Module completion
|
|
- `notifyTop10Entry()` - Top 10 achievement
|
|
- `getStatistics()` - Get notification stats
|
|
|
|
### 5. Worker (workers/notification-sender.worker.ts)
|
|
|
|
**Responsibilities:**
|
|
- Background job processing
|
|
- Queue management
|
|
- Retry logic
|
|
- Job cleanup
|
|
|
|
**Key Functions:**
|
|
- `queueNotification()` - Add job to queue
|
|
- `retryFailedNotifications()` - Retry failed jobs
|
|
- `getQueueStats()` - Get queue statistics
|
|
- `pauseQueue()` / `resumeQueue()` - Queue control
|
|
|
|
**Queue Configuration:**
|
|
- Concurrency: 3 jobs
|
|
- Rate limit: 20 messages/minute
|
|
- Max retries: 3
|
|
- Backoff: Exponential
|
|
- Cleanup: 24h (completed), 7d (failed)
|
|
|
|
## Security Considerations
|
|
|
|
### 1. No End-User Exposure
|
|
- Telegram completely hidden from users
|
|
- Bot token never exposed in API
|
|
- Admin chat ID is server-side only
|
|
|
|
### 2. Input Sanitization
|
|
- HTML escaping in templates
|
|
- Length limits on messages
|
|
- Truncation of long content
|
|
|
|
### 3. Rate Limiting
|
|
- Built-in rate limiting (20/min)
|
|
- Respects Telegram API limits
|
|
- Queue prevents spam
|
|
|
|
### 4. Error Filtering
|
|
- Sensitive data not in errors
|
|
- Stack traces truncated
|
|
- User data anonymized
|
|
|
|
## Performance Optimizations
|
|
|
|
### 1. Async Processing
|
|
- All notifications queued
|
|
- Non-blocking for main thread
|
|
- Background worker processing
|
|
|
|
### 2. Connection Pooling
|
|
- Axios instance reuse
|
|
- HTTP/2 support
|
|
- Keep-alive connections
|
|
|
|
### 3. Efficient Queue
|
|
- Redis for fast operations
|
|
- Job prioritization
|
|
- Batch processing support
|
|
|
|
### 4. Smart Retry
|
|
- Exponential backoff
|
|
- Respect retry-after header
|
|
- Skip non-retryable errors
|
|
|
|
## Monitoring & Observability
|
|
|
|
### 1. Logging
|
|
- Structured logging with Winston
|
|
- Correlation IDs for tracking
|
|
- Debug level for development
|
|
|
|
### 2. Metrics
|
|
- Queue depth
|
|
- Processing time
|
|
- Success/failure rates
|
|
- Rate limit hits
|
|
|
|
### 3. Health Checks
|
|
- Telegram connection
|
|
- Queue status
|
|
- Worker status
|
|
- Redis connection
|
|
|
|
### 4. Statistics
|
|
- Total notifications
|
|
- By type
|
|
- By status
|
|
- Today's counts
|
|
|
|
## Scalability Considerations
|
|
|
|
### Horizontal Scaling
|
|
- Worker can run on multiple servers
|
|
- Redis shared queue
|
|
- No local state
|
|
|
|
### Vertical Scaling
|
|
- Configurable concurrency
|
|
- Adjustable rate limits
|
|
- Memory-efficient queue
|
|
|
|
### Load Handling
|
|
- Queue absorbs spikes
|
|
- Priority ensures important messages first
|
|
- Rate limiting prevents overload
|
|
|
|
## Summary
|
|
|
|
The Telegram Notifications Module provides:
|
|
|
|
1. **Complete Implementation**: All components in place
|
|
2. **Production Ready**: Error handling, retry, monitoring
|
|
3. **Well Architected**: Separation of concerns, modular design
|
|
4. **Scalable**: Async processing, queue-based
|
|
5. **Secure**: No user exposure, input sanitization
|
|
6. **Maintainable**: Clear structure, good documentation
|
|
7. **Testable**: Test scripts, health checks
|
|
8. **Observable**: Logging, metrics, statistics
|
|
|
|
The module is ready for production use and can handle high notification loads while maintaining reliability and performance.
|