help_desk/proyecto.md

# Help Desk — Documentación del Proyecto

## Estructura del Proyecto

```text
help_desk/
├── app.js                          # Entry point, configuración de Express 5 y middlewares
├── package.json                     # Dependencias, scripts y metadatos
├── package-lock.json
├── .env.example                     # Plantilla de variables de entorno
├── .gitignore                       # Ignorados por Git (uploads, secrets, node_modules)
├── servers.conf.example             # Plantilla de destinos de despliegue para desplegar.sh
├── id_agente.md                     # Identidad del agente en sigma-robot (Agente ID 90)
├── README.md                        # Guía general del proyecto
├── agents.md                        # Documento maestro para agentes IA
├── memoria.md                       # Resumen técnico y decisiones de arquitectura
├── proyecto.md                      # Estructura del proyecto, tablas y rutas
├── init.sh                          # Script interactivo de gestión local
├── desplegar.sh                     # Script de despliegue automatizado con SIAX Monitor
├── siax-app-HELPDESK.service        # Unidad systemd supervisada en CT 132
├── config/
│   ├── db.js                        # Pool de conexión a MariaDB (mysql2/promise)
│   ├── init.sql                     # Script SQL relacional inicial
│   ├── setup.js                     # Script de inicialización, migraciones y seeds
│   ├── uploader.js                  # Subida segura de imágenes con validación MIME
│   ├── errorReporter.js             # Reporter de errores hacia API-SIGMA-WEBCONTROL
│   └── tareasHubService.js          # Cliente de integración con tareas.telcotronics.com
├── middleware/
│   └── auth.js                      # Middlewares: isAuthenticated, roles y loadCompany
├── models/
│   ├── Company.js                   # CRUD y cuotas de empresas SaaS
│   ├── User.js                      # CRUD y autenticación de usuarios
│   ├── Department.js                # CRUD departamentos
│   ├── Ticket.js                    # CRUD tickets y respuestas
│   ├── TicketVisita.js              # Modelo y timeline de visitas FSM
│   ├── Herramienta.js               # Catálogo de herramientas individuales
│   ├── HerramientaSet.js            # Kits y maletines de herramientas
│   └── HerramientaAsignacion.js     # Custodia de herramientas a técnicos
├── routes/
│   ├── auth.js                      # Login multicanal, OAuth social y logout
│   ├── client.js                    # Panel y tickets del cliente
│   ├── agent.js                     # Triaje, visitas FSM y herramientas para agentes
│   ├── admin.js                     # Gestión de usuarios, departamentos, herramientas y etiquetas QR
│   ├── saas.js                      # Panel superadmin de tenants
│   ├── company.js                   # Ajustes de empresa
│   ├── api.js                       # Endpoints externos M2M (tickets, sets)
│   └── qr.js                        # Rutas públicas para escaneo móvil de QR (/qr/set, /qr/asignacion)
├── views/
│   ├── partials/
│   │   ├── header.ejs               # Head HTML y estilos
│   │   ├── footer.ejs               # Scripts de Bootstrap y modales
│   │   ├── navbar.ejs               # Barra superior con selector de empresa y perfil
│   │   └── sidebar.ejs              # Menú lateral dinámico por rol
│   ├── auth/
│   │   ├── login.ejs                # Login con pestañas (Clientes vs Personal Técnico)
│   │   └── register.ejs             # Registro de clientes
│   ├── client/
│   │   ├── dashboard.ejs            # Tickets propios del cliente
│   │   ├── new-ticket.ejs           # Formulario para abrir ticket
│   │   └── view-ticket.ejs          # Conversación y estado del ticket
│   ├── agent/
│   │   ├── dashboard.ejs            # Bandeja de tickets general
│   │   ├── view-ticket.ejs          # Detalle, asignación, timeline FSM y notas
│   │   └── herramientas.ejs         # Consulta de herramientas y maletines para agentes
│   ├── admin/
│   │   ├── dashboard.ejs            # Métricas del tenant
│   │   ├── users.ejs                # Gestión de usuarios
│   │   ├── create-user.ejs          # Alta de agentes/administradores
│   │   ├── departments.ejs          # Departamentos de soporte
│   │   ├── herramientas.ejs         # Gestión integral de herramientas, sets y custodias
│   │   └── etiqueta_qr.ejs          # Vista de impresión térmica de etiquetas QR (95mm)
│   ├── public/
│   │   ├── qr_set.ejs               # Manifiesto móvil web responsivo del set escaneado
│   │   ├── qr_asignacion.ejs        # Manifiesto móvil de asignación de custodia
│   │   └── qr_error.ejs             # Vista de error de token QR no encontrado
│   ├── saas/
│   │   └── companies.ejs            # Gestión SaaS de organizaciones
│   └── company/
│       └── settings.ejs             # Ajustes de empresa
├── scripts/
│   ├── consultar_errores.js         # Consulta de errores en API-SIGMA-WEBCONTROL
│   ├── sigma_robot_worker.js        # Worker de sincronización y buzón sigma-robot
│   ├── test_visita_flow.js          # Test end-to-end de visitas FSM
│   ├── test_foto_flow.js            # Test de fotos y asignaciones de custodia
│   └── test_qr_flow.js              # Test de tokens y render de manifiestos QR
└── public/
    ├── css/style.css                # Estilos visuales del sistema
    ├── img/                         # Logos, favicon y bot-soporte.svg
    └── uploads/herramientas/        # Fotos subidas de herramientas y sets (.gitkeep)
```

