# 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`.