pablinux/help_desk

Fork 0

Files

T

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

2026-11-01 09:28:45 -05:00

11 KiB

Raw Blame History

Help Desk — Documentación del Proyecto

Estructura del Proyecto

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

11 KiB Raw Blame History

Help Desk — Documentación del Proyecto

Estructura del Proyecto

Esquema de Base de Datos (MariaDB / MySQL)

1. companies

2. users

3. departments

4. tickets

5. ticket_respuestas

6. ticket_visitas

7. herramientas

8. herramientas_sets

9. herramientas_set_items

10. tecnico_herramientas_asignaciones