Saltar al contenido principal

REQ-SUP-01 — Módulo de tickets para cliente y administrador (Soporte)

· 6 min de lectura
Yovany Suárez Silva
Software Engineer - FullStack Developer

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ónEntregable
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 reabrirPOST /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álogosGET /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 alcanceSincronizació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, con RECHAZADO y CANCELADO como finales alternos. El sistema valida cada transición y rechaza las que no lo son.
  • Reapertura en el mismo ticket: un ticket CERRADO solo se reabre (CERRADO → EN_PROCESO), con la acción REAPERTURA en 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_codigo y estado_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 NULL es el estado actual). La duración real se compara contra las 20 reglas de SLA por prioridad × estado para marcar SLA 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_PROCESO o RESUELTO.
  • Evidencias: imágenes del ticket o de una respuesta concreta, guardadas en uploads/tickets/ y servidas en /uploads/tickets (mismo patrón que uploads/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​

PiezaRol
database/migrations/033_create_tickets.sqlLas 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.tsPágina tickets (/tickets) + módulo 98 visible a todos los roles (web y móvil)
src/components/tickets/tickets-panel.tsxOrquestador del panel: KPIs, filtros, alta, detalle y acciones según el rol
src/components/tickets/ticket-detalle.tsxHilo con evidencias, respuesta (nota interna y cambio de estado), asignación y bloque de tiempos/SLA
src/screens/TicketsScreen.tsx / TicketDetalleScreen.tsxExperiencia cliente en el móvil (crear, ver, responder y adjuntar)

Auditoría con @AuditarAccionPrivilegiada: CREAR_TICKET, CAMBIAR_ESTADO_TICKET, ASIGNAR_TICKET y ELIMINAR_TICKET. El solicitante y el autor siempre salen del JWT: no viajan en el cuerpo.

🧪 Pruebas​

  • API: tsc EXIT 0; suite src/domains/tickets 17/17 y suite completa 129 suites / 1201 tests OK.
  • Web: tsc EXIT 0; eslint 0 errores; tickets-panel.test.tsx 3/3.
  • Móvil: tsc EXIT 0; npm test 12 suites / 103 tests OK.

Nota de entorno: 4 suites de common/backup/* del API fallan por EPERM mkdtemp en %TEMP% (limitación del entorno de Windows, ajena a este cambio).

🔧 Correcciones posteriores​

CorrecciónCausaArreglo
«Error al cargar los datos: page must not be less than 1; page must be an integer number…» al abrir la gridLos 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 filasGrid a 5 columnas como máximoGrid 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 denotabaEl 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 tarjetatext-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 dictarEl 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ónPor qué
Sincronización con nodo central multi-sedeEl 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 No aporta al flujo del almacén y añade dependencias del dispositivoSe 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​