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