Help Desk — Sistema Multi-Tenant de Gestión de Incidencias & FSM

Sistema web SaaS modular para la gestión de tickets de soporte técnico, atención al cliente y despacho de visitas técnicas en terreno (FSM - Field Service Management), integrado con el ecosistema central de Telcotronics sobre Node.js, Express 5 y MariaDB.

🎯 ¿Qué resuelve?

Centraliza el ciclo completo de atención técnica para las organizaciones del ecosistema Telcotronics:

Recepción y Triaje Digital: Clientes y agentes registran solicitudes con prioridad y categorización por departamento.
Aislamiento Multi-Tenant (SaaS): Cada empresa u organización opera con sus propios datos, usuarios y tickets de forma completamente aislada.
Despacho y Trazabilidad de Campo (FSM): Cuando un ticket requiere atención presencial, el agente programa la visita técnica directamente hacia el sistema central tareas.telcotronics.com (CT 132), asignando a técnicos reales con checklist de tareas, coordenadas GPS y seguimiento operativo en vivo.
Mini-Timeline en Vivo & Firma Digital: Visualización de los 4 hitos operativos en el ticket: Programada ➔ Check-in GPS en sitio ➔ Avance de checklist con fotos de evidencia ➔ Cierre con firma digital del cliente.

👥 Roles de Usuario y Capacidades

Rol	Dashboard / Acceso	Capacidades Principales
Superadmin	`/saas/companies`	Alta de empresas, activación/suspensión de tenants y control de cuotas
Admin	`/admin/dashboard`	Gestión de agentes y clientes, CRUD de departamentos y configuración del tenant
Agente	`/agent/dashboard`	Bandeja de tickets, cambio de estado (`abierto`, `en_progreso`, `cerrado`), programación de visitas técnicas FSM y respuesta
Cliente	`/client/dashboard`	Apertura de tickets con prioridad y departamento, consulta de historial y respuestas

🚚 Módulo FSM (Visitas Técnicas en Terreno)

Integrado bidireccionalmente con tareas.telcotronics.com:

Programación desde el Modal: Selecciona técnicos en vivo desde el Hub (/api/external/users/list), define fecha/hora, dirección, coordenadas GPS (Lat, Lng), referencia y checklist inicial.
Seguimiento con Mini-Timeline:
1. 📅 Programada: Datos del técnico asignado, fecha/hora y dirección.
2. 📍 Check-in GPS: Hora de arribo y coordenadas validadas en sitio por el técnico.
3. 📸 Avance y Evidencias: Barra de porcentaje de checklist, galería de fotos de campo en terreno y visualización de la firma digital del cliente.
4. 🏁 Finalización: Botón 🔄 Sincronizar estado con Hub para actualizar el timeline y bitácora de eventos a demanda.
Automatización en el Hilo del Ticket:
- Al programar: el ticket pasa automáticamente a en_progreso y se publica el detalle del despacho.
- Al completarse la visita: se sella la visita como completada y se añade automáticamente una nota con el balance de tareas, observaciones del técnico y el nombre de quien firmó el acta.

🛠️ Stack Tecnológico

Backend: Node.js 20+ con Express 5.2.
Vistas: EJS 5 con partials modulares y Bootstrap 5.3 + Font Awesome 6.
Base de Datos: MariaDB / MySQL vía conector nativo mysql2/promise (192.168.10.149:3306, Contenedor CT 114).
Integración FSM: API REST externa contra tareas.telcotronics.com (CT 132 192.168.10.160:3000).
Autenticación: Sesiones del lado del servidor con express-session y contraseñas cifradas con bcryptjs.
Auditoría y Bitácora de Errores: Integración con API-SIGMA-WEBCONTROL (192.168.10.149:3005).
Inventario Central: Registrado oficialmente en el MCP de Infraestructura como Servicio ID 35.

📋 Requisitos Previos

Node.js versión 18 o superior (recomendado Node 20+).
MariaDB 10.x / MySQL 8.x con acceso a crear bases de datos y tablas.
Conectividad a la red interna Telcotronics (192.168.10.149 y 192.168.10.160).

🚀 Instalación y Puesta en Marcha

1. Clonar e instalar dependencias

git clone https://git.telcotronics.net/pablinux/help_desk.git
cd help_desk
npm install

2. Configurar variables de entorno

Crea un archivo .env en la raíz basándote en la plantilla .env.example:

PORT=3008
DB_HOST=192.168.10.149
DB_USER=helpdesk
DB_PASSWORD=tu_password_segura
DB_NAME=help_desk
SESSION_SECRET=tu_secreto_de_sesion
JWT_SECRET=tu_jwt_secret

# Integración Hub de Tareas FSM
HUB_TAREAS_URL=https://tareas.telcotronics.com/api/external
HUB_TAREAS_API_KEY=sigma_crm_test_key_123

# Bitácora Centralizada de Errores
ERROR_API_URL=https://api.siax-system.net/api/errores

3. Inicializar y migrar la Base de Datos

Crea la base de datos, tablas (incluyendo ticket_visitas), relaciones y datos semilla (empresa demo y usuarios):

node config/setup.js

4. Iniciar la Aplicación

# Modo producción
npm start

# Modo desarrollo
node app.js

Acceso en navegador: http://localhost:3008

🧪 Pruebas y Auditoría

# Verificar flujo completo de visitas técnicas contra el Hub
node scripts/test_visita_flow.js

# Consultar la bitácora centralizada de errores (API-SIGMA-WEBCONTROL)
npm run check:errors

🔑 Credenciales por Defecto (Seed)

Rol	Correo Electrónico	Contraseña
Superadmin	`super@helpdesk.com`	`123456`
Admin	`admin@helpdesk.com`	`123456`
Agente	`agent@helpdesk.com`	`123456`
Cliente	`client@helpdesk.com`	`123456`

📁 Documentación para Agentes e Infraestructura

Punto de Entrada de Agentes: agents.md
Identidad del Agente: id_agente.md
Documentación Interna del Proyecto: Carpeta .agente/
Inventario Global del Ecosistema: .agente/infraestructura.md

6.7 KiB Raw Blame History