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.

9. Despliegue a Producción, Dominio y Orquestación con SIAX Monitor:

   • Servidor y Proceso: Desplegado en server-webapps (CT 132 192.168.10.160) bajo la unidad systemd siax-app-HELPDESK.service en el puerto 3008.
   • Supervisión y Ciclo de Vida: Orquestado por SIAX Monitor (http://192.168.10.160:8080), el cual supervisa el proceso autoritativo por MainPID, expone métricas y permite reinicios y despliegues atómicos sin necesidad de sudo interactivo ni contraseñas.
   • Convención de Despliegue: Implementación de servers.conf (a partir de servers.conf.example) y script ./desplegar.sh conforme al estándar Prompt 8 (crear_desplegar_sh) y Feedback #25 del MCP de Infraestructura.
   • Dominio Público y Proxy Reverso: Dominio oficial https://soporte.sigmac.app. El tráfico público ingresa por la WAN hacia Servidor-web CT 109 (192.168.10.109 Apache 2.4.66), que enruta hacia el upstream interno http://192.168.10.160:3008/ confirmado por SIAX Monitor (/api/ports).
   • Inventario MCP de Infraestructura: Registrado oficialmente como Servicio ID 35 (category: application, type: webapp, status: ACTIVE, url: https://soporte.sigmac.app).

10. Estrategia Multicanal de Autenticación y Mascota Bot de Soporte:

    • Clientes de la Plataforma: Autentican directamente contra la API central de Telcotronics API-SIGMA-WEBCONTROL (http://192.168.10.160:3002/api/auth/login con fallback a https://api.siax-system.net/api/auth/login). Al validar credenciales, se realiza aprovisionamiento o actualización transparente en help_desk.users (provider='webcontrol') y se inicia sesión con rol client.
    • Nuevos Clientes (Social OAuth): Integración nativa con Google Identity Services (GIS) verificando ID Tokens contra https://oauth2.googleapis.com/tokeninfo, y Facebook OAuth vía Graph API. Auto-aprovisiona usuarios como clientes sin fricción.
    • Personal Técnico y Staff: La consola de inicio de sesión local MariaDB queda reservada exclusivamente para el personal operativo (superadmin, admin, agent). Se bloquea el acceso de clientes comunes por la consola técnica.
    • Identidad Visual y Mascota: Rediseño integral de la página de inicio de sesión (/login) con control segmentado de pestañas (Clientes vs Personal Técnico) y la mascota oficial robot de soporte (/img/bot-soporte.svg, /img/bot-soporte.png y /img/bot-soporte-512.png) con animación de levitación y estado activo 24/7.

11. Sincronización Inter-Agentes y Coordinación Tripartita (Ideas <-> Tareas <-> Help Desk):

    • Centro de Comunicaciones: Alta formal y token permanente en sigma-robot con identidad autorizada por Pablinux (Agente Help Desk, ID 90), comunicando vía MCP y API REST.
    • Contrato Operativo con app_tareas (ID 89): Despacho M2M de visitas técnicas en terreno (POST /api/external/tareas), trazabilidad GPS en sitio, avance de checklist de campo, fotos de evidencias y firma digital del cliente en canvas móvil, con sincronización de estado y cierre automático en el hilo del ticket.
    • Ciclo de Retroalimentación con app_ideas (ID 82): Canalización de solicitudes de funciones y patrones de fallas hacia el Canvas estratégico de ideas. Se acordó que Help Desk enviará resúmenes técnicos saneados bajo control manual del agente técnico (sin datos personales de clientes), ingresando como candidata_revision antes de que app_ideas genere tareas definitivas hacia app_tareas.

---

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 [nullable], rol, provider, provider_id, avatar_url, 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).