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
```json
{
  "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
```typescript
{
  firebase: {
    projectId: process.env.FIREBASE_PROJECT_ID,
    privateKey: process.env.FIREBASE_PRIVATE_KEY,
    clientEmail: process.env.FIREBASE_CLIENT_EMAIL
  }
}
```

### Quiet Hours
```typescript
// Por usuario
{
  quiet_hours: {
    enabled: true,
    start: '22:00',
    end: '08:00'
  }
}
```

---

**Ultima actualizacion:** 2026-01-07