help_desk/.agente/proyecto_estructura.md

# 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, 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 (incluye ticket_visitas)
│   └── 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
│   └── test_visita_flow.js          # Script CLI de prueba e integración end-to-end para FSM
├── 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
│   └── 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, 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)
    └── 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** | `/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) |