Inbox

El modulo de Inbox gestiona la bandeja de entrada de cada usuario: mensajes internos, notificaciones push (mobile y browser), y preferencias de notificacion. Es el punto central donde convergen alertas de todos los modulos.

Arquitectura

┌──────────────────┐     ┌──────────────────┐     ┌──────────────┐
│  Chat Module     │────▶│  InboxService    │────▶│  Supabase    │
│  Community       │     │                  │     │  inbox_messages│
│  Notifications   │     │  InboxPushNotif. │     └──────────────┘
│  AI              │     │  Service         │
│  System          │     └──────────────────┘
└──────────────────┘            │
                         ┌──────────────┐
                         │  Expo / Web  │
                         │  Push        │
                         └──────────────┘

Tipos de mensaje

Tipo	Source Tool	Descripcion
`chat_unread`	chat	Mensajes no leidos en canal
`chat_booking_create`	chat	Nueva reserva creada
`chat_booking_archive`	chat	Reserva archivada
`chat_shift_created`	chat	Turno creado
`chat_shift_assigned`	chat	Turno asignado
`chat_shift_started`	chat	Turno iniciado
`chat_shift_ended`	chat	Turno finalizado
`chat_property_assigned`	chat	Propiedad asignada
`chat_ticket_created`	chat	Ticket creado
`chat_ticket_updated`	chat	Ticket actualizado
`chat_ticket_assigned`	chat	Ticket asignado
`chat_ticket_resolved`	chat	Ticket resuelto
`restock_alert`	community	Alerta de reposicion
`guide_incomplete`	community	Guia incompleta
`guide_request`	community	Solicitud de guia
`notification_sent`	notifications	Notificacion enviada
`notification_failed`	notifications	Fallo de notificacion
`ai_daily_summary`	ai	Resumen diario IA
`ai_weekly_summary`	ai	Resumen semanal IA
`general`	system	Mensaje general

Prioridades

Prioridad	Comportamiento
`low`	Solo inbox, sin push
`normal`	Inbox + push si habilitado
`high`	Inbox + push (respeta quiet hours)
`urgent`	Inbox + push (ignora quiet hours)

Estados

unread → read → resolved → archived Soft delete con campo deleted_at.

API Endpoints

Metodo	Endpoint	Auth	Descripcion
POST	`/inbox/messages`	Bearer / API Key	Crear mensaje (integracion externa)
GET	`/inbox/messages`	Bearer	Listar mensajes del usuario con filtros
GET	`/inbox/unread-count`	Bearer	Conteo desglosado por prioridad/tipo/tool
GET	`/inbox/messages/:id`	Bearer	Detalle de mensaje
PATCH	`/inbox/messages/:id`	Bearer	Actualizar estado/notas
PATCH	`/inbox/messages/:id/read`	Bearer	Marcar como leido
POST	`/inbox/messages/batch-read`	Bearer	Marcar multiples como leidos
PATCH	`/inbox/messages/:id/resolve`	Bearer	Marcar como resuelto
DELETE	`/inbox/messages/:id`	Bearer	Eliminar (soft delete)
POST	`/inbox/push-subscription`	Bearer	Registrar suscripcion push browser
DELETE	`/inbox/push-subscription`	Bearer	Desregistrar suscripcion push
GET	`/inbox/vapid-public-key`	Bearer	Obtener clave publica VAPID
GET	`/inbox/preferences`	Bearer	Obtener preferencias de notificacion
PATCH	`/inbox/preferences`	Bearer	Actualizar preferencias

Filtros

Los endpoints de listado aceptan:

sourceTool — filtrar por herramienta origen (chat, community, notifications, system, ai)
messageTypes — array de tipos de mensaje
priority — filtrar por prioridad
status — filtrar por estado

Preferencias de usuario

Cada usuario puede configurar:

Campo	Tipo	Descripcion
`pushEnabled`	boolean	Activar push notifications
`pushUrgentOnly`	boolean	Solo push para urgentes
`pushCommunity`	boolean	Push de community
`pushChat`	boolean	Push de chat
`pushTickets`	boolean	Push de tickets
`pushShifts`	boolean	Push de turnos
`pushAi`	boolean	Push de IA
`emailEnabled`	boolean	Activar emails
`emailDigestFrequency`	string	Frecuencia de digest
`quietHoursEnabled`	boolean	Horas silenciosas
`quietHoursTimezone`	string	Timezone para quiet hours

Push Notifications

El inbox soporta dos canales de push:

Expo Push — para vivla-mobile (iOS/Android)
Web Push — para el panel web via VAPID/service worker

