REQ-SUP-01 — Módulo de tickets para cliente y administrador (Soporte)
Implementación del requerimiento REQ-SUP-01 (Módulo de tickets para cliente y administrador), dentro de Soporte y con prioridad Media. El almacén no tenía un canal formal para reportar fallos, pedir mejoras o resolver dudas: los reportes llegaban por WhatsApp, llamada o de viva voz, sin responsable ni trazabilidad.
El módulo replica el esquema TICK de Surosv4 (módulo SurosTick) adaptado a PostgreSQL, y
conserva la misma máquina de estados, los mismos códigos de catálogo y las mismas 20 reglas
de SLA del origen.
📋 Alcance
| Criterio de aceptación | Entregable |
|---|---|
Réplica del esquema TICK (9 tablas) | 10 tablas en PostgreSQL: 4 catálogos, 5 operativas/configuración y ticket_evidencias |
| Cliente: crear, listar solo los suyos, detalle + hilo, responder, evidencias, estado/SLA y reabrir | POST /api/tickets, GET /api/tickets, GET /api/tickets/:id, POST /api/tickets/:id/respuestas, POST /api/tickets/:id/evidencias y PATCH /api/tickets/:id/estado (CERRADO → EN_PROCESO) |
| Administrador: ver y filtrar todos, KPIs, asignar, responder (con nota interna), cambiar estado, cerrar/reaperturar, post-atención y catálogos | GET /api/tickets (filtros), GET /api/tickets/kpis, PATCH /api/tickets/:id/asignacion, POST /api/tickets/:id/evidencias, PATCH /api/tickets/:id/estado, GET /api/tickets/catalogos |
| Fuera de alcance | Sincronización con nodo central multi-sede y WhatsApp (notificación/chat bidireccional) |
⚙️ Cómo funciona
- Máquina de estados idéntica al origen:
NUEVO → ASIGNADO → EN_PROCESO ⇄ ESPERA_USUARIO → RESUELTO → CERRADO, conRECHAZADOyCANCELADOcomo finales alternos. El sistema valida cada transición y rechaza las que no lo son. - Reapertura en el mismo ticket: un ticket
CERRADOsolo se reabre (CERRADO → EN_PROCESO), con la acciónREAPERTURAen la trazabilidad. Es la única acción de estado que puede hacer el cliente sobre su ticket. - Catálogos por código natural: el ticket guarda
area_codigo,tipo_codigo,prioridad_codigoyestado_codigo, y las FK apuntan a esas claves, exactamente como en SQL Server. - Tiempos y SLA: cada cambio de estado cierra el periodo abierto y abre uno nuevo (el de fin
NULLes el estado actual). La duración real se compara contra las 20 reglas de SLA por prioridad × estado para marcarSLA excedido. - Post-atención: documenta una atención ya prestada por un canal informal (WhatsApp, llamada,
presencial, correo u otro) con fecha real de atención, que pasa a ser el origen de los tiempos y
del SLA. Solo lo registra un administrador y nace en
EN_PROCESOoRESUELTO. - Evidencias: imágenes del ticket o de una respuesta concreta, guardadas en
uploads/tickets/y servidas en/uploads/tickets(mismo patrón queuploads/productos). - Notificaciones reutilizadas: al crear un ticket se avisa a los administradores activos; al
responder o cambiar estado se avisa a la contraparte (solicitante o asignado) por el dominio
notifications+ socket.
🧩 Detalles de implementación
| Pieza | Rol |
|---|---|
database/migrations/033_create_tickets.sql | Las 10 tablas, constraints, índices, COMMENT y semillas (catálogos + 20 reglas de SLA); idempotente |
domains/tickets/ | Servicio, controlador, tipos/máquina de estados, DTOs, entidades y specs |
src/database/migrations/045-crear-menu-tickets.ts | Página tickets (/tickets) + módulo 98 visible a todos los roles (web y móvil) |
src/components/tickets/tickets-panel.tsx | Orquestador del panel: KPIs, filtros, alta, detalle y acciones según el rol |
src/components/tickets/ticket-detalle.tsx | Hilo con evidencias, respuesta (nota interna y cambio de estado), asignación y bloque de tiempos/SLA |
src/screens/TicketsScreen.tsx / TicketDetalleScreen.tsx | Experiencia cliente en el móvil (crear, ver, responder y adjuntar) |
Auditoría con
@AuditarAccionPrivilegiada:CREAR_TICKET,CAMBIAR_ESTADO_TICKET,ASIGNAR_TICKETyELIMINAR_TICKET. El solicitante y el autor siempre salen del JWT: no viajan en el cuerpo.
🧪 Pruebas
- API:
tscEXIT 0; suitesrc/domains/tickets17/17 y suite completa 129 suites / 1201 tests OK. - Web:
tscEXIT 0;eslint0 errores;tickets-panel.test.tsx3/3. - Móvil:
tscEXIT 0;npm test12 suites / 103 tests OK.
Nota de entorno: 4 suites de
common/backup/*del API fallan porEPERM mkdtempen%TEMP%(limitación del entorno de Windows, ajena a este cambio).
🔧 Correcciones posteriores
| Corrección | Causa | Arreglo |
|---|---|---|
| «Error al cargar los datos: page must not be less than 1; page must be an integer number…» al abrir la grid | Los parámetros de la query llegan como texto y QueryTicketsDto no declaraba la conversión de tipo (PaginationDto sí lo hace). El pipe global usa transform: true pero sin enableImplicitConversion | @Type(() => Number) en page/limit y @Transform a booleano en soloMios/slaExcedido/soloPostAtencion. Spec nuevo tickets.dto.spec.ts que lo fija |
| Las 9 tarjetas de indicadores ocupaban varias filas | Grid a 5 columnas como máximo | Grid grid-cols-2 → sm:4 → md:6 → lg:9 con tarjetas compactas (icono h-3.5, etiqueta text-[10px] y valor text-base apilados): las 9 caben en una sola fila desde 1024 px |
| Los selects del alta de ticket centraban el texto y su borde no se denotaba | El disparador de Radix es un <button> (el UA stylesheet lo centra) y el token --select-border era casi blanco (0 0% 89.8%) sobre la tarjeta | text-left en SelectTrigger + text-align: left para [role="combobox"], y token a gris visible (0 0% 70% claro / 217 33% 42% oscuro). Cambio general para todos los selects, fijado en req-dsg-02-borde-select.test.tsx |
| El alta de ticket no permitía dictar | El dictado existía solo en «Ideas y novedades» y «Contacto con el desarrollador» | Se reutiliza el mismo CampoVoz (título, descripción y caja de respuesta); fijado en tickets-dictado-voz.test.tsx |
🚫 Fuera de alcance en el almacén
| Exclusión | Por qué |
|---|---|
| Sincronización con nodo central multi-sede | El almacén es una instalación única (una sede, un cliente): no hay nodo central con el que reconciliar |
| WhatsApp (notificación y chat bidireccional) | El canal de soporte es el propio módulo; el canal informal sí se documenta en el post-atención, pero sin chat ni notificación por WhatsApp |
| Dictado por voz | Se replica reutilizando el campo con micrófono ya existente (CampoVoz + useDictadoVoz): título, descripción y respuesta del ticket. Web Speech API del navegador, sin dependencias nuevas ni audio al servidor |
📚 Documentación
- Spec: REQ-SUP-01: Módulo de tickets para cliente y administrador (Soporte)
- Manual: Tickets de soporte
- Framework:
ccf-almacen-framework/DOMINIOS/SOPORTE.md
