85 lines
7.9 KiB
Markdown
85 lines
7.9 KiB
Markdown
# 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.
|
|
|
|
---
|
|
|
|
## 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`).
|
|
|