# Matriz de Notificaciones Push (Expo)

Este documento resume todas las acciones del backend que envian notificaciones push, a quien se envian y como probar cada escenario.

## Flujo base de push

- Registro de token: `POST /api/expo-token/register`
- Envio directo de prueba: `POST /api/expo-token/direct-test`
- Envio real por negocio: `NotificationService` -> `ExpoPushNotificationService` -> `ExpoNotificationService`

## Regla clave de destinatarios

Para que alguien reciba push, debe existir:

1. Un `user` asociado al destinatario esperado.
2. Un `ExpoToken` registrado para ese usuario.

En varios flujos, shipper/receiver reciben push solo si estan vinculados a `pobox.user`.

---

## 1) Prueba tecnica directa por token

### Endpoint

- `POST /api/expo-token/direct-test`

### Destinatario

- El `token` enviado en el body.

### Body minimo

```json
{
  "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]"
}
```

### Body completo

```json
{
  "token": "ExponentPushToken[xxxxxxxxxxxxxxxxxxxxxx]",
  "title": "Prueba desde API",
  "body": "Si ves esto, Expo push funciona",
  "data": {
    "kind": "manual-test"
  }
}
```

### Uso recomendado

Confirmar si la API puede enviar correctamente a Expo sin depender de reglas de negocio.

---

## 2) Eventos que notifican a usuarios SISTEMA (admins operativos)

Estos envios usan el evento `system_users`.

### Destinatarios push

- Usuarios con:
  - misma `maincompany`
  - `user.type = SISTEMA`
  - token Expo registrado

### Acciones que disparan push

1. Crear alerta (`AlertService::createAlert`)
2. Crear pickup (`PickupService::createPickup`)
3. Crear reempaque (`ReempackService::createReempack`)
4. Crear reempaque strict (`ReempackService::createReempackStrict`)

### Como probar

1. Iniciar sesion con un usuario SISTEMA en la app y registrar token (`/api/expo-token/register`).
2. Ejecutar una de las acciones anteriores.
3. Verificar push en ese usuario SISTEMA.

---

## 3) Notificaciones batch de documentos

## 3.1 Receipt batch

### Endpoint

- `POST /api/receipt/send-notifications`

### Evento interno

- `receipt_batch`

### Destinatarios push

- `receipt.shipper.pobox.user`
- `receipt.receiver.customer.pobox.user`

### Body

```json
{
  "entityIds": [1, 2, 3]
}
```

## 3.2 Guide batch

### Endpoint

- `POST /api/guide/send-notifications`

### Evento interno

- `guide_batch`

### Destinatarios push

- `guide.sender.pobox.user`
- `guide.addressee.customer.pobox.user`

### Body

```json
{
  "entityIds": [101, 102]
}
```

## 3.3 Warehouse batch

### Endpoint

- `POST /api/warehouse-receipt/send-notifications`

### Evento interno

- `warehouse_batch`

### Destinatarios push

- `whrec.shipper.pobox.user`
- `whrec.receiver.customer.pobox.user`

### Body

```json
{
  "entityIds": [201, 202]
}
```

### Como probar shipper vs receiver

- Solo shipper: shipper con `pobox.user` + token; receiver sin vinculo/token.
- Solo receiver: receiver con `pobox.user` + token; shipper sin vinculo/token.
- Ambos: ambos con `pobox.user` y token.
- Ninguno: no debe enviar push (skipped/0 tokens).

---

## 4) Notificaciones por creacion de estado (automaticas)

## 4.1 Guide status

### Flujo

- `GuideController::createStatusForGuideAction`
- `GuideService::createStatusForGuide`
- `NotificationService::notify('guide_status', ...)`

### Destinatarios push

- `guide.sender.pobox.user`
- `guide.addressee.customer.pobox.user`

### Endpoint de disparo

- `POST /api/guide/create-status`
  - (usar el endpoint real de creacion de estado configurado en tu controlador)

## 4.2 Warehouse status

### Flujo

- `WarehouseReceiptController::createStatusForWarehouseReceiptAction`
- `WarehouseReceiptService::createStatusForWarehouseReceipt`
- `NotificationService::notify('warehouse_status', ...)`

### Destinatarios push

- `whrec.shipper.pobox.user`
- `whrec.receiver.customer.pobox.user`

### Endpoint de disparo

- `POST /api/warehouse-receipt/create-status`
  - (usar el endpoint real de creacion de estado configurado en tu controlador)

---

## 5) Reempaque procesado

### Evento interno

- `reempack_status`

### Disparadores

- `POST /api/reempack/process-shipping`
- `POST /api/reempack/process-shipping-in-entity`

### Destinatario push

- Solo `reempack.pobox.user`

No se envia directamente a shipper/receiver en este flujo.

---

## 6) Alertas recibidas por tracking

### Evento interno

- `alert_received`

### Flujo

- `AlertService::notifyTrackingReceived(...)` cuando encuentra tracking recibido.

### Destinatario push

- `alert.pobox.user`

### Disparo funcional

- Normalmente ocurre desde el procesamiento de alertas (`/api/alert/process`) o flujo interno equivalente.

---

## Checklist de QA recomendado

1. Registrar tokens de prueba:
   - Usuario SISTEMA
   - Usuario pobox de shipper
   - Usuario pobox de receiver
2. Validar canal tecnico con `POST /api/expo-token/direct-test`.
3. Probar eventos `system_users` (create alert/pickup/reempack).
4. Probar batches `receipt/guide/warehouse`.
5. Probar creacion de status en guide/warehouse.
6. Probar proceso de reempaque.
7. Revisar en respuesta:
   - `success`
   - `status` (`sent`, `partial`, `failed`, `skipped`)
   - `sent`
   - `failed`
   - `results[]`

## Nota de diagnostico comun

Si aparece `InvalidCredentials` en Expo (por ejemplo error FCM), el backend si esta enviando a Expo pero falta/caducaron credenciales push del proyecto en Expo/EAS/Firebase.