---

## Esquema de Base de Datos (MariaDB / MySQL)

### 1. `companies`
Gestión de empresas u organizaciones multi-tenant con cuotas y plan.

### 2. `users`
Usuarios por empresa con soporte de login local o federado (`webcontrol`, `google`, `facebook`).

### 3. `departments`
Departamentos o áreas de soporte por empresa.

### 4. `tickets`
Tickets de soporte técnico con prioridad, estado, agente asignado e historial.

### 5. `ticket_respuestas`
Mensajes y notas del hilo de discusión del ticket.

### 6. `ticket_visitas`
Despacho de visitas técnicas en terreno hacia `tareas.telcotronics.com` con `historial_json` para el timeline en vivo.

### 7. `herramientas`
| Campo | Tipo | Descripción |
|---|---|---|
| id | INT AUTO_INCREMENT PK | Identificador único |
| company_id | INT NOT NULL FK | Tenant propietario |
| codigo | VARCHAR(50) NOT NULL | Código patrimonial o SKU |
| nombre | VARCHAR(150) NOT NULL | Nombre de la herramienta |
| descripcion | TEXT | Descripción o características |
| categoria | VARCHAR(50) | Categoría (fibra, red, electrica, etc.) |
| marca | VARCHAR(100) | Marca del fabricante |
| modelo | VARCHAR(100) | Modelo comercial |
| numero_serie | VARCHAR(100) | Número de serie físico |
| estado | ENUM('disponible','en_uso','en_reparacion','baja') | Estado operativo actual |
| foto_url | VARCHAR(255) | Ruta a la fotografía subida |
| created_at / updated_at | TIMESTAMP | Marcas temporales |

### 8. `herramientas_sets`
| Campo | Tipo | Descripción |
|---|---|---|
| id | INT AUTO_INCREMENT PK | Identificador único |
| company_id | INT NOT NULL FK | Tenant propietario |
| codigo | VARCHAR(50) NOT NULL | Código identificador del set o caja |
| nombre | VARCHAR(150) NOT NULL | Nombre del set (ej. Maletín Fusión) |
| descripcion | TEXT | Notas del kit o uso previsto |
| foto_url | VARCHAR(255) | Fotografía del set completo |
| qr_token | VARCHAR(64) UNIQUE | Token seguro para escaneo público sin login |
| is_active | TINYINT(1) DEFAULT 1 | Estado de activación del kit |
| created_at / updated_at | TIMESTAMP | Marcas temporales |

