help_desk/.agente/proyecto_memoria.md

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