pablinux/help_desk
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: inicializacion de Help Desk segun estandar Telcotronics con bitacora de errores e integracion MCP

Browse Source
This commit is contained in:
pablinux
2026-10-16 23:29:32 -05:00
commit 0f2708462e
54 changed files with 7590 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agente/ideas.md
+21
View File
@@ -0,0 +1,21 @@
# Ideas y Propuestas — Help Desk
## Ideas Pendientes de Evaluación
1. **API RESTful dedicada con JWT:**
- Exponer endpoints versionados `/api/v1/tickets` protegidos por tokens Bearer para integración con clientes móviles (ej. Flutter) o sistemas externos.
2. **Integración con bot de comunicaciones (sigma-robot):**
- Notificaciones inmediatas en canales de mensajería (Telegram / WhatsApp) cuando se registre un ticket con prioridad `critica` o cuando un agente responda.
3. **Subida real de adjuntos:**
- Implementar almacenamiento de capturas de pantalla y archivos adjuntos (usando `express-fileupload`) con persistencia en directorio dedicado o servicio de almacenamiento compartido del ecosistema.
4. **SLA y métricas de resolución:**
- Panel visual con tiempos medios de respuesta por departamento y alertas cuando un ticket supere 24/48 horas sin respuesta.
---
## Borradores y Exploraciones
- *Borrador:* Integración de IA para categorización automática del departamento según el asunto y mensaje del ticket.
.agente/infraestructura.md
+2789
View File
File diff suppressed because it is too large Load Diff
.agente/objetivos.md
+29
View File
@@ -0,0 +1,29 @@
# Objetivos del Proyecto — Help Desk
## Objetivos en Curso
*(Ninguno actualmente en curso)*
---
## Objetivos Pendientes
| ID | Objetivo | Origen | Prioridad | Criterio de Aceptación |
|---|---|---|---|---|
| **OBJ-001** | Script `init.sh` estandarizado del ecosistema | Estándar Telcotronics | Alta | Menú interactivo/flags para arranque local, validación de variables de entorno y conexión con MariaDB |
| **OBJ-002** | Script `desplegar.sh` para producción | Estándar Telcotronics | Media | Automatización de sincronización y preparación hacia servidor de producción Proxmox |
| **OBJ-003** | Ficha de servicio registrada en el MCP de Infraestructura | Requerimiento ecosistema | Alta | Reintentar registro vía `crear_servicio` tras resolución de Feedback #20 (Error 1114: table 'services' is full) |
| **OBJ-004** | Depuración o activación de API REST JWT | Memoria técnica | Media | Decidir entre implementar endpoints `/api/v1` para clientes externos o retirar paquete `jsonwebtoken` |
| **OBJ-005** | Adaptación de vistas UI al SIGMA Design System | Guía de diseño del ecosistema | Baja | Colores corporativos, tipografía y componentes alineados con `design-system.md` |
---
## Objetivos Completados
| Fecha | Objetivo | Evidencia |
|---|---|---|
| 2026-10-16 | **OBJ-006:** Integración de bitácora centralizada de errores y remoto Git | Módulo `config/errorReporter.js`, middleware global en `app.js`, script `scripts/consultar_errores.js` (`npm run check:errors`) y remoto `git.telcotronics.net/pablinux/help_desk.git` configurado |
| 2026-10-16 | **OBJ-000:** Inicialización documental estandarizada según estándar Telcotronics | Estructura `.agente/` completa, espejo `infraestructura.md` sincronizado al 100%, `id_agente.md`, `agents.md` y `README.md` alineados |
| 2026-05-16 | Implementación del backend base con Express 5 y MariaDB | Modelos `User`, `Department`, `Ticket`, rutas funcionales y conexión a `192.168.10.149` |
| 2026-05-16 | Implementación de vistas EJS y roles client, agent, admin | Plantillas en `views/` con Bootstrap 5, autenticación con bcrypt y session |
| 2026-05-16 | Evolución multi-tenant SaaS y modelo Company | Migración en `config/setup.js`, modelo `Company.js`, rutas `/saas` y `/company` |
.agente/proyecto_errores.md
+38
View File
@@ -0,0 +1,38 @@
# Bitácora de Errores e Incidentes — Help Desk
## Incidente #1: Comportamiento inestable de `node --watch`
- **Fecha:** 2026-05-16
- **Síntoma:** El comando `node --watch app.js` (`npm run dev`) no detecta recargas o falla en ciertos entornos Linux / terminales virtuales.
- **Causa confirmada:** Limitación del soporte experimental de `--watch` en ciertas versiones y sistemas de archivos bajo Linux.
- **Solución / Alternativa:** Utilizar `nodemon` para desarrollo o arrancar con `npm start` estándar.
- **Verificación:** Ejecución directa con `node app.js` funciona de forma estable.
- **Estado:** Resuelto (con workaround documentado).
---
## Incidente #2: Dependencia no utilizada en código activo (`jsonwebtoken`)
- **Fecha:** 2026-05-16
- **Síntoma:** `jsonwebtoken` figura en las dependencias de `package.json`, pero no es importado en ninguna ruta activa (`routes/`).
- **Causa confirmada:** Se planificó inicialmente una API REST para clientes móviles, pero se implementó interfaz web monousuario/multi-tenant con `express-session`.
- **Solución:** Mantener identificada la dependencia; evaluar si se implementará la API REST para la app móvil o desinstalarla para limpiar el árbol de dependencias.
- **Estado:** Pendiente de decisión técnica.
---
## Incidente #3: Error 1114 al registrar servicio en MCP de Infraestructura
- **Fecha:** 2026-10-16
- **Síntoma:** Al invocar `crear_servicio` en el MCP de Infraestructura (`192.168.10.160:3006`), MariaDB devolvió: `MysqlError 1114 (HY000): The table 'services' is full`.
- **Causa confirmada:** La tabla `services` en la base de datos `mcp_infraestructura` (MariaDB `192.168.10.149:3306`) alcanzó su límite de tamaño o memoria asignada.
- **Solución / Seguimiento:** Se reportó como **Feedback #20** (`helpdesk-services-full-20261016`, severidad `CRITICAL`, estado `OPEN`) en el sistema de feedback del MCP. Reintentar el registro una vez resuelto en MariaDB.
- **Estado:** Reportado / Pendiente de resolución externa.
---
## Integración con Bitácora Centralizada (API-SIGMA-WEBCONTROL)
- **Endpoint de Reporte:** `POST https://api.siax-system.net/api/errores`
- **Módulo implementado:** `config/errorReporter.js` + middleware global en `app.js`.
- **Filtro de consulta:** `GET https://api.siax-system.net/api/errores?app_origen=Help Desk`
- **Comando de verificación:** `npm run check:errors` (o `node scripts/consultar_errores.js`).
- **Consola visual humana:** `https://siax-system.net` (WebControlSigma).
.agente/proyecto_estructura.md
+127
View File
@@ -0,0 +1,127 @@
# Estructura del Proyecto — Help Desk
## Árbol de Archivos
```text
help_desk/
├── app.js # Punto de entrada de la aplicación Express
├── package.json # Metadatos del proyecto y dependencias npm
├── package-lock.json # Bloqueo de versiones de dependencias
├── .env.example # Plantilla de variables de entorno (sin secretos)
├── .gitignore # Ignorados por Git (node_modules, .env)
├── id_agente.md # Identidad del agente en sigma-robot (estado local)
├── README.md # Documentación general para humanos
├── agents.md # Punto de entrada principal para agentes IA
├── .agente/ # Documentación interna del proyecto
│ ├── infraestructura.md # Espejo del inventario global de infraestructura
│ ├── proyecto_memoria.md # Historial de decisiones y arquitectura
│ ├── proyecto_estructura.md # Este archivo: árbol, rutas y dependencias
│ ├── proyecto_errores.md # Bitácora de incidentes y problemas conocidos
│ ├── objetivos.md # Objetivos pendientes, en curso y completados
│ ├── reglas.md # Restricciones técnicas y de seguridad
│ └── ideas.md # Ideas y propuestas pendientes
├── config/
│ ├── db.js # Pool de conexión a MariaDB con mysql2/promise
│ ├── errorReporter.js # Cliente y reporter de errores hacia API-SIGMA-WEBCONTROL
│ ├── init.sql # Esquema SQL relacional base
│ └── setup.js # Script de inicialización y migración multi-tenant
├── scripts/
│ └── consultar_errores.js # Script CLI para consultar la bitácora centralizada de errores
├── middleware/
│ └── auth.js # Middlewares: isAuthenticated, roles y loadCompany
├── models/
│ ├── Company.js # Consultas y operaciones para empresas/tenants
│ ├── Department.js # Operaciones CRUD para departamentos
│ ├── Ticket.js # Consultas, creación y respuestas de tickets
│ └── User.js # Autenticación, creación y gestión de usuarios
├── routes/
│ ├── auth.js # Rutas de autenticación (login, register, logout)
│ ├── client.js # Rutas para clientes (creación y seguimiento de tickets)
│ ├── agent.js # Rutas para agentes (gestión, respuesta y asignación)
│ ├── admin.js # Rutas para administradores (usuarios, departamentos)
│ ├── saas.js # Rutas para superadmin (empresas y tenants)
│ └── company.js # Rutas de ajustes de la empresa
├── views/
│ ├── partials/
│ │ ├── header.ejs # Encabezado HTML y carga de CSS/CDN
│ │ ├── footer.ejs # Scripts de Bootstrap y cierre HTML
│ │ ├── navbar.ejs # Barra de navegación superior con perfil
│ │ └── sidebar.ejs # Menú lateral dinámico según rol
│ ├── auth/
│ │ ├── login.ejs # Vista de inicio de sesión
│ │ └── register.ejs # Vista de registro de usuario
│ ├── client/
│ │ ├── dashboard.ejs # Panel principal de cliente con sus tickets
│ │ ├── new-ticket.ejs # Formulario para registrar nuevo ticket
│ │ └── view-ticket.ejs # Detalle del ticket y formulario de respuesta
│ ├── agent/
│ │ ├── dashboard.ejs # Panel general de tickets para agentes
│ │ └── view-ticket.ejs # Vista de resolución, reasignación y respuesta
│ ├── admin/
│ │ ├── dashboard.ejs # Panel de control de administrador con estadísticas
│ │ ├── users.ejs # Lista y gestión de usuarios
│ │ ├── create-user.ejs # Formulario para dar de alta usuarios
│ │ └── departments.ejs # Gestión de departamentos de soporte
│ ├── saas/
│ │ └── companies.ejs # Gestión de empresas para superadmin
│ └── company/
│ └── settings.ejs # Configuración general de la empresa
└── public/
├── css/
│ └── style.css # Estilos personalizados de la interfaz
└── js/
└── main.js # Lógica JavaScript en navegador
```
---
## Tabla de Rutas HTTP
| Método | Ruta | Middleware de Acceso | Descripción |
|---|---|---|---|
| **GET** | `/` | Sesión / Redirección | Redirige al dashboard correspondiente según el rol del usuario |
| **GET** | `/login` | Público | Renderiza formulario de login |
| **POST** | `/login` | Público | Valida credenciales e inicializa sesión |
| **GET** | `/register` | Público | Formulario de registro de cliente |
| **POST** | `/register` | Público | Crea usuario nuevo con rol `client` |
| **GET** | `/logout` | `isAuthenticated` | Cierra la sesión y redirige a login |
| **GET** | `/client/dashboard` | `isAuthenticated`, `isClient` | Listado de tickets creados por el cliente |
| **GET** | `/client/tickets/new` | `isAuthenticated`, `isClient` | Formulario de nuevo ticket |
| **POST** | `/client/tickets` | `isAuthenticated`, `isClient` | Registro de nuevo ticket |
| **GET** | `/client/tickets/:id` | `isAuthenticated`, `isClient` | Vista de detalle de un ticket y su conversación |
| **POST** | `/client/tickets/:id/reply` | `isAuthenticated`, `isClient` | Publica una respuesta a un ticket propio |
| **GET** | `/agent/dashboard` | `isAuthenticated`, `isAgent` | Bandeja de tickets de la empresa para agentes |
| **GET** | `/agent/tickets/:id` | `isAuthenticated`, `isAgent` | Detalle del ticket, cambio de estado y asignación |
| **POST** | `/agent/tickets/:id/reply` | `isAuthenticated`, `isAgent` | Envía respuesta oficial del agente |
| **POST** | `/agent/tickets/:id/status`| `isAuthenticated`, `isAgent` | Actualiza estado: `abierto`, `en_progreso`, `cerrado` |
| **POST** | `/agent/tickets/:id/assign`| `isAuthenticated`, `isAgent` | Asigna ticket a un agente específico |
| **GET** | `/admin/dashboard` | `isAuthenticated`, `isAdmin` | Métricas y estadísticas de la empresa |
| **GET** | `/admin/users` | `isAuthenticated`, `isAdmin` | Lista de usuarios del tenant |
| **GET** | `/admin/users/create` | `isAuthenticated`, `isAdmin` | Formulario para crear agentes o administradores |
| **POST** | `/admin/users` | `isAuthenticated`, `isAdmin` | Alta de usuario con rol específico |
| **POST** | `/admin/users/:id/toggle` | `isAuthenticated`, `isAdmin` | Activa o desactiva acceso de un usuario |
| **GET** | `/admin/departments` | `isAuthenticated`, `isAdmin` | Catálogo de departamentos |
| **POST** | `/admin/departments` | `isAuthenticated`, `isAdmin` | Creación de departamento |
| **POST** | `/admin/departments/:id/delete` | `isAuthenticated`, `isAdmin` | Eliminación de departamento |
| **GET** | `/saas/companies` | `isAuthenticated`, `isSuperAdmin` | Panel maestro de organizaciones para Superadmin |
| **POST** | `/saas/companies` | `isAuthenticated`, `isSuperAdmin` | Creación de nuevo tenant / empresa |
| **POST** | `/saas/companies/:id/toggle` | `isAuthenticated`, `isSuperAdmin` | Activa / suspende un tenant |
| **GET** | `/company/settings` | `isAuthenticated`, `isAdmin` | Configuración y estado de la empresa |
---
## Dependencias Principales
| Paquete | Versión | Rol |
|---|---|---|
| `express` | ^5.2.1 | Framework web principal |
| `mysql2` | ^3.22.3 | Conector a MariaDB / MySQL con soporte para promesas |
| `ejs` | ^5.0.2 | Motor de renderizado del lado del servidor |
| `express-session` | ^1.19.0 | Manejo de sesiones de usuario |
| `bcryptjs` | ^3.0.3 | Hashing y verificación de contraseñas |
| `connect-flash` | ^0.1.1 | Mensajes flash temporales en vistas |
| `cookie-parser` | ^1.4.7 | Parseo de cookies HTTP |
| `express-fileupload`| ^1.5.2 | Manejo de archivos subidos en formularios |
| `morgan` | ^1.10.1 | Logger HTTP en consola |
| `dotenv` | ^17.4.2 | Carga de variables de entorno desde `.env` |
| `jsonwebtoken` | ^9.0.3 | Instalado (reservado para endpoints de API REST) |
.agente/proyecto_memoria.md
+58
View File
@@ -0,0 +1,58 @@
# 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`).
.agente/reglas.md
+21
View File
@@ -0,0 +1,21 @@
# Reglas Técnicas y de Operación — Help Desk
## 1. Regla de Seguridad Crítica en Infraestructura (MCP)
- **Alcance:** Todas las operaciones con el servidor MCP de Infraestructura (`192.168.10.160:3006`).
- **Restricción:** El servidor MCP tiene bloqueada toda operación de eliminación de registros. La eliminación de cualquier servicio, hardware o registro SOLO puede realizarse desde la interfaz web bajo supervisión humana explícita.
- **Motivo:** Evitar borrados accidentales de elementos compartidos del ecosistema por parte de agentes autónomos.
## 2. Aislamiento Multi-Tenant Estricto
- **Alcance:** Modelos y consultas SQL a la base de datos (`models/*.js`).
- **Restricción:** Toda consulta, creación o actualización de tickets, departamentos o usuarios que pertenezcan a un tenant DEBE incluir la cláusula `WHERE company_id = ?` correspondiente a la sesión activa (`req.session.user.company_id`).
- **Motivo:** Garantizar la confidencialidad y aislamiento de datos entre empresas.
## 3. Manejo de Secretos y Repositorios
- **Alcance:** Archivo `.env` y configuración local.
- **Restricción:** Nunca comitear credenciales, passwords de base de datos ni `SESSION_SECRET` a Git. El archivo `.env` debe permanecer en `.gitignore`. Para repositorios se mantiene `.env.example` sin valores sensibles.
- **Motivo:** Seguridad de la red interna y cumplimiento de buenas prácticas.
## 4. Rutina de Actualización Documental
- **Alcance:** Mantenimiento y evolución del proyecto.
- **Restricción:** Al solicitar "actualizar proyecto", se debe revisar y sincronizar `agents.md`, `.agente/proyecto_estructura.md`, `.agente/proyecto_memoria.md`, `.agente/proyecto_errores.md`, `.agente/objetivos.md`, `README.md` y la ficha en el MCP de Infraestructura.
- **Motivo:** Preservar la fuente de verdad técnica y la coherencia en todo el ecosistema.