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` |