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
proyecto.md
+167 -98
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`
| 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 |
## Esquema de Base de Datos (MariaDB / MySQL)
### Tabla: `departments`
| 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 |
### 1. `companies`
Gestión de empresas u organizaciones multi-tenant con cuotas y plan.
### Tabla: `tickets`
| 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 |
### 2. `users`
Usuarios por empresa con soporte de login local o federado (`webcontrol`, `google`, `facebook`).
### Tabla: `ticket_respuestas`
| 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 |
### 3. `departments`
Departamentos o áreas de soporte por empresa.
## Roles y Permisos
### 4. `tickets`
Tickets de soporte técnico con prioridad, estado, agente asignado e historial.
| 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 |
### 5. `ticket_respuestas`
Mensajes y notas del hilo de discusión del ticket.
## Tecnologías
### 6. `ticket_visitas`
Despacho de visitas técnicas en terreno hacia `tareas.telcotronics.com` con `historial_json` para el timeline en vivo.
- **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
### 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 |
## Scripts
### 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 |
```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)
```
### 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 |
## Credenciales por defecto
### 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 |
- **Admin**: admin@helpdesk.com / 123456
---
## 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 |