# agents.md — Punto de Entrada del Proyecto Help Desk > **Reglas Obligatorias:** > - Este archivo es el eslabón más importante de la documentación. Leerlo siempre antes de cualquier tarea. > - Cada cambio significativo debe reflejarse en este archivo y en los demás archivos del índice documental (`.agente/`). > - Debe ser técnico, claro y detallado para que cualquier humano, agente o IA lo entienda sin explicaciones previas. > - **Rutina al actualizar el proyecto:** Al actualizar el proyecto, revisar objetivos, errores, memoria, reglas, estructura y README; actualizar la ficha propia en MCP con datos verificados; registrar pruebas y pendientes. Hacer commit de los cambios revisados cuando se solicite actualizar proyecto. El push se realiza según la instrucción vigente del usuario y se confirma contra el remoto; un commit local no prueba publicación. --- ## Antecedentes Help Desk es la aplicación de soporte técnico y gestión de incidencias del ecosistema Telcotronics. Nació de la necesidad de centralizar las solicitudes de asistencia, reportes de averías y consultas operativas de los usuarios y clientes de los servicios de la red. Evolucionó desde una solución básica monousuario a una arquitectura multi-tenant (SaaS) que permite segregar la atención por empresas manteniendo una única infraestructura backend. --- ## Objetivo General Proveer un sistema web robusto, ágil y seguro para la gestión integral de tickets de soporte técnico, con separación de roles y aislamiento por empresa (multi-tenant). ### Responsabilidades Principales: 1. **Atención a clientes:** Registro simplificado de incidencias, categorización por departamento, priorización y seguimiento del hilo de conversación. 2. **Gestión técnica de agentes:** Panel operativo para triaje, respuesta, asignación y resolución de tickets. 3. **Administración por tenant:** Gestión de usuarios, departamentos y configuración propia de cada organización. 4. **Control SaaS global:** Creación, activación y control de cuotas de empresas cliente (tenants). --- ## Stack Técnico | Componente | Tecnología | Versión | |---|---|---| | **Runtime / Backend** | Node.js | v18+ | | **Framework HTTP** | Express | ^5.2.1 | | **Motor de Vistas** | EJS | ^5.0.2 | | **Base de Datos** | MariaDB / MySQL (`mysql2/promise`) | 10.11+ / 8.0+ | | **Autenticación** | `express-session` + `bcryptjs` | ^1.19.0 / ^3.0.3 | | **UI Framework** | Bootstrap 5 + Font Awesome 6 (CDN) | 5.3 / 6.4 | | **Middlewares** | `morgan`, `connect-flash`, `cookie-parser`, `express-fileupload` | Estándar | --- ## Módulos del Sistema y Estado ### 1. Autenticación y Control de Acceso **Estado: ✅ Operativo** - Control de sesión servidor (`express-session`) con hashing `bcryptjs`. - Protección por middleware (`middleware/auth.js`) para 4 roles: `superadmin`, `admin`, `agent`, `client`. - Inyección de datos de contexto (`loadCompany`, `res.locals`). ### 2. Portal de Clientes (`/client`) **Estado: ✅ Operativo** - Dashboard de tickets propios filtrados por usuario y empresa. - Formulario de creación de ticket (asunto, departamento, prioridad, mensaje). - Hilo de discusión y respuestas en tiempo real por recarga/flash. ### 3. Consola de Agentes (`/agent`) **Estado: ✅ Operativo** - Bandeja central de tickets del tenant. - Cambio de estado: `abierto` -> `en_progreso` -> `cerrado`. - Reasignación de agente responsable y respuesta a incidencias. ### 4. Administración de Empresa (`/admin`) **Estado: ✅ Operativo** - Panel de estadísticas básicas. - CRUD de departamentos (Soporte Técnico, Facturación, Ventas, etc.). - Gestión de usuarios del tenant (activación/desactivación y roles). ### 5. Consola SaaS Superadmin (`/saas`) **Estado: ✅ Operativo** - Gestión global de empresas/tenants (`companies`). - Asignación de planes (`free`, `pro`, `enterprise`) y cuotas máximas de usuarios y tickets. ### 6. Módulo FSM — Visitas Técnicas en Terreno (`/agent/ticket/:id/visita`) **Estado: ✅ Operativo** - Programación y despacho de visitas técnicas directamente hacia `tareas.telcotronics.com` (CT 132 `192.168.10.160:3000`). - Sincronización de nómina de técnicos en tiempo real (`/api/external/users/list`). - Creación de tareas operativas con checklist inicial, coordenadas GPS y destino. - Persistencia en MariaDB (`ticket_visitas`) con caché de timeline en `historial_json`. - Mini-Timeline de seguimiento en vivo en `view-ticket.ejs`: Programada ➔ Check-in GPS ➔ Evidencias/Fotos ➔ Finalización con firma del cliente. - Automatización bidireccional de hilos de tickets y estados (`en_progreso` al despachar, `completada` al cerrar). ### 7. Coordinación Tripartita Ecosistema (`ideas` <-> `tareas` <-> `help_desk`) **Estado: ✅ Activo en sigma-robot** - Identidad oficial: **Agente Help Desk** (ID `90`), autorizado por `pablinux`. - Centro de Comunicaciones: `sigma-robot` (MCP `sigma-agentes` y API REST `https://sigma-bot.telcotronics.com/ecosistema/v1`). - **app_tareas (ID 89):** Despacho M2M de visitas técnicas FSM, timeline en vivo, firmas de clientes y checklist de campo. - **app_ideas (ID 82):** Canalización de tickets recurrentes, solicitudes de clientes (feature requests) y mejoras hacia el Canvas estratégico de ideas para evaluación y posterior generación de objetivos. --- ## Infraestructura y Fuentes de Verdad - **Repositorio Git Oficial:** `https://git.telcotronics.net/pablinux/help_desk.git` (remoto `origin` configurado localmente). - **Servidor MCP de Infraestructura:** `http://192.168.10.160:3006/sse` (modo SSE). Panel web: `http://192.168.10.160:3007`. - **Ficha MCP de Help Desk:** - Categoría: `application` - Tipo: `webapp` - Puerto: `3008` - URL Oficial: `https://soporte.sigmac.app` - Estado en inventario: ✅ **Registrado oficialmente como Servicio ID 35** (`http://192.168.10.160:3007/api/services/35`). - Incidente previo resuelto: Feedback #20 cerrado como `RESOLVED` tras liberación de espacio en disco en CT 114. - **Despliegue y Orquestación:** - Archivo de destinos: `servers.conf` (a partir de `servers.conf.example`, no commiteado). - Script de despliegue: `./desplegar.sh` (sincroniza rsync, instala deps, setup MariaDB, solicita reinicio a SIAX Monitor y actualiza MCP). - Orquestador de procesos: **SIAX Monitor** (`http://192.168.10.160:8080`) supervisando la unidad `siax-app-HELPDESK.service`. - Servidor de ejecución: `server-webapps` (CT 132 `192.168.10.160`). - Dominio público: `https://soporte.sigmac.app` (Proxy reverso en `Servidor-web` CT 109 `192.168.10.109`). - **Base de Datos Central:** - Host: `192.168.10.149:3306` (CT 114 en Proxmox). - Base de datos: `help_desk` (Verificada: 6 tablas activas: `companies`, `departments`, `ticket_respuestas`, `tickets`, `users`, `ticket_visitas`). - Usuario: `helpdesk`. - **Puerto Local de Ejecución:** `3008`. ### Documentos Compartidos del Ecosistema - `/home/pablinux/Projects/infraestructura.md`: Respaldado localmente en `.agente/infraestructura.md`. - `/home/pablinux/Projects/design-system.md`: Estándar visual SIGMA. - `/home/pablinux/Projects/roadmap.md`: Decisiones y prioridades estratégicas. --- ## Bitácora Centralizada de Errores (Ecosistema Telcotronics) Este proyecto reporta sus errores de runtime a la bitácora centralizada de **API-SIGMA-WEBCONTROL** (`https://api.siax-system.net`). Esto tiene dos direcciones — implementar el reporte es solo la mitad: quien mantenga este proyecto (agente o humano) debe además **consultar** periódicamente qué se reportó, no asumir que reportar es "trabajo terminado". **Fuente autoritativa del contrato:** - Swagger en vivo: `https://api.siax-system.net/api-docs` → tag "Errores de Sistemas". - `agents.md` de API-SIGMA-WEBCONTROL y MCP de Infraestructura (`infra://guias/bitacora-errores`). **Separación de canales:** - La bitácora humana está en `https://siax-system.net` (WebControlSigma). - El único destino de reporte de runtime es `POST https://api.siax-system.net/api/errores`. - El MCP interno distribuye guías e inventario; no transporta errores ni hace de proxy de la API de errores. ### Reportar — `POST https://api.siax-system.net/api/errores` - Auth: `x-api-key` a nivel-app (`WEBCONTROL_API_KEY`). - Implementado en Express vía middleware en [config/errorReporter.js](file:///home/pablinux/Projects/Node/help_desk/config/errorReporter.js). - Parámetros: `app_origen: "Help Desk"`, `mensaje`, `detalle` (stack trace), `categoria` (`sistema`, `bd`, `auth`, `red`), `codigo`, `clase`, `metodo`, `usuario`, `cuenta`, `version`, `fecha_evento`. - Deduplicación automática en memoria con throttle de 10 minutos por firma de error. ### Consultar — Descargar lo que ya se reportó de esta app Al empezar una sesión de mantenimiento de este proyecto (o cuando se pida revisar errores/bugs reportados por usuarios reales), traer los propios antes de asumir que no hay nada nuevo: - **CLI rápido:** `npm run check:errors` (ejecuta [scripts/consultar_errores.js](file:///home/pablinux/Projects/Node/help_desk/scripts/consultar_errores.js)). - **HTTP directo:** `GET https://api.siax-system.net/api/errores?app_origen=Help Desk` (con header `x-api-key`). - **Resumen:** `GET https://api.siax-system.net/api/errores/resumen?dias=7`. - **Conversión a Objetivos:** Cualquier error nuevo se registra en [.agente/objetivos.md](file:///home/pablinux/Projects/Node/help_desk/.agente/objetivos.md) como objetivo verificable y en [.agente/proyecto_errores.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_errores.md). --- ## Variables de Entorno (`.env`) ```ini PORT=3008 DB_HOST=192.168.10.149 DB_USER=helpdesk DB_PASSWORD=[PROTEGIDO_VER_ENV_LOCAL] DB_NAME=help_desk SESSION_SECRET=[SECRETO_SESION] JWT_SECRET=[SECRETO_JWT] # Bitácora de Errores (API-SIGMA-WEBCONTROL) ERROR_REPORTING_URL=https://api.siax-system.net/api/errores WEBCONTROL_API_KEY=[API_KEY_WEBCONTROL] ``` --- ## Migraciones y Configuración de Base de Datos Para inicializar las tablas y datos semilla de la base de datos: ```bash node config/setup.js ``` El script verifica la conexión, crea las tablas si no existen, aplica migraciones de columnas multi-tenant y siembra la empresa `demo`, departamentos y los cuatro usuarios base: - `super@helpdesk.com` / `123456` (superadmin) - `admin@helpdesk.com` / `123456` (admin) - `agent@helpdesk.com` / `123456` (agent) - `client@helpdesk.com` / `123456` (client) --- ## Arranque Local ```bash # Instalación de dependencias npm install # Inicializar/verificar BD node config/setup.js # Arrancar aplicación npm start # O desarrollo node app.js ``` Acceso web en navegador: `http://localhost:3008` --- ## Índice de Archivos del Proyecto - [id_agente.md](file:///home/pablinux/Projects/Node/help_desk/id_agente.md): Identidad del agente asignada por sigma-robot. - [README.md](file:///home/pablinux/Projects/Node/help_desk/README.md): Manual y guía general para operadores humanos. - [.agente/infraestructura.md](file:///home/pablinux/Projects/Node/help_desk/.agente/infraestructura.md): Espejo 100% sincronizado del inventario global. - [.agente/proyecto_memoria.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_memoria.md): Memoria técnica y decisiones de diseño. - [.agente/proyecto_estructura.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_estructura.md): Árbol de archivos y tabla completa de endpoints HTTP. - [.agente/proyecto_errores.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_errores.md): Bitácora de incidentes y problemas conocidos. - [.agente/objetivos.md](file:///home/pablinux/Projects/Node/help_desk/.agente/objetivos.md): Registro de objetivos completados, en curso y pendientes. - [.agente/tareas.md](file:///home/pablinux/Projects/Node/help_desk/.agente/tareas.md): Bitácora de tareas, entregables completados y backlog. - [.agente/reglas.md](file:///home/pablinux/Projects/Node/help_desk/.agente/reglas.md): Reglas de seguridad y buenas prácticas del proyecto. - [.agente/ideas.md](file:///home/pablinux/Projects/Node/help_desk/.agente/ideas.md): Registro de propuestas e ideas en evaluación.