🔔 EPIC 4 — Sistema de Alertas Proactivas y Directorio de Contactos

# 🔔 EPIC 4 — Sistema de Alertas Proactivas y Directorio de Contactos ## Descripción Implementar el módulo completo de alertas proactivas multi-canal y el directorio de contactos clave (empresas, universidades, programas de talento junior) para CyberRemote Monitor Pro. El objetivo es que usuarios, gobiernos y universidades puedan **suscribirse a oportunidades por perfil, ciudad o especialidad** y recibir notificaciones automáticas en tiempo real en sus canales preferidos. --- ## 🎯 Objetivos - Permitir suscripciones granulares por país, ciudad, especialidad y nivel - Enviar alertas proactivas cuando aparezcan vacantes que coincidan con el perfil - Integrar canales: **Email**, **Telegram Bot**, **WhatsApp (Twilio)** - Construir un directorio navegable de contactos: empresas remotas, programas de becas, universidades y agencias gubernamentales - Soporte multi-tenant: alertas por organización/gobierno con múltiples destinatarios --- ## 📋 Tareas (Sub-issues) ### Backend — Motor de Alertas - [ ] **#B1** — Modelo de BD `alert_subscriptions` (ya en schema SQL — conectar con API) - [ ] **#B2** — Endpoint `POST /api/v1/alerts/subscriptions` — crear suscripción por perfil - [ ] **#B3** — Endpoint `GET /api/v1/alerts/subscriptions` — listar suscripciones del usuario - [ ] **#B4** — Endpoint `DELETE /api/v1/alerts/subscriptions/{id}` — cancelar suscripción - [ ] **#B5** — Motor de matching: comparar nuevas vacantes ingresadas vs suscripciones activas - [ ] **#B6** — Worker Celery `alerts_dispatcher` — despacha notificaciones cuando hay match - [ ] **#B7** — Rate limiting de alertas por usuario (máx. N alertas/hora) ### Integraciones de Canales - [ ] **#C1** — Integración **Email** (SendGrid / SMTP) con template HTML profesional - [ ] **#C2** — Integración **Telegram Bot** (`python-telegram-bot`) — comando `/subscribe`, `/unsubscribe`, `/status` - [ ] **#C3** — Integración **WhatsApp** (Twilio API) — mensajes de alerta formateados - [ ] **#C4** — (Opcional) Integración **Slack Webhook** para equipos gubernamentales ### Directorio de Contactos - [ ] **#D1** — Modelo de BD `contacts_directory` (empresas, universidades, programas, agencias) - [ ] **#D2** — Dataset inicial: 50+ empresas que contratan remoto juniors en ciberseguridad - [ ] **#D3** — Dataset inicial: 20+ programas de becas/talento junior (LATAM + global) - [ ] **#D4** — Endpoint `GET /api/v1/contacts` con filtros (tipo, país, especialidad) - [ ] **#D5** — Panel frontend: directorio navegable con tarjetas de contacto ### Frontend — UI de Alertas - [ ] **#F1** — Componente `AlertsSubscriptionModal` — formulario de suscripción con filtros - [ ] **#F2** — Panel "Mis Alertas" — lista de suscripciones activas con toggle on/off - [ ] **#F3** — Indicador visual en el globo 3D cuando hay alertas activas para un país - [ ] **#F4** — Notificación in-app (toast) cuando llega una alerta en tiempo real (WebSocket) --- ## 🏗️ Arquitectura del Módulo ``` [Nueva vacante ingresada] ↓ [jobs_ingestor] → [PostgreSQL jobs] ↓ [Celery Task: check_alerts] ↓ [Motor de matching: vacante vs alert_subscriptions] ↓ (matches encontrados) [alerts_dispatcher Worker] / | \ [Email] [Telegram] [WhatsApp] ``` --- ## 📐 Esquema de Datos ```python # Suscripción de alerta class AlertSubscription(BaseModel): id: UUID user_id: UUID tenant_id: UUID # para modo gobierno (múltiples destinatarios) country_code: str | None city: str | None specialty: str | None # pentesting | soc | cloud | devsecops | osint level: str | None # junior | semi-junior | mid channel: str # email | telegram | whatsapp | slack channel_target: str # email address | chat_id | phone number is_active: bool created_at: datetime # Directorio de contactos class ContactDirectory(BaseModel): id: UUID name: str type: str # company | university | scholarship | government_agency country_cod