docs: actualizar documentacion tecnica, arquitectura y manuales de herramientas y QR

memoria.md

@@ -1,41 +1,78 @@
-# Memoria del Proyecto - Help Desk
+# Memoria Técnica del Proyecto — Help Desk
 
 ## Fecha de inicio
 16 de Mayo, 2026
 
-## Stack tecnológico
-- Node.js con Express 5
-- EJS como motor de plantillas
-- MariaDB/MySQL con mysql2
-- express-session + bcryptjs para autenticación
-- Bootstrap 5 + Font Awesome para UI
-- morgan, connect-flash, express-fileupload
+## 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. **MySQL vs MongoDB**: El usuario eligió MySQL (MariaDB) como base de datos, consistente con su stack habitual en otros proyectos Node.
+## Decisiones de Arquitectura
 
-2. **express-session vs JWT**: Se optó por sesiones del lado del servidor con express-session en lugar de JWT para mantener la compatibilidad con connect-flash y facilitar mensajes flash. Aunque se instaló jsonwebtoken, no se está utilizando activamente.
+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.
 
-3. **3 roles de usuario**: admin, agent, client. Cada uno con acceso a rutas específicas protegidas por middleware de autenticación.
+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.
 
-4. **EJS con partials**: Se usan partials (header.ejs, footer.ejs, navbar.ejs, sidebar.ejs) en lugar de layouts para mantener la estructura simple sin dependencias extra.
+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`).
 
-5. **Bootstrap 5 desde CDN**: No se incluye Bootstrap local para mantener el proyecto liviano. Se carga desde CDN junto con Font Awesome.
+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.
 
-## Base de Datos
-- Servidor MariaDB en `192.168.10.149`
-- Usuario: `helpdesk`@`192.168.10.101`
-- Base de datos: `help_desk`
-- 4 tablas: users, departments, tickets, ticket_respuestas
+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.
 
-## Puerto del servidor
-- El servidor corre en el puerto 3008
+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.
 
-## Pendientes / Notas
-- La contraseña del usuario helpdesk se cambió de `password` a `5oyN9zvq/2K8b1Fs`
-- jsonwebtoken está instalado como dependencia pero no se usa activamente
-- El frontend es funcional pero se puede mejorar
+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.
 
-## Problemas conocidos
-- node --watch no funciona correctamente en algunos entornos; usar nodemon como alternativa
+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`.