### 9. `herramientas_set_items`
| Campo | Tipo | Descripción |
|---|---|---|
| id | INT AUTO_INCREMENT PK | Identificador único |
| set_id | INT NOT NULL FK | Set al que pertenece |
| herramienta_id | INT NOT NULL FK | Herramienta vinculada |
| cantidad | INT NOT NULL DEFAULT 1 | Cantidad empaquetada |

### 10. `tecnico_herramientas_asignaciones`
| Campo | Tipo | Descripción |
|---|---|---|
| id | INT AUTO_INCREMENT PK | Identificador único |
| company_id | INT NOT NULL FK | Tenant propietario |
| set_id | INT NULL FK | Set asignado (si aplica) |
| herramienta_id | INT NULL FK | Herramienta individual (si aplica) |
| tecnico_email | VARCHAR(150) NOT NULL | Email del técnico custodio |
| tecnico_nombre | VARCHAR(150) NOT NULL | Nombre del técnico custodio |
| ticket_visita_id | INT NULL FK | Visita FSM vinculada (si aplica) |
| fecha_asignacion | DATETIME NOT NULL | Fecha/hora del despacho de custodia |
| fecha_devolucion | DATETIME NULL | Fecha/hora de retorno a bodega |
| estado | ENUM('activa','devuelta') | Estado de la custodia |
| foto_entrega_url | VARCHAR(255) | Foto de evidencia al entregar al técnico |
| foto_devolucion_url | VARCHAR(255) | Foto de evidencia al retornar a bodega |
| condicion_entrega | TEXT | Estado físico en la entrega |
| condicion_devolucion | TEXT | Estado físico en la devolución |
| qr_token | VARCHAR(64) UNIQUE | Token seguro para escaneo del acta de custodia |
| created_at / updated_at | TIMESTAMP | Marcas temporales |

---

## Rutas y Endpoints Principales

| Ruta | Rol / Permiso | Descripción |
|---|---|---|
| `GET /login`, `POST /login` | Público | Autenticación multicanal |
| `POST /auth/google`, `/auth/facebook` | Público | Login social OAuth |
| `GET /client/dashboard` | `client` | Panel de tickets del cliente |
| `GET /agent/dashboard` | `agent` | Bandeja de tickets |
| `POST /agent/ticket/:id/visita` | `agent` | Programación de visita FSM al Hub |
| `POST /agent/ticket/:id/visita/sync` | `agent` | Sincronización en vivo de timeline y firma |
| `GET /agent/herramientas` | `agent` | Consulta de herramientas disponibles |
| `GET /admin/herramientas` | `admin` | CRUD de herramientas, sets y asignación de custodia |
| `POST /admin/herramientas` | `admin` | Alta de herramienta con soporte para subida de foto |
| `POST /admin/herramientas/sets` | `admin` | Creación de set de herramientas con foto |
| `POST /admin/herramientas/sets/:id/items` | `admin` | Adición de herramientas al set |
| `POST /admin/herramientas/asignar` | `admin` | Asignación de custodia a técnico con foto de entrega |
| `POST /admin/herramientas/asignaciones/:id/devolver` | `admin` | Retorno a bodega con foto y condición |
| `GET /admin/herramientas/sets/:id/etiqueta` | `admin` | Vista de impresión térmica de etiqueta QR (95mm) |
| `GET /qr/set/:token` | **Público** | **Manifiesto móvil web responsivo con checklist interactivo** |
| `GET /qr/asignacion/:token` | **Público** | Manifiesto móvil de asignación de custodia |
| `GET /api/external/herramientas/sets` | API Key | Endpoint M2M para consulta externa de sets |
| `GET /saas/companies` | `superadmin` | Gestión de empresas y planes SaaS |