Este es un sistema moderno de tickets de soporte y mesa de servicio diseñado para ejecutarse sobre la infraestructura global de Cloudflare Workers, utilizando Durable Objects (SQL API) como base de datos relacional (SQLite) y sincronización en tiempo real mediante WebSockets.
- Base de datos SQLite en el Edge: Datos persistentes y consultas SQL rápidas usando la API SQL nativa de Cloudflare Durable Objects.
- Tiempo Real: Sincronización instantánea de tickets, comentarios, bitácora y métricas entre clientes mediante WebSockets.
- Portal Público y Privado: Permite a usuarios invitados crear y consultar tickets por número único, y al staff (agentes y administradores) gestionar los casos desde una vista privada.
- Configuración Global en Tiempo Real:
- Huso Horario Centralizado: El administrador puede cambiar la zona horaria del sistema, actualizando instantáneamente la presentación de todas las fechas y horas para todos los usuarios activos.
- Temas Dinámicos del Sistema: 4 temas visuales premium (Classic Slate, Esmeralda, Rosa/Crimson, Ámbar/Oro) aplicables en caliente a nivel global por el administrador.
- Sincronización sin Recarga: Los cambios de tema y huso horario se propagan al instante a todos los usuarios conectados sin necesidad de recargar el navegador.
- Flujos de Trabajo Interactivos (Wizard de Asignación y Delegación):
- Al hacer clic en "Tomar Caso" en la bandeja o en el panel de detalles, se abre un modal interactivo para definir el Tiempo Estimado de Solución y la Prioridad del ticket.
- Delegación de Casos (Solo Administrador): Los administradores tienen un campo adicional en este modal para asignar directamente el ticket a cualquier miembro del staff técnico, estando ellos mismos pre-seleccionados por defecto.
- Imágenes de Evidencia y Visor Lightbox:
- Permite subir hasta 3 imágenes de evidencia al crear un reporte, en el chat del cliente y en la bitácora técnica de técnicos.
- Compresión en Cliente: Las imágenes se escalan a un máximo de 1000px y se comprimen a JPEG al 70% de calidad en el navegador usando Canvas API para no sobrecargar los límites de SQLite en Durable Objects.
- Visor Lightbox Integrado: Permite ampliar cualquier imagen adjunta a pantalla completa con fondo desenfocado y descargar el archivo original.
- Restricción de Estado en Tickets No Asignados:
- Se prohíbe cambiar el estado de un ticket si no cuenta con un técnico asignado.
- La interfaz oculta el selector de estado (mostrando una insignia de sólo lectura) en la bandeja y detalles del ticket si no está asignado. El backend rechaza cualquier actualización de estado no válida con un error
400 Bad Request.
- Precisión de Fecha y Zona Horaria:
- Se corrigió el desfase de zona horaria mediante un analizador de fechas UTC SQLite en el cliente (
parseSqliteDate), garantizando que la configuración horaria del sistema (ej. Hora Central) se aplique y presente con total exactitud.
- Se corrigió el desfase de zona horaria mediante un analizador de fechas UTC SQLite en el cliente (
- Detalle de Ticket Optimizados y Escalamiento:
- Si un ticket está Sin asignar, el drawer muestra un botón destacado de "Tomar Caso" para autoasignación, en lugar del selector abierto de técnicos.
- Si el ticket ya cuenta con un técnico asignado, la etiqueta cambia a "Escalar a:", mostrando un desplegable para reasignar o escalar el ticket a otro compañero.
- Métricas Interactivas y Desglose de Resumen (Desempeño del Soporte):
- Las tarjetas del Panel de Control de Soporte (
Total,Pendientes,SLA Vencido,Resueltos,T. RespuestayT. Resolución) ahora son completamente clickeables e interactivas, con efectos hover y active fluidos. - Al presionarlas, abren un modal que detalla la lógica de cálculo/fórmula aplicada e incluye una tabla resumen con los últimos 20 tickets más recientes asociados a esa métrica para un diagnóstico rápido y directo.
- Al hacer clic en cualquier fila de ticket dentro del modal, este se cierra de inmediato y abre el panel lateral de detalles de dicho ticket.
- Cuenta con un aviso explícito en el pie de la tabla indicando la restricción a 20 elementos para mantener un rendimiento DOM excelente en el navegador.
- Las tarjetas del Panel de Control de Soporte (
- Indicador Personalizado de Carga de Trabajo (Badge del Sidebar):
- El badge numérico al lado del botón "Tickets" en la barra lateral ahora muestra únicamente los tickets activos/pendientes asignados al usuario activo (o los creados por el cliente si es un solicitante).
- Se oculta automáticamente si la cuenta es 0 para un diseño limpio, y se actualiza en tiempo real de forma inmediata mediante WebSockets ante cualquier cambio de estado o asignación.
- Prevención de "Usuarios Fantasma":
- La creación de tickets públicos por invitados que no han iniciado sesión no crea registros de usuarios ficticios en la base de datos si el correo no está registrado. La información se guarda directamente en columnas dedicadas en el ticket (
guest_nombre,guest_email,guest_area) y se presenta de forma unificada en todo el sistema.
- La creación de tickets públicos por invitados que no han iniciado sesión no crea registros de usuarios ficticios en la base de datos si el correo no está registrado. La información se guarda directamente en columnas dedicadas en el ticket (
- Diseño Totalmente Responsivo:
- Menú lateral (sidebar) colapsable en móviles mediante botón de hamburguesa y fondo traslúcido.
- Bandeja híbrida: se convierte de tabla estructurada a tarjetas verticales independientes en móviles para facilitar el uso en celulares.
- Altura ajustable con scroll vertical interno en modales y prevención de desbordamientos en campos de entrada y bitácora técnica.
- Eliminación y Bitácora de Auditoría:
- Historial detallado de transacciones por ticket y capacidad para que los administradores eliminen tickets de forma definitiva con borrado en cascada de dependencias.
- Funcionamiento y Combinación de Filtros en la Bandeja:
El personal técnico dispone de dos filtros principales y un buscador en tiempo real en la bandeja de entrada. La combinación de estos filtros en el servidor permite obtener vistas específicas de trabajo:
- Filtro de Asignación (Técnicos):
- Mis asignados y libres (Predeterminado): Muestra los tickets asignados al usuario logueado más los que están libres (sin asignar). Diseñado para la rutina diaria de un agente.
- Todos los técnicos: Muestra los tickets de todo el personal de soporte sin importar a quién pertenezcan.
- Solo mis asignados: Muestra de forma exclusiva los tickets bajo responsabilidad directa del usuario activo.
- Solo sin asignar: Filtra únicamente los tickets huérfanos que requieren ser tomados o delegados.
- Filtro de Estado:
- Pendientes (No resueltos) (Predeterminado): Oculta los casos cerrados y muestra solo lo activo (
Nuevo,Abierto,En Progreso,En Espera). - Todos los estados: Muestra el historial completo de tickets sin excluir los cerrados.
- Estados específicos (
Nuevo,Abierto,En Progreso,En Espera,Resuelto): Muestra únicamente los casos en ese estado particular.
- Pendientes (No resueltos) (Predeterminado): Oculta los casos cerrados y muestra solo lo activo (
- Combinaciones de Uso Comunes:
- Solo sin asignar + Nuevo (Bandeja de Entrada): Ideal para que los técnicos o administradores identifiquen los reportes recién levantados por los usuarios y procedan a asignarlos o tomarlos.
- Solo mis asignados + En Progreso (Trabajo Activo): Muestra los tickets en los que el técnico está trabajando activamente en su jornada.
- Todos los técnicos + Pendientes (Supervisión Global): Permite a los administradores evaluar el volumen de trabajo pendiente en toda la organización.
- Todos los técnicos + Resuelto (Historial de Auditoría): Permite consultar de forma masiva el histórico de tickets cerrados.
- Filtro de Asignación (Técnicos):
Antes de comenzar, asegúrate de tener instalado:
- Node.js (Versión 18 o superior recomendada).
- NPM (Incluido con Node.js).
- Cuenta de Cloudflare: Para producción, una cuenta gratuita (Workers Free) es suficiente ya que el proyecto utiliza la arquitectura SQLite de Durable Objects (
new_sqlite_classes).
worker.js: Código del backend. Contiene la lógica del Cloudflare Worker y la claseHelpdeskHub(Durable Object) que gestiona la base de datos SQLite y los WebSockets.public/index.html: Interfaz de usuario (frontend) interactiva y responsiva creada con HTML5, JavaScript (Vanilla) y Tailwind CSS.wrangler.toml: Configuración de wrangler para Cloudflare, incluyendo las migraciones de base de datos y bindings de Durable Objects.
Asegúrate de estar en el directorio raíz del proyecto:
cd /home/carlos/Escritorio/HelpdeskPuedes iniciar el entorno de desarrollo simulando la red de Cloudflare en tu máquina local ejecutando:
npx wrangler devEsto iniciará un servidor local (usualmente en http://127.0.0.1:8787). Las migraciones de base de datos SQL se ejecutarán automáticamente en la persistencia local.
El sistema siembra automáticamente un usuario administrador en la primera ejecución:
- Usuario:
admin - Contraseña:
admin(Nota: Al iniciar sesión por primera vez, el sistema obligará a cambiar la contraseña predeterminada por razones de seguridad. Este usuario semilla solo se volverá a crear si no existe ningún otro usuario con rol de administrador en el sistema).
- Administrador (
admin):- Control total del sistema y acceso a la pestaña "Configuración Sistema".
- Gestión de usuarios mediante Baja/Inactivación lógica (inhabilita el inicio de sesión y asignaciones, pero mantiene el nombre del usuario en el historial y folios antiguos) y Eliminación Permanente (borrado definitivo de la base de datos para usuarios previamente inactivos).
- Creación y eliminación de categorías de tickets.
- Asignación libre de técnicos, cambio de prioridad y eliminación definitiva de tickets (con borrado en cascada de comentarios, transacciones e historial).
- Agente (
agente):- Gestión de tickets asignados o libres: cambiar estados, prioridades, asignar tiempos de respuesta estimados y autoasignarse casos.
- Visualización del dashboard de métricas.
- Escribir comentarios públicos y notas internas de bitácora técnica.
- Solicitante (
solicitante):- Creación de tickets de soporte desde su portal.
- Consulta del historial y chat exclusivo del ticket creado por él.
Para subir el proyecto a la red de Cloudflare y tenerlo disponible en internet:
Ejecuta el siguiente comando para autenticarte con tu cuenta de Cloudflare en tu terminal:
npx wrangler loginSigue las instrucciones en el navegador para otorgar los permisos de wrangler.
Una vez autenticado, publica tu aplicación ejecutando:
npx wrangler deployEl comando compilará el código, aplicará las migraciones de base de datos en la nube y te proporcionará una URL pública (ejemplo: https://mesa-de-servicio.<tu-subdominio>.workers.dev).
Para mayor seguridad y prevención de spam o ataques de fuerza bruta, el sistema cuenta con integración nativa con Cloudflare Turnstile. El captcha se activa automáticamente en los siguientes escenarios:
- Creación de Tickets Públicos: Se requiere siempre resolver el captcha para enviar un ticket como invitado (sin iniciar sesión).
- Inicio de Sesión (Login): Si se intenta iniciar sesión incorrectamente desde una IP o cuenta de usuario más de una vez (a partir del segundo intento), se activa obligatoriamente la resolución del captcha para el siguiente intento.
- Consulta de Tickets Públicos: Se requiere siempre resolver el captcha para buscar y visualizar un ticket público por su código único (
TK-XXXXXX), previniendo que bots rastreen o escaneen folios.
- Ve a la consola de administración de Cloudflare Turnstile.
- Registra un nuevo sitio web y obtén:
- Llave del Sitio (Site Key / Pública)
- Llave Secreta (Secret Key / Privada)
- Para no guardar tus llaves reales en el código (Recomendado para GitHub):
- En desarrollo local: Crea un archivo
.dev.varsen la raíz del proyecto (este archivo ya está configurado en.gitignorepara no ser subido a Git) y añade tus llaves:TURNSTILE_SITE_KEY="tu_site_key_aqui" TURNSTILE_SECRET_KEY="tu_secret_key_aqui"
- En producción:
- Guarda la llave secreta en Cloudflare ejecutando en tu terminal:
npx wrangler secret put TURNSTILE_SECRET_KEY
- Configura la llave de sitio (pública) en el panel de Cloudflare (Configuración del Worker -> Variables -> Variables de entorno), agregándola como tipo "Texto" (Text) con el nombre TURNSTILE_SITE_KEY y el valor de tu llave pública, o colócala bajo la sección
[vars]en tuwrangler.toml.
- Guarda la llave secreta en Cloudflare ejecutando en tu terminal:
- En desarrollo local: Crea un archivo
- Método alternativo (Hardcoded en código):
Puedes abrir el archivo worker.js y colocar directamente tus llaves en las constantes
TURNSTILE_SITE_KEYyTURNSTILE_SECRET_KEYen la parte superior del archivo.
Note
Modo sin configuración (Bypass): Si dejas las constantes con sus valores por defecto ("TU_LLAVE_...") y no defines variables de entorno ni archivo .dev.vars, el backend omitirá automáticamente la validación del captcha e imprimirá una advertencia en la consola, permitiendo realizar pruebas locales de los flujos de login y tickets públicos sin necesidad de registrar un dominio en Cloudflare.