Skip to main content

​
Tickets

El módulo de Tickets es el sistema de gestión de incidencias de soporte de Vivla (propiedades, experiencia del cliente, administrativo). Nació como un espejo de Zendesk y está en transición para que Vivla Tools sea la herramienta principal, manteniendo sincronización con Zendesk mientras ambos conviven.
Operativamente lo usa el equipo de CX. Cada cambio de campo, adjunto o comentario hecho en Vivla Tools se sincroniza de vuelta a Zendesk (write-back) para no perder información durante la transición.

​
Arquitectura

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Frontend   │────▶│   Backend    │◀───▶│    Zendesk   │
│ (TanStack)   │◀────│  (NestJS)    │     │ (import+wh)  │
└──────────────┘     └──────┬───────┘     └──────────────┘
                            │
              ┌─────────────┼─────────────┐
              ▼             ▼             ▼
       ┌───────────┐ ┌───────────┐ ┌───────────┐
       │ Supabase  │ │ Cloudinary│ │ Claude AI │
       │ (tickets) │ │ (adjuntos)│ │ (mejoras) │
       └───────────┘ └───────────┘ └───────────┘
  • Fuente de verdad: Vivla Tools gobierna las opciones de los desplegables (config en código) y aloja los adjuntos en su propio Cloudinary. Zendesk sigue como inbound (import + webhook) y recibe el write-back durante la transición.
  • Sincronización: import diario (vía Windmill) + webhook en tiempo real. Ver Sincronización.

​
Superficies

El módulo se expone en dos lugares:
SuperficieRutaUso
Tool dedicada/app/ticketsHerramienta top-level: dashboard + lista + detalle
Chat-embed/app/chat/ticketsTickets embebidos dentro del módulo de Chat
Cada una tiene su layout (TicketsToolLayout / EmbeddedTicketsLayout) con sub-navegación a Panel (dashboard) y Tickets (lista), y el detalle del ticket (/.../list/$ticketId).
El ticket se gestiona por completo desde el detalle: la sección Gestión permite cambiar estado (incluido darlo por finalizado), prioridad, tipo (incidencia | propuesta de mejora) y asignación con guardado inmediato al seleccionar, y también se editan título, descripción, routing, reparación, notas y fechas.

​
Tipo de ticket (ticket_kind)

Cada ticket tiene una naturaleza persistida en la columna ticket_kind:
  • Incidencia (incident, default): el ticket de soporte estándar.
  • Propuesta de mejora (improvement_proposal): una idea de mejora para la casa, no una incidencia.
Es una dimensión propia, separada del estado (lifecycle) y del Segmento derivado de SLA (casa/experiencia/administrativo/dormido). Desde Tools se puede crear un ticket eligiendo el tipo (CX puede levantar propuestas) y filtrar la lista por tipo. Las propuestas de mejora son Tools-native: se crean también desde el portal de Home Excellence y nunca se envían a Zendesk.
“Propuesta de mejora” fue en su día un estado falso del status; ahora es su propia dimensión (ticket_kind). Ver la transición two-phase.

​
Funcionalidades

Campos y formulario

Campos nativos, desplegables (fuente de verdad en Tools), mapeo con Zendesk y automatizaciones (casa→destino, pagador auto, estado de reparación).

Adjuntos

Archivos a nivel ticket (fotos + PDFs) en Cloudinary, con write-back a Zendesk y re-alojado de imágenes de chat.

Dashboard y SLAs

KPIs, cumplimiento de SLA por prioridad, cohortes de antigüedad, tipos de ticket (Casa/Experiencia/Administrativo/Dormido) y FCR.

Actividad e IA

Audit log (quién creó/cambió qué), soft-delete de inválidos y planes de mejora generados con IA.

Sincronización Zendesk

Import, webhook, comentarios y los CLIs de backfill (históricos, comentarios, historial, equipos por IA).

​
Modelo de datos

TablaDescripción
chat_ticketsTicket: campos nativos (incl. ticket_kind) + columnas derivadas (resolved_at, reopened_count) + soft-delete (invalid) + rango de coste + plan de mejora IA
chat_ticket_commentsComentarios (importados de Zendesk + creados en Tools)
chat_ticket_attachmentsAdjuntos a nivel ticket alojados en Cloudinary (Fase I)
chat_ticket_status_historyHistorial/actividad append-only: transiciones y cambios de campo con actor
chat_ticket_messagesMensajes de chat asociados al ticket

​
Backend

apps/backend/src/chat/tickets/
├── tickets.controller.ts          # endpoints REST
├── tickets.service.ts             # lógica principal
├── ticket-comments.{service,controller}.ts
├── ticket-attachments.{service,controller}.ts
├── config/
│   ├── sla.config.ts              # SLAs, tipos de ticket, dormido
│   ├── ticket-options.config.ts   # opciones de desplegables (fuente de verdad)
│   ├── payer-rules.config.ts      # pagador automático por equipo
│   └── location-destination.config.ts  # casa→destino
└── entities/                      # entidades + mapeos
La integración con Zendesk vive en apps/backend/src/chat/integrations/ticketing/.