11 KiB
11 KiB
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:
- Atención a clientes: Registro simplificado de incidencias, categorización por departamento, priorización y seguimiento del hilo de conversación.
- Gestión técnica de agentes: Panel operativo para triaje, respuesta, asignación y resolución de tickets.
- Administración por tenant: Gestión de usuarios, departamentos y configuración propia de cada organización.
- 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 hashingbcryptjs. - 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 132192.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 enhistorial_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_progresoal despachar,completadaal cerrar).
Infraestructura y Fuentes de Verdad
- Repositorio Git Oficial:
https://git.telcotronics.net/pablinux/help_desk.git(remotooriginconfigurado 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 - 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
RESOLVEDtras liberación de espacio en disco en CT 114.
- Categoría:
- 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.
- Host:
- 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.mdde 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-keya nivel-app (WEBCONTROL_API_KEY). - Implementado en Express vía middleware en 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). - HTTP directo:
GET https://api.siax-system.net/api/errores?app_origen=Help Desk(con headerx-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 como objetivo verificable y en .agente/proyecto_errores.md.
Variables de Entorno (.env)
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:
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
# 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: Identidad del agente asignada por sigma-robot.
- README.md: Manual y guía general para operadores humanos.
- .agente/infraestructura.md: Espejo 100% sincronizado del inventario global.
- .agente/proyecto_memoria.md: Memoria técnica y decisiones de diseño.
- .agente/proyecto_estructura.md: Árbol de archivos y tabla completa de endpoints HTTP.
- .agente/proyecto_errores.md: Bitácora de incidentes y problemas conocidos.
- .agente/objetivos.md: Registro de objetivos completados, en curso y pendientes.
- .agente/tareas.md: Bitácora de tareas, entregables completados y backlog.
- .agente/reglas.md: Reglas de seguridad y buenas prácticas del proyecto.
- .agente/ideas.md: Registro de propuestas e ideas en evaluación.