help_desk/memoria.md

Memoria Técnica del Proyecto — Help Desk

Fecha de inicio

16 de Mayo, 2026

Stack Tecnológico

• Runtime / Backend: Node.js 20+ con Express 5.2.
• Motor de Vistas: EJS 5 con partials modulares.
• Base de Datos: MariaDB 10.11 / MySQL (mysql2/promise) en CT 114 (192.168.10.149:3306).
• Autenticación y Sesiones: express-session, cookie-parser, bcryptjs.
• Integraciones de Identidad: SIGMA WebControl API, Google Identity Services (GIS), Facebook OAuth.
• Frontend / UI: Bootstrap 5.3 + Font Awesome 6 (CDN) + Estilos custom (public/css/style.css).
• Middlewares y Utilidades: morgan, connect-flash, express-fileupload, qrcode.
• Integración FSM: API REST externa contra tareas.telcotronics.com (CT 132 192.168.10.160:3000).
• Auditoría de Errores: Integración con API-SIGMA-WEBCONTROL (192.168.10.149:3005).

---

Decisiones de Arquitectura

1. MariaDB Relacional vs NoSQL:

   • Se utiliza MariaDB en CT 114 (192.168.10.149:3306), garantizando integridad referencial estricta, llaves foráneas y consistencia transaccional multi-tenant.

2. express-session vs JWT:

   • Se utiliza express-session con almacenamiento de sesión del lado del servidor para el portal web renderizado con EJS, facilitando el manejo de mensajes flash (connect-flash) y redirecciones seguras. jsonwebtoken permanece reservado para APIs REST.

3. Arquitectura Multi-tenant SaaS:

   • La tabla maestra companies gobierna el aislamiento lógico. Todas las entidades operativas (users, departments, tickets, ticket_visitas, herramientas, herramientas_sets, tecnico_herramientas_asignaciones) incorporan la clave foránea company_id.
   • Soporte para cuotas máximas de usuarios y tickets por plan (free, pro, enterprise).

4. 4 Roles de Usuario con Control Granular (middleware/auth.js):

   • superadmin: Acceso a /saas/companies para gestión global de organizaciones.
   • admin: Administración de agentes, clientes, departamentos, inventario de herramientas y configuraciones de la empresa.
   • agent: Bandeja operativa de tickets, triaje, respuestas, despacho de visitas técnicas FSM y asignación de herramientas.
   • client: Apertura y seguimiento de incidencias propias.

5. Estrategia Multicanal de Autenticación & Mascota Bot:

   • Los clientes del ecosistema validan sus credenciales contra SIGMA WebControl (api.siax-system.net) con aprovisionamiento transparente en MariaDB.
   • Los nuevos clientes pueden autenticar mediante Google Identity Services (GIS) y Facebook Login.
   • El personal técnico (superadmin, admin, agent) utiliza la consola local MariaDB protegida por bcryptjs.
   • Mascota oficial del Bot de Soporte (/img/bot-soporte.svg, /img/bot-soporte.png) integrada en la interfaz de login.

6. Módulo FSM — Despacho y Trazabilidad de Campo:

   • Integrado bidireccionalmente con tareas.telcotronics.com (CT 132 192.168.10.160:3000).
   • Sincronización en vivo de nómina de técnicos, despacho con checklist, dirección y coordenadas GPS.
   • Mini-Timeline de 4 hitos operativos en el ticket: Programada ➔ Check-in GPS en sitio ➔ Avance de checklist con fotos ➔ Cierre con firma digital del cliente.
   • Automatización de estados y mensajes en el hilo del ticket al programar o completar la visita.

7. Módulo de Inventario de Herramientas, Sets y Manifiesto QR:

   • Inventario físico multi-tenant de herramientas individuales (herramientas) con código, serie, marca, modelo, estado (disponible, en_uso, en_reparacion, baja) y fotografía.
   • Agrupación en Sets / Kits de Herramientas (herramientas_sets y herramientas_set_items) para maletines de trabajo (fusión de fibra, redes de cobre, kits de cuadrilla).
   • Asignación de custodia a técnicos (tecnico_herramientas_asignaciones) en dos modalidades: dotación fija de bodega o vinculada a un ticket de visita técnica FSM.
   • Subida y almacenamiento seguro de imágenes (config/uploader.js) para evidencias de herramientas, maletines, estado de entrega y estado de devolución.
   • Generación de códigos QR e impresión térmica adhesiva (/admin/herramientas/sets/:id/etiqueta) optimizada a 95mm vía @media print.
   • Manifiesto móvil web responsivo (/qr/set/:token y /qr/asignacion/:token) con badge de custodia en vivo (EN BODEGA vs EN CUSTODIA) y checklist interactivo para auditoría de maletines en terreno o almacén.
   • Endpoint externo M2M /api/external/herramientas/sets protegido por API Key.

8. Despliegue a Producción y Orquestación con SIAX Monitor:

   • Servidor: CT 132 192.168.10.160 (server-webapps), puerto 3008.
   • Dominio público: https://soporte.sigmac.app mediante proxy reverso en CT 109 (192.168.10.109:443).
   • Administrado por la unidad systemd siax-app-HELPDESK.service y supervisado por SIAX Monitor (:8080).
   • Despliegue atómico automatizado vía ./desplegar.sh.
   • Registrado oficialmente en el MCP de Infraestructura como Servicio ID 35.

---

Esquema de Base de Datos (10 Tablas Activas)

• companies: Gestión de tenants SaaS y cuotas.
• users: Usuarios del sistema con soporte multicanal (provider, provider_id, rol, company_id).
• departments: Áreas o departamentos de soporte técnico.
• tickets: Tickets de soporte con aislamiento por empresa, prioridad y estado.
• ticket_respuestas: Mensajes, notas y respuestas del hilo del ticket.
• ticket_visitas: Visitas técnicas y tareas de campo FSM con timeline en historial_json.
• herramientas: Catálogo de herramientas individuales con código, serie, estado y foto_url.
• herramientas_sets: Kits o maletines de herramientas con código, foto_url y qr_token.
• herramientas_set_items: Relación Many-to-Many entre sets y herramientas con cantidad requerida.
• tecnico_herramientas_asignaciones: Registro de custodia a técnicos con estado (activa, devuelta), fotos de entrega/devolución y qr_token.