# 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. --- ## 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: `service` / `application` - Estado en inventario: ⏳ Pendiente de registro remoto. Se intentó registrar vía `crear_servicio`, pero la base de datos del MCP arrojó `MysqlError 1114 (The table 'services' is full)`. Se registró el incidente formalmente en el sistema de feedback del MCP como **Feedback #20** (`helpdesk-services-full-20261016`, estado `OPEN`). - **Base de Datos Central:** - Host: `192.168.10.149:3306` (CT 114 en Proxmox). - Base de datos: `help_desk` (Verificada: 5 tablas activas: `companies`, `departments`, `ticket_respuestas`, `tickets`, `users`). - 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/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.