trading-platform/orchestration/tareas/_archive/2026-01/TASK-2026-01-25-PHASE1-MVP/06-DOCUMENTACION.md

06-DOCUMENTACION - Phase 1 MVP Implementation

Resumen Ejecutivo

Se completó la implementación de los componentes finales del Phase 1 MVP:

1. Servicio de Notificaciones: Sistema unificado para envío de notificaciones a través de múltiples canales (WebSocket, email, push).

2. Job de Distribución: Cron job diario para cálculo y distribución automática de rendimientos de inversión.

API de Notificaciones

Endpoints

Método	Ruta	Descripción
GET	/api/v1/notifications	Listar notificaciones del usuario
GET	/api/v1/notifications/unread-count	Obtener conteo de no leídas
GET	/api/v1/notifications/preferences	Obtener preferencias
PATCH	/api/v1/notifications/preferences	Actualizar preferencias
POST	/api/v1/notifications/read-all	Marcar todas como leídas
PATCH	/api/v1/notifications/:id/read	Marcar una como leída
DELETE	/api/v1/notifications/:id	Eliminar notificación

Tipos de Notificación

Tipo	Descripción	Canales Default
alert_triggered	Alerta de precio activada	in_app, email, push
trade_executed	Orden ejecutada	in_app, email
deposit_confirmed	Depósito confirmado	in_app, email
withdrawal_completed	Retiro completado	in_app, email
distribution_received	Rendimiento recibido	in_app, email
system_announcement	Anuncio del sistema	in_app
security_alert	Alerta de seguridad	in_app, email, push
account_update	Actualización de cuenta	in_app

Preferencias de Usuario

interface UserNotificationPreferences {
  emailEnabled: boolean;      // Recibir emails
  pushEnabled: boolean;       // Recibir push
  inAppEnabled: boolean;      // Mostrar in-app
  smsEnabled: boolean;        // Recibir SMS
  quietHoursStart?: string;   // Inicio horas silenciosas (HH:MM)
  quietHoursEnd?: string;     // Fin horas silenciosas (HH:MM)
  disabledTypes: string[];    // Tipos deshabilitados
}

Job de Distribución

Configuración

• Frecuencia: Diaria a las 00:00 UTC
• Método de Cálculo:
  • Tasa mensual promedio / 30 días
  • Varianza diaria: -15% a +35%
• Performance Fee: Aplicado sobre rendimiento bruto
• Mínimo distribución: > $0.01

Productos y Tasas

Producto	Retorno Mensual	Performance Fee
Atlas	3% - 5%	20%
Orion	5% - 10%	20%
Nova	10% - 20%	20%

Flujo de Distribución

1. Obtener cuentas activas con balance > 0
2. Para cada cuenta:
   a. Calcular retorno diario con varianza
   b. Si retorno > 0:
      - Calcular fee
      - Actualizar balance
      - Registrar transacción
      - Registrar en distribution_history
      - Enviar notificación
3. Registrar resumen en distribution_runs

Integración con Alertas

El servicio de alertas ahora envía notificaciones automáticamente cuando se activa una alerta de precio:

// alerts.service.ts - triggerAlert()
await notificationService.sendAlertNotification(alert.userId, {
  symbol: alert.symbol,
  condition: alert.condition,
  targetPrice: alert.price,
  currentPrice,
  note: alert.note,
});

Próximos Pasos Sugeridos

1. DDL: Crear tablas notifications, user_push_tokens, investment.distribution_history, investment.distribution_runs

2. Push Notifications: Integrar con Firebase Cloud Messaging (FCM) para Android/Web y APNS para iOS

3. SMS: Integrar Twilio para notificaciones SMS (ya en package.json)

4. Testing: Crear tests unitarios para notification.service y distribution.job

5. Admin UI: Panel para ver estadísticas de distribuciones

Archivos de Referencia

Archivo	Propósito
notification.service.ts	Servicio core de notificaciones
distribution.job.ts	Job de distribución de rendimientos
alerts.service.ts	Integración de alertas con notificaciones

Checklist Final

• Servicio de notificaciones creado
• API REST de notificaciones expuesta
• Integración con WebSocket para real-time
• Templates de email implementados
• Job de distribución implementado
• Integración con alerts service
• Graceful shutdown implementado
• TypeScript compila sin errores (en archivos nuevos)
• Documentación CAPVED completa