module:
  name: notifications
  version: 1.0.0
  description: Sistema completo de notificaciones multi-canal con soporte para push, email, SMS, in-app y webhooks
  category: communication
  author: MCP Backend Modular
  license: MIT

# Condiciones de activación
activation:
  keywords:
    - notification
    - notifications
    - push
    - alert
    - alerts
    - messaging
    - notify
    - announcement
    - broadcast
    - real-time
    - firebase
    - fcm
    - apns
    - sms
    - twilio
    - webhook
    - in-app
  patterns:
    - "send notification"
    - "push notification"
    - "real-time alerts"
    - "notification system"
    - "messaging service"
    - "broadcast message"

# Puntos de entrada del módulo
entry_points:
  service: src/notifications/notifications.service.ts
  gateway: src/notifications/notifications.gateway.ts
  controller: src/notifications/notifications.controller.ts
  module: src/notifications/notifications.module.ts
  queue: src/notifications/queue/notification.queue.ts
  providers: src/notifications/providers/
  templates: src/notifications/templates/
  scheduler: src/notifications/scheduler/notification.scheduler.ts

# Dependencias
dependencies:
  required:
    - database
  optional:
    - auth
    - logging
    - cache
    - websockets
    - email
    - queue

# Variables de entorno
environment:
  required:
    - NOTIFICATIONS_ENABLED
  optional:
    # Firebase/FCM
    - FIREBASE_PROJECT_ID
    - FIREBASE_PRIVATE_KEY
    - FIREBASE_CLIENT_EMAIL
    - FCM_SERVER_KEY
    
    # Apple Push Notifications
    - APNS_KEY_ID
    - APNS_TEAM_ID
    - APNS_BUNDLE_ID
    - APNS_PRIVATE_KEY
    - APNS_PRODUCTION
    
    # SMS (Twilio)
    - TWILIO_ACCOUNT_SID
    - TWILIO_AUTH_TOKEN
    - TWILIO_PHONE_NUMBER
    
    # Webhooks
    - WEBHOOK_SECRET
    - WEBHOOK_TIMEOUT
    
    # Configuración general
    - NOTIFICATION_QUEUE_ENABLED
    - NOTIFICATION_RETRY_ATTEMPTS
    - NOTIFICATION_BATCH_SIZE
    - NOTIFICATION_RATE_LIMIT
    - NOTIFICATION_TEMPLATES_PATH

# Características principales
features:
  channels:
    - push_notifications
    - email_notifications
    - sms_notifications
    - in_app_notifications
    - webhook_notifications
    - browser_notifications
  
  providers:
    - firebase_fcm
    - apple_apns
    - twilio_sms
    - custom_webhook
    - websocket_realtime
  
  functionality:
    - template_system
    - notification_queue
    - batch_processing
    - scheduled_notifications
    - notification_preferences
    - delivery_tracking
    - retry_mechanism
    - rate_limiting
    - notification_history
    - analytics_tracking
    - user_subscriptions
    - device_management
    - notification_categories
    - priority_levels
    - localization_support

# Endpoints de API
api_endpoints:
  - method: POST
    path: /notifications/send
    description: Enviar notificación individual
    auth_required: true
  
  - method: POST
    path: /notifications/broadcast
    description: Enviar notificación masiva
    auth_required: true
    permissions: ["notifications:broadcast"]
  
  - method: POST
    path: /notifications/schedule
    description: Programar notificación
    auth_required: true
  
  - method: GET
    path: /notifications/history
    description: Historial de notificaciones
    auth_required: true
  
  - method: GET
    path: /notifications/preferences
    description: Preferencias de usuario
    auth_required: true
  
  - method: PUT
    path: /notifications/preferences
    description: Actualizar preferencias
    auth_required: true
  
  - method: POST
    path: /notifications/devices
    description: Registrar dispositivo
    auth_required: true
  
  - method: DELETE
    path: /notifications/devices/:deviceId
    description: Eliminar dispositivo
    auth_required: true
  
  - method: GET
    path: /notifications/templates
    description: Listar plantillas
    auth_required: true
    permissions: ["notifications:manage"]
  
  - method: POST
    path: /notifications/templates
    description: Crear plantilla
    auth_required: true
    permissions: ["notifications:manage"]
  
  - method: GET
    path: /notifications/analytics
    description: Analíticas de notificaciones
    auth_required: true
    permissions: ["notifications:analytics"]

