> ## Documentation Index
> Fetch the complete documentation index at: https://wiki.vivla.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tickets

> Gestión de tickets de soporte con integración bidireccional con Zendesk, en transición a Vivla Tools como herramienta principal

# 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.

<Note>
  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.
</Note>

## 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](/tickets/sync).

## Superficies

El módulo se expone en dos lugares:

| Superficie        | Ruta                | Uso                                                |
| ----------------- | ------------------- | -------------------------------------------------- |
| **Tool dedicada** | `/app/tickets`      | Herramienta top-level: dashboard + lista + detalle |
| **Chat-embed**    | `/app/chat/tickets` | Tickets 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`).

<Note>
  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.
</Note>

## 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**.

<Note>
  "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](/tickets/fields).
</Note>

## Funcionalidades

<CardGroup cols={2}>
  <Card title="Campos y formulario" href="/tickets/fields">
    Campos nativos, desplegables (fuente de verdad en Tools), mapeo con Zendesk
    y automatizaciones (casa→destino, pagador auto, estado de reparación).
  </Card>

  <Card title="Adjuntos" href="/tickets/attachments">
    Archivos a nivel ticket (fotos + PDFs) en Cloudinary, con write-back a
    Zendesk y re-alojado de imágenes de chat.
  </Card>

  <Card title="Dashboard y SLAs" href="/tickets/dashboard">
    KPIs, cumplimiento de SLA por prioridad, cohortes de antigüedad, tipos de
    ticket (Casa/Experiencia/Administrativo/Dormido) y FCR.
  </Card>

  <Card title="Actividad e IA" href="/tickets/activity">
    Audit log (quién creó/cambió qué), soft-delete de inválidos y planes de
    mejora generados con IA.
  </Card>

  <Card title="Sincronización Zendesk" href="/tickets/sync">
    Import, webhook, comentarios y los CLIs de backfill (históricos, comentarios,
    historial, equipos por IA).
  </Card>
</CardGroup>

## Modelo de datos

| Tabla                        | Descripción                                                                                                                                                    |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chat_tickets`               | Ticket: campos nativos (incl. `ticket_kind`) + columnas derivadas (resolved\_at, reopened\_count) + soft-delete (invalid) + rango de coste + plan de mejora IA |
| `chat_ticket_comments`       | Comentarios (importados de Zendesk + creados en Tools)                                                                                                         |
| `chat_ticket_attachments`    | Adjuntos a nivel ticket alojados en Cloudinary (Fase I)                                                                                                        |
| `chat_ticket_status_history` | Historial/actividad append-only: transiciones y cambios de campo con actor                                                                                     |
| `chat_ticket_messages`       | Mensajes 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/`.