# Memoria Técnica del Proyecto — Help Desk ## Fecha de inicio 16 de Mayo, 2026 ## Stack tecnológico - **Backend / Runtime:** Node.js con Express 5.2 - **Motor de plantillas:** EJS 5 con partials modulares - **Base de datos:** MariaDB / MySQL con `mysql2` (modo async/promises) - **Autenticación y Seguridad:** `express-session`, `cookie-parser`, `bcryptjs` - **Frontend / UI:** Bootstrap 5.x + Font Awesome 6 vía CDN - **Middlewares complementarios:** `morgan` (logging HTTP), `connect-flash` (mensajes flash), `express-fileupload` (subida de archivos) --- ## Decisiones de Arquitectura 1. **MySQL/MariaDB vs MongoDB:** - Decisión: Se utiliza MariaDB (servidor `192.168.10.149`), alineado al stack relacional habitual de servicios internos. El modelo relacional asegura integridad referencial estricta entre empresas, usuarios, departamentos, tickets y respuestas. 2. **express-session vs JWT:** - Decisión: Se optó por sesiones del lado del servidor con `express-session` para la interfaz web renderizada con EJS. Esto permite la persistencia natural de la sesión en cookies de navegador y la integración directa con `connect-flash`. Aunque `jsonwebtoken` se incluyó en las dependencias iniciales, se mantiene en reserva para una futura API REST. 3. **Arquitectura Multi-tenant (SaaS):** - Decisión: El esquema evolucionó desde una aplicación simple monousuario/monoempresa a un modelo multi-tenant basado en la entidad `companies`. Todas las entidades dependientes (`users`, `departments`, `tickets`) contienen `company_id` obligatorio. - Existe una empresa por defecto (`Demo Company` con slug `demo`) creada por el script de setup. 4. **Roles y Permisos:** - Se definieron cuatro niveles de autorización controlados por middleware (`middleware/auth.js`): - `superadmin`: Gestión global de empresas y capacidades del SaaS. - `admin`: Administrador de una empresa específica (gestiona agentes, clientes, departamentos y tickets de su empresa). - `agent`: Agente de soporte técnico (gestiona tickets asignados o de su departamento, responde y cambia estados). - `client`: Usuario final (crea tickets, visualiza sus tickets y añade respuestas). 5. **EJS con Partials:** - Decisión: Se utilizan partials (`header.ejs`, `footer.ejs`, `navbar.ejs`, `sidebar.ejs`) sin frameworks de layout adicionales para mantener simplicidad y bajo acoplamiento. 6. **Estilos y Assets Livianos:** - Decisión: Bootstrap 5 y Font Awesome se cargan desde CDN público, complementados con `public/css/style.css` y `public/js/main.js` para personalizaciones locales. 7. **Módulo de Asignación de Tareas y Visitas Técnicas (FSM - Field Service Management):** - Decisión: Integración directa bidireccional entre `help_desk` y el sistema central `tareas.telcotronics.com` (CT 132 `192.168.10.160:3000`). - Cuando un ticket requiere atención presencial, el agente programa la visita desde el modal de Help Desk asignando a técnicos reales del Hub (obtenidos en vivo de `/api/external/users/list`). - Se crea una tarea operativa en el Hub (`POST /api/external/tareas`) con destino (dirección, coordenadas GPS, referencia), prioridad y un checklist inicial de tareas. - En MariaDB se almacena en la tabla `ticket_visitas`, incluyendo la columna `historial_json` (LONGTEXT) para cachear el timeline operativo (hora de llegada/check-in GPS, progreso del checklist, fotos de evidencia en terreno y firma digital del cliente). - En la vista del ticket (`view-ticket.ejs`), se presenta un **Mini-Timeline de Seguimiento Operativo en Vivo** con botón de sincronización a demanda (`POST /agent/ticket/:id/visita/sync`). - Automatización bidireccional: al programar se actualiza el ticket a `en_progreso` y se publica un mensaje en el hilo. Al detectar que la tarea externa fue completada en campo, se actualiza la visita a `completada` y se inserta una respuesta de cierre con las observaciones y firma del cliente en el hilo del ticket. 8. **Bitácora Centralizada de Errores (API-SIGMA-WEBCONTROL):** - Decisión: Integración con el servicio central de auditoría de errores en `http://192.168.10.149:3005` mediante `config/errorReporter.js`. Dispone de throttling en memoria (10 min) para no saturar la API central ante ráfagas de errores idénticos, y middleware global de Express en `app.js`. --- ## Base de Datos - **Servidor:** MariaDB en `192.168.10.149:3306` (Contenedor CT 114) - **Usuario:** `helpdesk` - **Base de datos:** `help_desk` - **Tablas:** - `companies`: Gestión de empresas/organizaciones (id, name, slug, plan, max_users, max_tickets, is_active, timestamps). - `users`: Usuarios de cada empresa (id, company_id, nombre, email, password, rol, is_active, invite_token, invited_by, timestamps). - `departments`: Departamentos de soporte por empresa (id, company_id, nombre, descripcion, created_at). - `tickets`: Tickets de soporte (id, company_id, user_id, department_id, asunto, mensaje, status, prioridad, assigned_to, timestamps). - `ticket_respuestas`: Mensajes e hilo de conversación de cada ticket (id, ticket_id, user_id, mensaje, created_at). - `ticket_visitas`: Visitas técnicas y tareas de campo vinculadas a tickets y al Hub de tareas (id, company_id, ticket_id, external_id, tecnico_email, tecnico_nombre, titulo, descripcion, ubicacion, fecha_visita, fecha_fin, estado, checklist_json, historial_json, created_at, updated_at). --- ## Puerto del Servidor - **Puerto configurado:** `3008` (por variable `PORT=3008` en `.env`).