# Archivos generados
generated_files:
  - src/notifications/notifications.service.ts
  - src/notifications/notifications.gateway.ts
  - src/notifications/notifications.controller.ts
  - src/notifications/notifications.module.ts
  - src/notifications/queue/notification.queue.ts
  - src/notifications/scheduler/notification.scheduler.ts
  - src/notifications/providers/firebase.provider.ts
  - src/notifications/providers/apns.provider.ts
  - src/notifications/providers/twilio.provider.ts
  - src/notifications/providers/webhook.provider.ts
  - src/notifications/providers/websocket.provider.ts
  - src/notifications/templates/notification.template.ts
  - src/notifications/interfaces/notification.interface.ts
  - src/notifications/dto/notification.dto.ts
  - src/notifications/entities/notification.entity.ts
  - src/notifications/guards/notification.guard.ts
  - src/notifications/decorators/notification.decorator.ts

# Integración con base de datos
database_integration:
  tables:
    - name: notifications
      description: Registro de notificaciones enviadas
      fields:
        - id: String (UUID)
        - userId: String
        - title: String
        - body: String
        - channel: String
        - status: String
        - scheduledAt: DateTime
        - sentAt: DateTime
        - readAt: DateTime
        - metadata: Json
        - createdAt: DateTime
        - updatedAt: DateTime
    
    - name: notification_templates
      description: Plantillas de notificaciones
      fields:
        - id: String (UUID)
        - name: String
        - title: String
        - body: String
        - channel: String
        - variables: Json
        - isActive: Boolean
        - createdAt: DateTime
        - updatedAt: DateTime
    
    - name: notification_preferences
      description: Preferencias de usuario
      fields:
        - id: String (UUID)
        - userId: String
        - channel: String
        - enabled: Boolean
        - settings: Json
        - createdAt: DateTime
        - updatedAt: DateTime
    
    - name: user_devices
      description: Dispositivos registrados
      fields:
        - id: String (UUID)
        - userId: String
        - deviceToken: String
        - platform: String
        - appVersion: String
        - isActive: Boolean
        - lastUsed: DateTime
        - createdAt: DateTime
        - updatedAt: DateTime
    
    - name: notification_analytics
      description: Analíticas de notificaciones
      fields:
        - id: String (UUID)
        - notificationId: String
        - event: String
        - timestamp: DateTime
        - metadata: Json

# Integración con autenticación
auth_integration:
  permissions:
    - notifications:send
    - notifications:broadcast
    - notifications:manage
    - notifications:analytics
    - notifications:templates
  
  user_context:
    - user_id: Para notificaciones personalizadas
    - user_preferences: Para respetar configuraciones
    - user_devices: Para envío a dispositivos específicos

# Integración con otros módulos
module_integration:
  websockets:
    - real_time_notifications
    - notification_status_updates
    - typing_indicators
  
  email:
    - email_notification_fallback
    - rich_email_templates
    - email_tracking
  
  cache:
    - template_caching
    - user_preferences_cache
    - device_token_cache
  
  logging:
    - notification_audit_logs
    - delivery_tracking
    - error_logging

# Canales de notificación
channels:
  push:
    platforms:
      - ios
      - android
      - web
    providers:
      - firebase_fcm
      - apple_apns
    features:
      - rich_notifications
      - action_buttons
      - custom_sounds
      - badges
  
  email:
    features:
      - html_templates
      - attachments
      - tracking
      - scheduling
  
  sms:
    providers:
      - twilio
      - custom
    features:
      - international_support
      - delivery_reports
      - opt_out_handling
  
  in_app:
    features:
      - real_time_delivery
      - read_receipts
      - notification_center
      - persistence
  
  webhook:
    features:
      - custom_payloads
      - retry_logic
      - signature_verification
      - timeout_handling

# Tipos de notificación
notification_types:
  - system_alerts
  - user_messages
  - promotional
  - transactional
  - security_alerts
  - reminders
  - announcements
  - updates

# Niveles de prioridad
priority_levels:
  - low
  - normal
  - high
  - urgent
  - critical

# Sistema de plantillas
template_system:
  engines:
    - handlebars
    - mustache
    - custom
  
  variables:
    - user_data
    - dynamic_content
    - localization
    - conditional_blocks
  
  features:
    - template_inheritance
    - partial_templates
    - template_validation
    - preview_mode

