Estructura del Proyecto — Help Desk

Árbol de Archivos

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, servers.conf)
├── servers.conf.example             # Plantilla de destinos de producción para desplegar.sh
├── servers.conf                     # Destinos de despliegue locales (ignorado por Git)
├── 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
├── init.sh                          # Script bash interactivo para gestión y entorno local
├── desplegar.sh                     # Script de despliegue coordinado con SIAX Monitor (:8080)
├── siax-app-HELPDESK.service        # Unidad de servicio systemd gestionada por SIAX en CT 132
├── .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
│   ├── tareas.md                    # Bitácora de tareas, entregables y backlog
│   ├── 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
│   ├── uploader.js                  # Manejo y validación de subida de imágenes
│   └── tareasHubService.js          # Conexión e integración con API externa tareas.telcotronics.com
├── scripts/
│   ├── consultar_errores.js         # Script CLI para consultar la bitácora centralizada de errores
│   ├── sigma_robot_worker.js        # Worker y sincronizador del chat sigma-robot
│   ├── test_visita_flow.js          # Script CLI de prueba e integración end-to-end para FSM
│   ├── test_foto_flow.js            # Script CLI de verificación de subida de fotos y asignaciones
│   └── test_qr_flow.js              # Script CLI de verificación de generación de QR y manifiestos
├── 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
│   ├── TicketVisita.js              # Modelo y persistencia para visitas técnicas y timeline FSM
│   ├── Herramienta.js               # Modelo y operaciones de catálogo de herramientas
│   ├── HerramientaSet.js            # Modelo de sets, maletines y empaquetado de herramientas
│   ├── HerramientaAsignacion.js     # Modelo de asignaciones de custodia a técnicos
│   └── 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, FSM y herramientas)
│   ├── admin.js                     # Rutas para administradores (usuarios, departamentos, herramientas, QR)
│   ├── saas.js                      # Rutas para superadmin (empresas y tenants)
│   ├── company.js                   # Rutas de ajustes de la empresa
│   ├── api.js                       # Endpoints M2M para tickets y herramientas
│   └── qr.js                        # Rutas públicas para manifiestos móviles escaneados por QR
├── 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
│   │   └── herramientas.ejs         # Catálogo de herramientas y sets para agentes
│   ├── 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
│   │   ├── herramientas.ejs         # Gestión integral de herramientas, sets y asignaciones
│   │   └── etiqueta_qr.ejs          # Vista de impresión térmica de etiqueta QR (95mm)
│   ├── public/
│   │   ├── qr_set.ejs               # Manifiesto móvil web responsivo con checklist
│   │   ├── qr_asignacion.ejs        # Manifiesto móvil web de acta de custodia
│   │   └── qr_error.ejs             # Vista amigable de error por token inválido
│   ├── saas/
│   │   └── companies.ejs            # Gestión de empresas para superadmin
│   └── company/
│       └── settings.ejs             # Configuración general de la empresa
└── public/
    ├── css/
    │   └── style.css                # Estilos personalizados, responsive, tabs y botones sociales
    ├── img/
    │   ├── logo.svg                 # Isotipo y logotipo base
    │   ├── favicon*                 # Favicons multi-resolución
    │   ├── bot-soporte.svg          # Mascota oficial vectorizada del Bot de Soporte
    │   ├── bot-soporte.png          # Mascota en raster alta resolución (192x192)
    │   └── bot-soporte-512.png      # Mascota en raster alta resolución (512x512)
    ├── uploads/
    │   └── herramientas/            # Almacenamiento de fotos de herramientas y sets
    └── 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 con selector de perfil (Clientes vs Staff)
POST	`/login`	Público	Valida credenciales (Clientes vía WebControl, Personal técnico vía MariaDB local)
POST	`/auth/google`	Público	Autenticación social con Google OAuth (GIS ID Token) para clientes
POST	`/auth/facebook`	Público	Autenticación social con Facebook OAuth (Graph API) para clientes
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/ticket/:id`	`isAuthenticated`, `isAgent`	Detalle del ticket, timeline de visitas y asignación
POST	`/agent/ticket/:id/respond`	`isAuthenticated`, `isAgent`	Envía respuesta oficial del agente
POST	`/agent/ticket/:id/status`	`isAuthenticated`, `isAgent`	Actualiza estado: `abierto`, `en_progreso`, `cerrado`
POST	`/agent/ticket/:id/assign`	`isAuthenticated`, `isAgent`	Asigna ticket a un agente específico
POST	`/agent/ticket/:id/visita`	`isAuthenticated`, `isAgent`	Programa visita técnica y crea tarea FSM en tareas.telcotronics.com
POST	`/agent/ticket/:id/visita/sync`	`isAuthenticated`, `isAgent`	Sincroniza estado, GPS, fotos y firma desde tareas.telcotronics.com
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	`/admin/herramientas`	`isAuthenticated`, `isAdmin`	Vista de inventario, sets y asignaciones de custodia
POST	`/admin/herramientas`	`isAuthenticated`, `isAdmin`	Alta de herramienta con subida de fotografía
POST	`/admin/herramientas/sets`	`isAuthenticated`, `isAdmin`	Creación de set/maletín con foto y token QR
POST	`/admin/herramientas/sets/:id/items`	`isAuthenticated`, `isAdmin`	Empaquetado de herramientas en el set
POST	`/admin/herramientas/asignar`	`isAuthenticated`, `isAdmin`	Asignación de custodia a técnico con foto de entrega
POST	`/admin/herramientas/asignaciones/:id/devolver`	`isAuthenticated`, `isAdmin`	Retorno de custodia a bodega con foto de devolución
GET	`/admin/herramientas/sets/:id/etiqueta`	`isAuthenticated`, `isAdmin`	Vista para impresión térmica de etiqueta QR (95mm)
GET	`/agent/herramientas`	`isAuthenticated`, `isAgent`	Catálogo de herramientas y sets para agentes
GET	`/qr/set/:token`	Público	Manifiesto móvil web responsivo con checklist interactivo
GET	`/qr/asignacion/:token`	Público	Manifiesto móvil web del acta de custodia asignada
GET	`/api/external/herramientas/sets`	API Key	Endpoint M2M para consulta externa de sets
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
`qrcode`	^1.5.4	Generador de códigos QR para etiquetas y manifiestos móviles
`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)

14 KiB Raw Blame History

Estructura del Proyecto — Help Desk

Árbol de Archivos

Tabla de Rutas HTTP

Dependencias Principales

14 KiB

Raw Blame History