michangarrito/backups/docs-backup-2026-01-10/docs/01-epicas/MCH-017-notificaciones.md

MCH-017: Notificaciones

Metadata

• Codigo: MCH-017
• Fase: 4 - Pedidos y Clientes
• Prioridad: P1
• Estado: Pendiente
• Fecha estimada: Sprint 8-9

Descripcion

Sistema centralizado de notificaciones multi-canal: push notifications, WhatsApp, y SMS. Soporta notificaciones transaccionales, recordatorios, y alertas de negocio.

Objetivos

1. Push notifications (Firebase)
2. Notificaciones WhatsApp
3. SMS como fallback
4. Configuracion por usuario
5. Historial de notificaciones

Alcance

Incluido

• Push via Firebase Cloud Messaging
• WhatsApp via MCH-011
• SMS via Twilio (fallback)
• Preferencias por usuario
• Templates de notificacion
• Programacion de envios

Excluido

• Email (no prioritario para micro-negocios)
• Notificaciones in-app complejas
• Marketing automation

Tipos de Notificacion

Transaccionales (Inmediatas)

Evento	Canal Default	Mensaje
Nuevo pedido	Push + WhatsApp	"Nuevo pedido #123"
Pedido listo	WhatsApp	"Tu pedido esta listo"
Pago recibido	Push	"Pago de $500 recibido"
Stock bajo	Push	"Coca-Cola: quedan 5"

Recordatorios (Programados)

Tipo	Canal	Frecuencia
Fiado pendiente	WhatsApp	Segun config
Reporte semanal	WhatsApp	Lunes 8am
Cierre de caja	Push	Diario 9pm

Alertas de Negocio

Alerta	Canal	Trigger
Stock bajo	Push	stock < min_stock
Venta grande	Push	sale.total > threshold
Nuevo cliente	Push	customer.created

Modelo de Datos

Tablas (schema: notifications)

notification_templates

• id, tenant_id, code, channel
• title, body, variables
• active

notifications

• id, tenant_id, user_id, type
• channel, title, body
• status (pending/sent/delivered/failed)
• scheduled_at, sent_at, read_at

notification_preferences

• id, user_id, channel
• enabled, quiet_hours_start, quiet_hours_end

device_tokens

• id, user_id, platform (ios/android/web)
• token, active, created_at

Endpoints API

Metodo	Endpoint	Descripcion
POST	/notifications/send	Enviar notificacion
GET	/notifications	Historial
PUT	/notifications/:id/read	Marcar como leida
GET	/notifications/preferences	Preferencias
PUT	/notifications/preferences	Actualizar prefs
POST	/notifications/register-device	Registrar token

Arquitectura

┌─────────────┐     ┌─────────────────┐
│   Trigger   │────▶│  Notification   │
│   (Event)   │     │    Service      │
└─────────────┘     └────────┬────────┘
                             │
         ┌───────────────────┼───────────────────┐
         │                   │                   │
  ┌──────▼──────┐    ┌───────▼───────┐   ┌──────▼──────┐
  │   Firebase  │    │   WhatsApp    │   │   Twilio    │
  │     FCM     │    │    Service    │   │    SMS      │
  └─────────────┘    └───────────────┘   └─────────────┘

Templates de Notificacion

Push - Nuevo Pedido

{
  "code": "new_order",
  "channel": "push",
  "title": "🛒 Nuevo Pedido",
  "body": "Pedido #{{order_id}} de {{customer_name}} por ${{total}}"
}

WhatsApp - Pedido Listo

¡Tu pedido #{{order_id}} esta listo! 📦

{{items_summary}}

Total: ${{total}}

Puedes pasar a recogerlo a:
{{business_address}}

WhatsApp - Recordatorio Fiado

Hola {{customer_name}}, te recordamos que tienes
un saldo pendiente de ${{balance}} en {{business_name}}.

¿Cuando podrias pasar a liquidar?

Entregables

Entregable	Estado	Archivo
notifications.module	Pendiente	modules/notifications/
Firebase integration	Pendiente	providers/firebase.provider.ts
Twilio integration	Pendiente	providers/twilio.provider.ts
Notification preferences UI	Pendiente	components/settings/

Dependencias

Depende de

• MCH-011 (WhatsApp Service)
• MCH-002 (Auth - usuarios)

Bloquea a

• MCH-008 (Recordatorios fiado)
• MCH-015 (Notificaciones pedido)

Criterios de Aceptacion

• Push notifications funcionan (iOS/Android)
• WhatsApp notifications funcionan
• SMS fallback funciona
• Preferencias se respetan
• Historial se guarda correctamente

Configuracion

Firebase

{
  firebase: {
    projectId: process.env.FIREBASE_PROJECT_ID,
    privateKey: process.env.FIREBASE_PRIVATE_KEY,
    clientEmail: process.env.FIREBASE_CLIENT_EMAIL
  }
}

Quiet Hours

// Por usuario
{
  quiet_hours: {
    enabled: true,
    start: '22:00',
    end: '08:00'
  }
}

---

Ultima actualizacion: 2026-01-07