# Ejemplos de uso
examples:
  basic_notification:
    description: "Envío básico de notificación"
    code: |
      await notificationService.send({
        userId: 'user123',
        title: 'Nueva mensaje',
        body: 'Tienes un nuevo mensaje',
        channel: 'push'
      });
  
  scheduled_notification:
    description: "Notificación programada"
    code: |
      await notificationService.schedule({
        userId: 'user123',
        title: 'Recordatorio',
        body: 'No olvides tu cita',
        channel: 'push',
        scheduledAt: new Date('2024-01-15T10:00:00Z')
      });
  
  broadcast_notification:
    description: "Notificación masiva"
    code: |
      await notificationService.broadcast({
        title: 'Mantenimiento programado',
        body: 'El sistema estará en mantenimiento',
        channels: ['push', 'email'],
        audience: { role: 'user' }
      });
  
  template_notification:
    description: "Notificación con plantilla"
    code: |
      await notificationService.sendFromTemplate({
        templateId: 'welcome-template',
        userId: 'user123',
        variables: {
          userName: 'Juan',
          appName: 'Mi App'
        }
      });

# Instrucciones para agentes de IA
ai_instructions:
  setup:
    - "Detectar automáticamente proveedores de notificación disponibles"
    - "Configurar canales según variables de entorno"
    - "Generar plantillas base para cada tipo de notificación"
    - "Configurar cola de notificaciones si está habilitada"
  
  usage:
    - "Usar el servicio de notificaciones para envíos simples"
    - "Implementar gateway para notificaciones en tiempo real"
    - "Configurar preferencias de usuario automáticamente"
    - "Manejar errores de entrega con reintentos"
  
  best_practices:
    - "Respetar preferencias de usuario"
    - "Implementar rate limiting"
    - "Usar plantillas para consistencia"
    - "Trackear métricas de entrega"
    - "Manejar tokens de dispositivo expirados"

# Scripts de automatización
automation_scripts:
  - name: generate-template
    description: Generar nueva plantilla de notificación
    command: node scripts/generate-notification-template.js
  
  - name: test-providers
    description: Probar conectividad con proveedores
    command: node scripts/test-notification-providers.js
  
  - name: cleanup-devices
    description: Limpiar dispositivos inactivos
    command: node scripts/cleanup-inactive-devices.js
  
  - name: analytics-report
    description: Generar reporte de analíticas
    command: node scripts/generate-analytics-report.js

# Pruebas
testing:
  unit_tests:
    - notification.service.spec.ts
    - notification.gateway.spec.ts
    - firebase.provider.spec.ts
    - template.service.spec.ts
  
  integration_tests:
    - notification-flow.e2e.spec.ts
    - provider-integration.e2e.spec.ts
    - queue-processing.e2e.spec.ts
  
  load_tests:
    - bulk-notification.load.spec.ts
    - concurrent-sending.load.spec.ts

# Métricas de rendimiento
performance_metrics:
  throughput:
    - notifications_per_second: 1000+
    - batch_processing_size: 100-1000
    - queue_processing_rate: 500/min
  
  latency:
    - push_notification_delivery: <2s
    - email_notification_delivery: <30s
    - sms_notification_delivery: <10s
    - in_app_notification_delivery: <100ms
  
  reliability:
    delivery_success_rate: ">99%"
    retry_success_rate: ">95%"
    uptime: ">99.9%"

# Optimización
optimization:
  caching:
    - template_cache: 1h
    - user_preferences_cache: 30min
    - device_tokens_cache: 24h
  
  batching:
    - batch_size: 100-1000
    - batch_timeout: 5s
    - parallel_batches: 10
  
  rate_limiting:
    - per_user: 100/hour
    - per_app: 10000/hour
    - burst_limit: 10/min

# Escalado
scaling:
  horizontal:
    - queue_workers: auto-scale
    - notification_processors: load-balanced
    - database_sharding: by_user_id
  
  vertical:
    - memory_optimization: template_caching
    - cpu_optimization: batch_processing
    - io_optimization: connection_pooling
  
  limits:
    - max_concurrent_notifications: 10000
    - max_queue_size: 1000000
    - max_template_size: 10KB

# Seguridad
security:
  features:
    - webhook_signature_verification
    - device_token_encryption
    - rate_limiting
    - input_validation
    - audit_logging
  
  best_practices:
    - secure_token_storage
    - encrypted_communications
    - access_control
    - data_privacy
    - gdpr_compliance

# Compatibilidad
compatibility:
  node_versions:
    - ">=16.0.0"
  
  frameworks:
    - nestjs: ">=9.0.0"
    - express: ">=4.18.0"
  
  databases:
    - postgresql: ">=12.0"
    - mysql: ">=8.0"
    - mongodb: ">=5.0"
  
  providers:
    - firebase: ">=9.0.0"
    - twilio: ">=3.0.0"
    - apns2: ">=11.0.0"

# Documentación
documentation:
  - README.md
  - API.md
  - PROVIDERS.md
  - TEMPLATES.md
  - DEPLOYMENT.md
  - TROUBLESHOOTING.md