Las notificaciones respetan las preferencias del usuario y las horas silenciosas (excepto prioridad urgent).

Helpers del servicio

InboxService expone metodos helper para crear mensajes tipados desde otros modulos:

createChatBookingCreateMessage() — notificacion de reserva
createChatTicketCreatedMessage() — nuevo ticket
createChatTicketAssignedMessage() — ticket asignado
createChatShiftCreatedMessage() — turno creado
createChatPropertyAssignedMessage() — propiedad asignada
createGuideIncompleteMessage() — guia incompleta
createAIDailySummaryMessage() — resumen IA diario

Tickets via Automation Engine (`ticket.*`)

Los avisos de ticket no pasan por los helpers createChatTicket*Message() de arriba (ese camino ad-hoc se retiro con VIV-2081) — llegan al buzón vía el motor de notificaciones (apps/backend/src/notifications/engine/), que escribe directamente en inbox_messages cuando el flow tiene una accion con canal tools_inbox. En este camino las filas quedan con message_type: 'automation' y source_tool: 'notifications'; el tipo de evento real vive en metadata.event_type. Eventos emitidos por ticket-events-emitter.service.ts (uno por transicion, nunca dos para el mismo cambio logico):

`metadata.event_type`	Cuando dispara
`ticket.created`	Se crea el ticket ya asignado
`ticket.updated`	Cambia un campo auditable (`field` en el payload)
`ticket.assigned`	Cambia el asignado
`ticket.resolved`	El status entra en un estado resuelto (`resolved`/`closed`), sustituye al `ticket.updated` de `field=status` para esa transicion. Un reopen (resuelto → abierto) sigue saliendo como `ticket.updated`
`ticket.comment_added`	Nuevo comentario (Tools o respuesta de agente en Zendesk)

Flows + plantillas: 171_seed_ticket_notification_flows.sql (created, updated, assigned, comment_added) y 178_seed_ticket_resolved_notification_flow.sql (resolved). Todos avisan a creador + asignado por tools_inbox + email, excluyendo al actor del cambio y deduplicando cuando creador == asignado (skipIfTargetEquals).

Metadata enriquecida para la card del buzón

Para que la card del sidebar (TicketMessageCard, en apps/frontend/app/components/inbox/) se pinte sin un fetch adicional a getTicket, el motor añade un bloque metadata.ticket solo para eventos ticket.* (aditivo — no toca el shape de metadata de otros flows):

{
  "deep_link_id": null,
  "template_id": "...",
  "event_type": "ticket.resolved",
  "aggregate_id": "<ticketId>",
  "ticket": {
    "ticketId": "<ticketId>",
    "title": "Grifo roto",
    "status": "resolved",
    "priority": "high",
    "ticketKind": "incident",
    "propertyName": "Casa Sol",
    "assigneeName": "Ana Agente"
  }
}

Todos los campos de metadata.ticket son best-effort (la resolucion de contexto en el emitter puede fallar en un miss puntual) — el frontend degrada campo a campo en vez de todo-o-nada. message.deepLink es siempre null para estos mensajes; el link se construye en el cliente como /app/tickets/list/{ticketId} a partir de metadata.aggregate_id.

Estructura de modulo

apps/backend/src/inbox/
  inbox.module.ts
  inbox.controller.ts
  inbox.service.ts
  inbox-push-notification.service.ts
  dto/
    create-message.dto.ts
    update-message.dto.ts
    inbox-filters.dto.ts
    preferences.dto.ts

Overview

Chat

Tickets

Encuestas

Community

Guías de mantenimiento

Notificaciones

Tools API

Plataforma

Integraciones

Inbox

Inbox

Arquitectura

Tipos de mensaje

Prioridades

Estados

API Endpoints

Filtros

Preferencias de usuario

Push Notifications

Helpers del servicio

Tickets via Automation Engine (`ticket.*`)

Metadata enriquecida para la card del buzón

Estructura de modulo

​Inbox

​Arquitectura

​Tipos de mensaje

​Prioridades

​Estados

​API Endpoints

​Filtros

​Preferencias de usuario

​Push Notifications

​Helpers del servicio

​Tickets via Automation Engine (ticket.*)

​Metadata enriquecida para la card del buzón

​Estructura de modulo

Inbox

Arquitectura

Tipos de mensaje

Prioridades

Estados

API Endpoints

Filtros

Preferencias de usuario

Push Notifications

Helpers del servicio

Tickets via Automation Engine (`ticket.*`)

Metadata enriquecida para la card del buzón

Estructura de modulo