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

docs: actualizar documentacion tecnica, arquitectura y manuales de herramientas y QR

Browse Source
This commit is contained in:
pablinux
2026-11-01 09:28:45 -05:00
parent e71e531b51
commit 82b1a52524
8 changed files with 332 additions and 135 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agente/objetivos.md
+2
View File
@@ -19,6 +19,8 @@
| Fecha | Objetivo | Evidencia |
|---|---|---|
| 2026-11-01 | **OBJ-011:** Manifiestos Móviles QR y Etiquetas Térmicas para Cajas de Herramientas | Generación con `qrcode`, tokens criptográficos seguros, vistas públicas `/qr/set/:token` y `/qr/asignacion/:token` con badge de custodia en vivo y checklist interactivo, vista de impresión `/admin/herramientas/sets/:id/etiqueta` con CSS `@media print` a 95mm y suite `scripts/test_qr_flow.js` aprobada al 100%. |
| 2026-11-01 | **OBJ-010:** Gestión de Herramientas, Sets Temáticos, Custodia a Técnicos y Evidencia Fotográfica | Tablas `herramientas`, `herramientas_sets`, `herramientas_set_items`, `tecnico_herramientas_asignaciones`, modelos `Herramienta*.js`, uploader seguro `config/uploader.js` con MIME check y hash de archivo, pruebas `scripts/test_foto_flow.js` al 100% y despliegue a CT 132. |
| 2026-10-20 | **OBJ-009:** VirtualHost Apache y SSL en Servidor-web (`192.168.10.109`) para `soporte.sigmac.app` | VirtualHost configurado con certificado Let's Encrypt y proxy reverso hacia `http://192.168.10.160:3008/`. Verificado: `curl -sI https://soporte.sigmac.app/login` responde HTTP 200 OK con cookies de sesión de Help Desk |
| 2026-10-18 | **OBJ-008:** Coordinación y despliegue automatizado con SIAX Monitor y dominio `soporte.sigmac.app` | Script `desplegar.sh` adaptado con `servers.conf` y Feedback #25, orquestación de reinicio vía API REST de SIAX Monitor (`http://192.168.10.160:8080`), auditoría de PID (4075474) y socket LISTEN, y actualización de URL oficial `https://soporte.sigmac.app` en la ficha #35 del MCP de Infraestructura |
| 2026-10-17 | **OBJ-002:** Despliegue a Producción en CT 132 (`server-webapps`) y script `desplegar.sh` | Desplegado en `/home/user_apps/apps/help_desk`, servicio `siax-app-HELPDESK.service` activo (running) en systemd, respondiendo HTTP 200 en `http://192.168.10.160:3008/` y estado en MCP actualizado a `ACTIVE` |
.agente/proyecto_estructura.md
+37 -7
View File
@@ -30,11 +30,15 @@ help_desk/
│ ├── 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)
│ ├── 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
│ └── test_visita_flow.js # Script CLI de prueba e integración end-to-end para FSM
│ ├── 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/
@@ -42,14 +46,19 @@ help_desk/
│ ├── 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 y asignación)
│ ├── admin.js # Rutas para administradores (usuarios, departamentos)
│ ├── 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
│ ├── 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
@@ -65,12 +74,19 @@ help_desk/
│ │ └── 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
│ │ ├── 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
│ │ ├── 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/
@@ -84,6 +100,8 @@ help_desk/
│ ├── 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
```
@@ -122,6 +140,17 @@ help_desk/
| **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 |
@@ -138,6 +167,7 @@ help_desk/
| `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 |
.agente/proyecto_memoria.md
+12 -1
View File
@@ -67,6 +67,13 @@
- **Contrato Operativo con `app_tareas` (ID 89):** Despacho M2M de visitas técnicas en terreno (`POST /api/external/tareas`), trazabilidad GPS en sitio, avance de checklist de campo, fotos de evidencias y firma digital del cliente en canvas móvil, con sincronización de estado y cierre automático en el hilo del ticket.
- **Ciclo de Retroalimentación con `app_ideas` (ID 82):** Canalización de solicitudes de funciones y patrones de fallas hacia el Canvas estratégico de ideas. Se acordó que Help Desk enviará resúmenes técnicos saneados bajo control manual del agente técnico (sin datos personales de clientes), ingresando como *candidata_revision* antes de que `app_ideas` genere tareas definitivas hacia `app_tareas`.
12. **Módulo de Inventario de Herramientas, Sets de Maletines, Evidencia Fotográfica y Manifiesto Móvil QR:**
- **Catálogo de Herramientas & Sets:** Control de herramientas individuales con código, serie, marca, modelo, estado operativo y fotos. Agrupación en kits/sets temáticos para maletines de trabajo (cobre, fibra óptica, herramientas básicas de cuadrilla).
- **Asignación de Custodia a Técnicos:** Registro de entrega de herramientas tanto en dotación de bodega como vinculadas a visitas técnicas FSM, registrando condiciones físicas y fotos en la entrega y en la devolución.
- **Uploader Seguro de Fotografías (`config/uploader.js`):** Validador centralizado con control de MIME type (JPG, PNG, WEBP, GIF), nombres únicos seguros con timestamp + hash aleatorio, límite de 8MB por archivo y almacenamiento en `public/uploads/herramientas/` (ignorado en Git por `.gitignore`).
- **Generación e Impresión de Etiquetas QR Adhesivas:** Generación de códigos QR mediante librería nativa `qrcode`. Vista de impresión `/admin/herramientas/sets/:id/etiqueta` con CSS `@media print` diseñado específicamente a **95mm** para impresoras térmicas de stickers y etiquetas autoadhesivas de cajas.
- **Manifiesto Móvil Web Responsivo (`/qr/set/:token` y `/qr/asignacion/:token`):** Acceso público sin requerir login mediante tokens aleatorios de 24 caracteres hex (`crypto.randomBytes(12)`). Al escanear el QR físico con cualquier teléfono inteligente, el usuario accede a un manifiesto móvil con badge de estado en vivo (**EN BODEGA / DISPONIBLE** vs **EN CUSTODIA TÉCNICA**), datos del custodio y un **Checklist interactivo** para verificar las herramientas presentes dentro del maletín durante inspecciones de inventario.
- **API Externa M2M (`/api/external/herramientas/sets`):** Consulta de sets y estado de disponibilidad protegida por `x-api-key` para aplicaciones hermanas del ecosistema.
---
@@ -75,13 +82,17 @@
- **Servidor:** MariaDB en `192.168.10.149:3306` (Contenedor CT 114)
- **Usuario:** `helpdesk`
- **Base de datos:** `help_desk`
- **Tablas:**
- **Tablas (10 tablas activas):**
- `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 [nullable], rol, provider, provider_id, avatar_url, 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).
- `ticket_visitas`: Visitas técnicas y tareas de campo vinculadas a tickets y al Hub de tareas (id, company_id, ticket_id, external_id, tecnico_email, tecnico_nombre, titulo, descripcion, ubicacion, fecha_visita, fecha_fin, estado, checklist_json, historial_json, created_at, updated_at).
- `herramientas`: Catálogo de herramientas individuales (id, company_id, codigo, nombre, descripcion, categoria, marca, modelo, numero_serie, estado, foto_url, created_at, updated_at).
- `herramientas_sets`: Kits y maletines temáticos (id, company_id, codigo, nombre, descripcion, foto_url, qr_token, is_active, created_at, updated_at).
- `herramientas_set_items`: Ítems asociados a cada set con su cantidad (id, set_id, herramienta_id, cantidad).
- `tecnico_herramientas_asignaciones`: Registro de custodia a técnicos con estado de entrega y devolución, fotos de evidencia y qr_token (id, company_id, set_id, herramienta_id, tecnico_email, tecnico_nombre, ticket_visita_id, fecha_asignacion, fecha_devolucion, estado, foto_entrega_url, foto_devolucion_url, condicion_entrega, condicion_devolucion, qr_token, created_at, updated_at).
---
.agente/tareas.md
+3
View File
@@ -10,6 +10,9 @@
| Fecha | Tarea / Entregable | Responsable | Archivos Afectados |
|---|---|---|---|
| 2026-11-01 | **Manifiesto Móvil Web Responsivo & Etiquetas QR para Cajas e Impresión Térmica** (Tokens seguros, checklist interactivo `/qr/set/:token`, impresión 95mm) | Agente IA | `routes/qr.js`, `views/public/*`, `views/admin/etiqueta_qr.ejs`, `views/admin/herramientas.ejs`, `config/setup.js`, `scripts/test_qr_flow.js` |
| 2026-11-01 | **Gestión de Evidencia Fotográfica y Auditoría Visual para Herramientas y Maletines** (Uploader seguro `uploader.js`, fotos en despacho/devolución) | Agente IA | `config/uploader.js`, `models/Herramienta*.js`, `routes/admin.js`, `routes/agent.js`, `scripts/test_foto_flow.js` |
| 2026-11-01 | **Módulo de Inventario de Herramientas, Sets y Asignaciones de Custodia FSM** (Tablas, modelos, dotación fija y visitas en terreno) | Agente IA | `models/Herramienta.js`, `models/HerramientaSet.js`, `models/HerramientaAsignacion.js`, `config/setup.js`, `routes/admin.js`, `routes/agent.js` |
| 2026-10-27 | **Integración M2M Help Desk ↔ sigma-robot (API `/api/external/tickets`, Idempotencia, Worker y Cron de 30min)** | Agente IA | `routes/api.js`, `models/Ticket.js`, `config/setup.js`, `scripts/sigma_robot_worker.js`, `app.js` |
| 2026-10-23 | **Publicación y Creación de Repositorio en Gitea (`git.telcotronics.net/pablinux/help_desk.git`)** | Agente IA | Git remoto, Gitea API (Repo ID 38) |
| 2026-10-23 | **Conexión y Verificación de Bitácora de Errores (`ak_helpdesk_...` en API-SIGMA-WEBCONTROL)** | Agente IA | `.env`, `webControl.api_key`, `scripts/consultar_errores.js` |
README.md
+36 -1
View File
@@ -41,6 +41,35 @@ Integrado bidireccionalmente con **`tareas.telcotronics.com`**:
---
## 🧰 Módulo de Inventario de Herramientas, Sets y Manifiesto QR
Permite la administración integral del parque de herramientas, maletines de trabajo y control de custodia de los técnicos en campo:
- **Catálogo de Herramientas & Sets Temáticos:**
- Alta de herramientas individuales con código patrimonial, marca, modelo, número de serie, estado operativo (`disponible`, `en_uso`, `en_reparacion`, `baja`) y foto.
- Creación de **Sets / Kits de Herramientas** (ej. *Maletín de Fusión de Fibra Óptica*, *Kit de Redes Cobre*, *Caja Básica de Cuadrilla*) agrupando múltiples herramientas con cantidades definidas y fotografía referencial del maletín.
- **Asignación y Custodia a Técnicos:**
- Asignación de custodia a técnicos de campo (sincronizados desde el Hub FSM o usuarios locales).
- Modalidad dual: **Dotación fija de bodega** o vinculación directa a un **Ticket de Visita Técnica FSM**.
- Registro de condición de entrega y condición de retorno a bodega.
- **Evidencia Fotográfica y Auditoría Visual:**
- Subida segura de imágenes (`config/uploader.js`) para herramientas individuales, maletines completos, foto del estado al momento del despacho/entrega y foto de retorno al almacén.
- **Generación e Impresión de Etiquetas QR:**
- Generación de códigos QR vectoriales de alta resolución para pegar en las cajas y maletines físicos.
- Vista de impresión optimizada (`/admin/herramientas/sets/:id/etiqueta`) con CSS `@media print` diseñado a **95mm** para impresoras térmicas de etiquetas adhesivas o impresión en papel estándar.
- Incluye código del set, nombre, lista de herramientas empaquetadas, código QR y enlace directo.
- **Manifiesto Móvil Web Responsivo (`/qr/set/:token` y `/qr/asignacion/:token`):**
- Cualquier operador, técnico o auditor puede escanear el código QR con la cámara de su teléfono inteligente **sin requerir inicio de sesión previo** gracias a tokens criptográficos seguros (`crypto.randomBytes(12)`).
- Despliega en tiempo real:
- Estado de custodia en vivo (badge distintivo: **EN BODEGA / DISPONIBLE** vs **EN CUSTODIA TÉCNICA**).
- Fotografía referencial del set.
- Técnico responsable y ticket FSM relacionado si se encuentra asignado.
- **Checklist interactivo de verificación:** Permite marcar casilla por casilla las herramientas presentes dentro de la caja para inventarios rápidos en almacén o cuadrilla.
- **API Externa M2M (`/api/external/herramientas/sets`):**
- Endpoint seguro autenticado vía `x-api-key` para consulta de sets y stock disponible desde aplicaciones hermanas (`app_tareas`, bots o dashboards).
---
## 🛠️ Stack Tecnológico
- **Backend:** Node.js 20+ con Express 5.2.
@@ -145,9 +174,15 @@ El proyecto está preparado para desplegarse de manera automatizada conforme a l
## 🧪 Pruebas y Auditoría
```bash
# Verificar flujo completo de visitas técnicas contra el Hub
# Verificar flujo completo de visitas técnicas contra el Hub FSM
node scripts/test_visita_flow.js
# Verificar flujo de inventario, subida de fotos y asignaciones de custodia
node scripts/test_foto_flow.js
# Verificar generación de tokens, códigos QR y manifiestos móviles
node scripts/test_qr_flow.js
# Consultar la bitácora centralizada de errores (API-SIGMA-WEBCONTROL)
npm run check:errors
```
agents.md
+11 -1
View File
@@ -87,6 +87,16 @@ Proveer un sistema web robusto, ágil y seguro para la gestión integral de tick
- **app_tareas (ID 89):** Despacho M2M de visitas técnicas FSM, timeline en vivo, firmas de clientes y checklist de campo.
- **app_ideas (ID 82):** Canalización de tickets recurrentes, solicitudes de clientes (feature requests) y mejoras hacia el Canvas estratégico de ideas para evaluación y posterior generación de objetivos.
### 8. Gestión de Herramientas, Sets y Manifiestos QR FSM (`/admin/herramientas`, `/agent/herramientas`, `/qr/set/:token`)
**Estado: ✅ Operativo**
- Inventario físico multi-tenant de herramientas individuales (`herramientas`) con código, serie, marca, modelo, estado y foto.
- Configuración de Sets/Kits de herramientas (`herramientas_sets` y `herramientas_set_items`) para maletines de cuadrilla.
- Asignación de custodia a técnicos (`tecnico_herramientas_asignaciones`) con soporte para dotación fija o vinculación a tickets de visita FSM.
- Evidencia fotográfica de recepción, entrega en campo y devolución a bodega mediante uploader seguro (`config/uploader.js`).
- Generación de códigos QR e impresión de etiquetas adhesivas térmicas a 95mm (`/admin/herramientas/sets/:id/etiqueta`).
- Manifiesto móvil web responsivo accesible por token criptográfico público (`/qr/set/:token` y `/qr/asignacion/:token`) con badge de custodia en vivo y checklist interactivo.
- API M2M externa `/api/external/herramientas/sets` para sincronización de inventario con otras aplicaciones del ecosistema.
---
@@ -109,7 +119,7 @@ Proveer un sistema web robusto, ágil y seguro para la gestión integral de tick
- Dominio público: `https://soporte.sigmac.app` (Proxy reverso en `Servidor-web` CT 109 `192.168.10.109`).
- **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`).
- Base de datos: `help_desk` (Verificada: 10 tablas activas: `companies`, `departments`, `ticket_respuestas`, `tickets`, `users`, `ticket_visitas`, `herramientas`, `herramientas_sets`, `herramientas_set_items`, `tecnico_herramientas_asignaciones`).
- Usuario: `helpdesk`.
- **Puerto Local de Ejecución:** `3008`.
memoria.md
+64 -27
View File
@@ -1,41 +1,78 @@
# Memoria del Proyecto - Help Desk
# Memoria Técnica del Proyecto — Help Desk
## Fecha de inicio
16 de Mayo, 2026
## Stack tecnológico
- Node.js con Express 5
- EJS como motor de plantillas
- MariaDB/MySQL con mysql2
- express-session + bcryptjs para autenticación
- Bootstrap 5 + Font Awesome para UI
- morgan, connect-flash, express-fileupload
## Stack Tecnológico
- **Runtime / Backend:** Node.js 20+ con Express 5.2.
- **Motor de Vistas:** EJS 5 con partials modulares.
- **Base de Datos:** MariaDB 10.11 / MySQL (`mysql2/promise`) en CT 114 (`192.168.10.149:3306`).
- **Autenticación y Sesiones:** `express-session`, `cookie-parser`, `bcryptjs`.
- **Integraciones de Identidad:** SIGMA WebControl API, Google Identity Services (GIS), Facebook OAuth.
- **Frontend / UI:** Bootstrap 5.3 + Font Awesome 6 (CDN) + Estilos custom (`public/css/style.css`).
- **Middlewares y Utilidades:** `morgan`, `connect-flash`, `express-fileupload`, `qrcode`.
- **Integración FSM:** API REST externa contra `tareas.telcotronics.com` (CT 132 `192.168.10.160:3000`).
- **Auditoría de Errores:** Integración con API-SIGMA-WEBCONTROL (`192.168.10.149:3005`).
## Decisiones de arquitectura
---
1. **MySQL vs MongoDB**: El usuario eligió MySQL (MariaDB) como base de datos, consistente con su stack habitual en otros proyectos Node.
## Decisiones de Arquitectura
2. **express-session vs JWT**: Se optó por sesiones del lado del servidor con express-session en lugar de JWT para mantener la compatibilidad con connect-flash y facilitar mensajes flash. Aunque se instaló jsonwebtoken, no se está utilizando activamente.
1. **MariaDB Relacional vs NoSQL:**
- Se utiliza MariaDB en CT 114 (`192.168.10.149:3306`), garantizando integridad referencial estricta, llaves foráneas y consistencia transaccional multi-tenant.
3. **3 roles de usuario**: admin, agent, client. Cada uno con acceso a rutas específicas protegidas por middleware de autenticación.
2. **express-session vs JWT:**
- Se utiliza `express-session` con almacenamiento de sesión del lado del servidor para el portal web renderizado con EJS, facilitando el manejo de mensajes flash (`connect-flash`) y redirecciones seguras. `jsonwebtoken` permanece reservado para APIs REST.
4. **EJS con partials**: Se usan partials (header.ejs, footer.ejs, navbar.ejs, sidebar.ejs) en lugar de layouts para mantener la estructura simple sin dependencias extra.
3. **Arquitectura Multi-tenant SaaS:**
- La tabla maestra `companies` gobierna el aislamiento lógico. Todas las entidades operativas (`users`, `departments`, `tickets`, `ticket_visitas`, `herramientas`, `herramientas_sets`, `tecnico_herramientas_asignaciones`) incorporan la clave foránea `company_id`.
- Soporte para cuotas máximas de usuarios y tickets por plan (`free`, `pro`, `enterprise`).
5. **Bootstrap 5 desde CDN**: No se incluye Bootstrap local para mantener el proyecto liviano. Se carga desde CDN junto con Font Awesome.
4. **4 Roles de Usuario con Control Granular (`middleware/auth.js`):**
- `superadmin`: Acceso a `/saas/companies` para gestión global de organizaciones.
- `admin`: Administración de agentes, clientes, departamentos, inventario de herramientas y configuraciones de la empresa.
- `agent`: Bandeja operativa de tickets, triaje, respuestas, despacho de visitas técnicas FSM y asignación de herramientas.
- `client`: Apertura y seguimiento de incidencias propias.
## Base de Datos
- Servidor MariaDB en `192.168.10.149`
- Usuario: `helpdesk`@`192.168.10.101`
- Base de datos: `help_desk`
- 4 tablas: users, departments, tickets, ticket_respuestas
5. **Estrategia Multicanal de Autenticación & Mascota Bot:**
- Los clientes del ecosistema validan sus credenciales contra SIGMA WebControl (`api.siax-system.net`) con aprovisionamiento transparente en MariaDB.
- Los nuevos clientes pueden autenticar mediante Google Identity Services (GIS) y Facebook Login.
- El personal técnico (`superadmin`, `admin`, `agent`) utiliza la consola local MariaDB protegida por `bcryptjs`.
- Mascota oficial del Bot de Soporte (`/img/bot-soporte.svg`, `/img/bot-soporte.png`) integrada en la interfaz de login.
## Puerto del servidor
- El servidor corre en el puerto 3008
6. **Módulo FSM — Despacho y Trazabilidad de Campo:**
- Integrado bidireccionalmente con `tareas.telcotronics.com` (CT 132 `192.168.10.160:3000`).
- Sincronización en vivo de nómina de técnicos, despacho con checklist, dirección y coordenadas GPS.
- Mini-Timeline de 4 hitos operativos en el ticket: Programada ➔ Check-in GPS en sitio ➔ Avance de checklist con fotos ➔ Cierre con firma digital del cliente.
- Automatización de estados y mensajes en el hilo del ticket al programar o completar la visita.
## Pendientes / Notas
- La contraseña del usuario helpdesk se cambió de `password` a `5oyN9zvq/2K8b1Fs`
- jsonwebtoken está instalado como dependencia pero no se usa activamente
- El frontend es funcional pero se puede mejorar
7. **Módulo de Inventario de Herramientas, Sets y Manifiesto QR:**
- Inventario físico multi-tenant de herramientas individuales (`herramientas`) con código, serie, marca, modelo, estado (`disponible`, `en_uso`, `en_reparacion`, `baja`) y fotografía.
- Agrupación en **Sets / Kits de Herramientas** (`herramientas_sets` y `herramientas_set_items`) para maletines de trabajo (fusión de fibra, redes de cobre, kits de cuadrilla).
- Asignación de custodia a técnicos (`tecnico_herramientas_asignaciones`) en dos modalidades: dotación fija de bodega o vinculada a un ticket de visita técnica FSM.
- Subida y almacenamiento seguro de imágenes (`config/uploader.js`) para evidencias de herramientas, maletines, estado de entrega y estado de devolución.
- Generación de códigos QR e impresión térmica adhesiva (`/admin/herramientas/sets/:id/etiqueta`) optimizada a 95mm vía `@media print`.
- Manifiesto móvil web responsivo (`/qr/set/:token` y `/qr/asignacion/:token`) con badge de custodia en vivo (EN BODEGA vs EN CUSTODIA) y checklist interactivo para auditoría de maletines en terreno o almacén.
- Endpoint externo M2M `/api/external/herramientas/sets` protegido por API Key.
## Problemas conocidos
- node --watch no funciona correctamente en algunos entornos; usar nodemon como alternativa
8. **Despliegue a Producción y Orquestación con SIAX Monitor:**
- Servidor: CT 132 `192.168.10.160` (`server-webapps`), puerto 3008.
- Dominio público: `https://soporte.sigmac.app` mediante proxy reverso en CT 109 (`192.168.10.109:443`).
- Administrado por la unidad systemd `siax-app-HELPDESK.service` y supervisado por **SIAX Monitor** (`:8080`).
- Despliegue atómico automatizado vía `./desplegar.sh`.
- Registrado oficialmente en el MCP de Infraestructura como **Servicio ID 35**.
---
## Esquema de Base de Datos (10 Tablas Activas)
- `companies`: Gestión de tenants SaaS y cuotas.
- `users`: Usuarios del sistema con soporte multicanal (`provider`, `provider_id`, `rol`, `company_id`).
- `departments`: Áreas o departamentos de soporte técnico.
- `tickets`: Tickets de soporte con aislamiento por empresa, prioridad y estado.
- `ticket_respuestas`: Mensajes, notas y respuestas del hilo del ticket.
- `ticket_visitas`: Visitas técnicas y tareas de campo FSM con timeline en `historial_json`.
- `herramientas`: Catálogo de herramientas individuales con código, serie, estado y `foto_url`.
- `herramientas_sets`: Kits o maletines de herramientas con código, `foto_url` y `qr_token`.
- `herramientas_set_items`: Relación Many-to-Many entre sets y herramientas con cantidad requerida.
- `tecnico_herramientas_asignaciones`: Registro de custodia a técnicos con estado (`activa`, `devuelta`), fotos de entrega/devolución y `qr_token`.
proyecto.md
+168 -99
View File
@@ -1,125 +1,194 @@
# Help Desk - Documentación del Proyecto
# Help Desk — Documentación del Proyecto
## Estructura del Proyecto
```
```text
help_desk/
├── app.js # Entry point, configura Express
├── package.json # Dependencias y scripts
├── .env # Variables de entorno
├── .gitignore
├── 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 # Conexión a MySQL/MariaDB con mysql2
│ ├── init.sql # Script SQL inicial
│ └── setup.js # Script Node para inicializar BD
│ ├── 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 # Middleware: isAuthenticated, isAdmin, isAgent, isClient
│ └── auth.js # Middlewares: isAuthenticated, roles y loadCompany
├── models/
│ ├── User.js # CRUD usuarios
│ ├── Ticket.js # CRUD tickets + respuestas
│ └── Department.js # CRUD departamentos
│ ├── 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, Register, Logout
│ ├── client.js # Rutas para clientes (ver/crear tickets)
│ ├── agent.js # Rutas para agentes (gestionar tickets)
│ └── admin.js # Rutas para admin (usuarios, departamentos)
│ ├── 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 + navbar
│ │ ├── footer.ejs # Scripts + cierre
│ │ ├── navbar.ejs # Barra de navegación superior
│ │ └── sidebar.ejs # Menú lateral por rol
│ │ ├── 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
│ │ └── register.ejs
│ │ ├── login.ejs # Login con pestañas (Clientes vs Personal Técnico)
│ │ └── register.ejs # Registro de clientes
│ ├── client/
│ │ ├── dashboard.ejs # Lista de tickets del cliente
│ │ ├── new-ticket.ejs # Formulario crear ticket
│ │ └── view-ticket.ejs # Ver ticket + respuestas
│ │ ├── 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 # Panel con todos los tickets
│ │ └── view-ticket.ejs # Ver ticket + responder + cambiar estado
│ └── admin/
│ ├── dashboard.ejs # Estadísticas y accesos rápidos
│ ├── users.ejs # CRUD usuarios
│ ├── create-user.ejs # Formulario crear usuario
│ └── departments.ejs # CRUD departamentos con modales
├── public/
│ ├── css/
│ │ └── style.css # Estilos personalizados
│ └── js/
│ └── main.js # JS del lado cliente
└── proyecto.md, memoria.md, readme.md
│ │ ├── 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)
```
## Base de Datos (MariaDB/MySQL)
---
### Tabla: `users`
## 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 | ID único |
| nombre | VARCHAR(100) NOT NULL | Nombre completo |
| email | VARCHAR(100) NOT NULL UNIQUE| Correo electrónico |
| password | VARCHAR(255) NOT NULL | Hash bcrypt |
| rol | ENUM('admin','agent','client') DEFAULT 'client' | Rol del usuario |
| created_at | TIMESTAMP DEFAULT CURRENT_TIMESTAMP | Fecha de registro |
|---|---|---|
| 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 |
### Tabla: `departments`
### 8. `herramientas_sets`
| Campo | Tipo | Descripción |
|------------|-----------------------------|---------------------------|
| id | INT AUTO_INCREMENT PK | ID único |
| nombre | VARCHAR(100) NOT NULL | Nombre del departamento |
| descripcion| TEXT | Descripción |
| created_at | TIMESTAMP DEFAULT CURRENT_TIMESTAMP | Fecha de creació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 |
### Tabla: `tickets`
### 9. `herramientas_set_items`
| Campo | Tipo | Descripción |
|-------------|-----------------------------|------------------------------|
| id | INT AUTO_INCREMENT PK | ID único (# ticket) |
| user_id | INT NOT NULL FK → users.id | Cliente creador |
| department_id| INT FK → departments.id | Departamento |
| asunto | VARCHAR(200) NOT NULL | Asunto del ticket |
| mensaje | TEXT NOT NULL | Descripción del problema |
| status | ENUM('abierto','en_progreso','cerrado') DEFAULT 'abierto' | Estado |
| prioridad | ENUM('baja','media','alta','critica') DEFAULT 'media' | Prioridad |
| assigned_to | INT FK → users.id | Agente asignado |
| created_at | TIMESTAMP DEFAULT CURRENT_TIMESTAMP | Fecha de creación |
| updated_at | TIMESTAMP ON UPDATE | Última actualizació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 |
### Tabla: `ticket_respuestas`
### 10. `tecnico_herramientas_asignaciones`
| Campo | Tipo | Descripción |
|-----------|-----------------------------|------------------------|
| id | INT AUTO_INCREMENT PK | ID único |
| ticket_id | INT NOT NULL FK → tickets.id| Ticket relacionado |
| user_id | INT NOT NULL FK → users.id | Quién respondió |
| mensaje | TEXT NOT NULL | Contenido respuesta |
| created_at| TIMESTAMP DEFAULT CURRENT_TIMESTAMP | Fecha de respuesta |
|---|---|---|
| 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 |
## Roles y Permisos
---
| Rol | Descripción |
|--------|------------------------------------------|
| admin | Acceso total: gestiona usuarios, deptos, tickets |
| agent | Gestiona tickets asignados, responde, cambia estado |
| client | Crea tickets, ve sus propios tickets, responde |
## Rutas y Endpoints Principales
## Tecnologías
- **Backend**: Node.js + Express 5
- **Motor de plantillas**: EJS
- **Base de Datos**: MariaDB/MySQL (mysql2)
- **Autenticación**: express-session + bcryptjs
- **Frontend**: Bootstrap 5 + Font Awesome
- **Middleware**: morgan, connect-flash, express-fileupload
## Scripts
```bash
npm start # Iniciar servidor producción
npm run dev # Iniciar con nodemon (auto-reload)
node config/setup.js # Inicializar BD (crear tablas + datos seed)
```
## Credenciales por defecto
- **Admin**: admin@helpdesk.com / 123456
| 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 |