91 lines
9.0 KiB
Markdown
91 lines
9.0 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.
|
|
|
|
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`).
|
|
|