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.

---

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

---

Puerto del Servidor

• Puerto configurado: 3008 (por variable PORT=3008 en .env).