help_desk/README.md

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:

1. Recepción y Triaje Digital: Clientes y agentes registran solicitudes con prioridad y categorización por departamento.
2. Aislamiento Multi-Tenant (SaaS): Cada empresa u organización opera con sus propios datos, usuarios y tickets de forma completamente aislada.
3. 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.
4. 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

---

🚀 Despliegue a Producción & Orquestación con SIAX Monitor

El proyecto está preparado para desplegarse de manera automatizada conforme a las reglas del Ecosistema Telcotronics y el orquestador SIAX Monitor:

• Servidor de Producción: server-webapps (CT 132 192.168.10.160, puerto 3008).
• Dominio Público Oficial: https://soporte.sigmac.app (Proxy reverso en Servidor-web CT 109 192.168.10.109).
• Gestor de Procesos: Unidad systemd siax-app-HELPDESK.service, administrada por SIAX Monitor (http://192.168.10.160:8080).
• Ficha MCP de Infraestructura: ID 35 (category: application, type: webapp, status: ACTIVE).

Pasos para Desplegar:

1. Configurar servidores de destino:

   cp servers.conf.example servers.conf
   # servers.conf nunca se commitea en Git
   

2. Ejecutar el script de despliegue:

   ./desplegar.sh
   

   El script realiza:

   • Sincronización atómica de código vía rsync hacia user_apps@192.168.10.160:/home/user_apps/apps/help_desk.
   • Instalación remota de dependencias de producción y validación de migraciones MariaDB (node config/setup.js).
   • Reinicio sin contraseña interactiva vía API de SIAX Monitor (POST http://192.168.10.160:8080/api/apps/HELPDESK/restart).
   • Verificación de PID, memoria y socket TCP en LISTEN.
   • Sincronización automática de estado ACTIVE y URL en el MCP de Infraestructura (http://192.168.10.160:3007/api/services/35).

3. Auditar estado desde terminal:

   ./desplegar.sh --check
   

---

🧪 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/
  • Memoria Técnica de Arquitectura
  • Estructura del Proyecto y Rutas
  • Objetivos y Sprint
  • Bitácora de Tareas
  • Bitácora de Errores e Incidentes
  • Reglas Técnicas y de Operación
  • Ideas y Roadmap
• Inventario Global del Ecosistema: .agente/infraestructura.md