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

docs: actualizar documentacion integral (.agente/, README, agents.md) y sincronizar espejo maestro de infraestructura

Browse Source
This commit is contained in:
pablinux
2026-10-17 03:55:39 -05:00
parent 5324d5f433
commit 5a7dbf7ab9
8 changed files with 199 additions and 78 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.agente/ideas.md
+14 -1
View File
@@ -14,8 +14,21 @@
4. **SLA y métricas de resolución:** 4. **SLA y métricas de resolución:**
- Panel visual con tiempos medios de respuesta por departamento y alertas cuando un ticket supere 24/48 horas sin respuesta. - Panel visual con tiempos medios de respuesta por departamento y alertas cuando un ticket supere 24/48 horas sin respuesta.
5. **Timeline Operativo en Tiempo Real (SSE / WebSockets):**
- Actualización push en vivo en la tarjeta del ticket en `view-ticket.ejs` cuando el técnico en terreno haga check-in GPS, complete un ítem de checklist o suba una foto, eliminando la necesidad de sincronización manual.
6. **Notificaciones Automatizadas al Cliente vía WhatsApp (sigma-robot):**
- Disparo de aviso automático al cliente con el nombre del técnico y hora estimada de llegada cuando la visita cambie a `en_camino`.
7. **Encuesta de Calidad y Satisfacción (CSAT) Post-Visita:**
- Envío de enlace para calificación de 1 a 5 estrellas al cliente tras la finalización de la visita y firma digital.
8. **Validación de Geocerca (Geofencing) en Arribo:**
- Alerta visual para el agente si el check-in GPS del técnico difiere en más de 200 metros de las coordenadas registradas en el ticket.
--- ---
## Borradores y Exploraciones ## Borradores y Exploraciones
- *Borrador:* Integración de IA para categorización automática del departamento según el asunto y mensaje del ticket. - *Borrador:* Integración de IA (modelo local SIAX o Gemini) para categorización automática del departamento y sugerencia de respuestas frecuentes según el asunto del ticket.
- *Borrador:* Modo offline para la app móvil de técnicos con sincronización en diferido de evidencias fotográficas de campo.
.agente/infraestructura.md
+56 -55
View File
@@ -153,8 +153,8 @@ cada proyecto debera implementar un algoritomo de control de versiones de las ac
| **API-SIGMA-COMUNICACIONES** | `https://git.telcotronics.net/pablinux/API-SIGMA-COMUNICACIONES.git` | Node.js (Express) + MySQL | pablinux | 🔴 En desarrollo inicial | Gateway SaaS multi-tenant de canales de mensajería: cada cliente/organización crea y conecta su propio componente WhatsApp (bot o Meta), Telegram y redes sociales, aislado del resto. Independiente de `sigma-robot` (comunicaciones internas de Telcotronics). | | **API-SIGMA-COMUNICACIONES** | `https://git.telcotronics.net/pablinux/API-SIGMA-COMUNICACIONES.git` | Node.js (Express) + MySQL | pablinux | 🔴 En desarrollo inicial | Gateway SaaS multi-tenant de canales de mensajería: cada cliente/organización crea y conecta su propio componente WhatsApp (bot o Meta), Telegram y redes sociales, aislado del resto. Independiente de `sigma-robot` (comunicaciones internas de Telcotronics). |
| **MCP-Infraestructura** | `https://git.telcotronics.net/pablinux/MCP-INFRAESTRUCTURA.git` | TypeScript (@modelcontextprotocol/sdk) + Nuxt 3 + MySQL | pablinux | ✅ Activo | Servidor MCP y panel web para inventario y gestión en tiempo real de la infraestructura del ecosistema (hardware, servicios, apps IA y externos). Fuente de verdad en MySQL. | | **MCP-Infraestructura** | `https://git.telcotronics.net/pablinux/MCP-INFRAESTRUCTURA.git` | TypeScript (@modelcontextprotocol/sdk) + Nuxt 3 + MySQL | pablinux | ✅ Activo | Servidor MCP y panel web para inventario y gestión en tiempo real de la infraestructura del ecosistema (hardware, servicios, apps IA y externos). Fuente de verdad en MySQL. |
| **proxy_server_SRI** | `https://git.telcotronics.net/pablinux/proxy_server_SRI.git` | Python 3 (ThreadingHTTPServer + requests) | pablinux | ✅ Producción | Script proxy HTTP multihilo para consultas SRI en cascada de RUC y Cédula (Ecuador). Provee proxy y normalización para WebControl, SIGMAC y apps. | | **proxy_server_SRI** | `https://git.telcotronics.net/pablinux/proxy_server_SRI.git` | Python 3 (ThreadingHTTPServer + requests) | pablinux | ✅ Producción | Script proxy HTTP multihilo para consultas SRI en cascada de RUC y Cédula (Ecuador). Provee proxy y normalización para WebControl, SIGMAC y apps. |
| **cloud-sync** | `https://git.telcotronics.net/pablinux/Service-Cloud-SINC.git` | Rust 2021 + Axum 0.7 + SQLite | pablinux | 🟡 En mantenimiento / primer deploy | Servidor central de backup cifrado y consolas web. Puerto 3000 en 192.168.10.136. MCP ID: 12. | | **cloud-sync** | `https://git.telcotronics.net/pablinux/Service-Cloud-SINC.git` | Rust 2021 + Axum 0.7 + SQLite | pablinux | ✅ Activo / Producción HTTP | Servidor central de backup cifrado y consolas web. `192.168.10.136:3000`, health `ok` y harness remoto upload/list/download/restore verificados el 2026-10-17. HTTPS pendiente; MCP id 12. |
| **cloud-sync-clients** | [sin remoto aún — siax-amd] | Rust 2021 + Axum 0.7 + Tokio + aes-gcm + zstd | pablinux | 🟡 En desarrollo activo | Clientes server-to-server (Linux/Windows) para respaldo y cifrado local hacia cloud-sync. UI local :3001. MCP ID: 21. | | **cloud-sync-clients** | [sin remoto aún — siax-amd] | Rust 2021 + Axum 0.7 + Tokio + aes-gcm + zstd + rusqlite | pablinux | 🟡 Operativo / En desarrollo | Clientes server-to-server (Linux/Windows) para respaldo y cifrado local hacia cloud-sync. UI local :3001. Harness remoto validado (192.168.10.136:3000). MCP ID: 21. Agente ID: 42. |
--- ---
@@ -2561,74 +2561,75 @@ curl -X POST https://api.telcotronics.com/api/biometria/1001 \
## cloud-sync — Sistema de Backup Automático y Recuperación ante Desastre ## cloud-sync — Sistema de Backup Automático y Recuperación ante Desastre
cloud-sync es el servidor central de backup y recuperación ante desastre para clientes SIGMA. El agente de origen comprime y cifra archivos y dumps de SQLite, MySQL, MariaDB o bases compatibles antes de subirlos; el servidor almacena metadatos y contenido cifrado, sin recibir la clave del cliente. El repositorio incluye la API Rust y las consolas root/empresa; los ejecutables server-to-server viven en `cloud-sync-clients`. La integración Flutter/Java y la aplicación de escritorio siguen siendo objetivos posteriores. cloud-sync es un servidor central de backup y recuperación ante desastre para clientes SIGMA. Los datos se comprimen y cifran en el equipo de origen antes de subirlos; el servidor almacena contenido cifrado y metadatos, sin recibir la clave de cifrado. El repositorio mantiene la API Rust y las consolas root/empresa. Los ejecutables server-to-server están en el proyecto separado `cloud-sync-clients`; Tauri y los SDK Flutter/Java siguen pendientes.
| Parámetro | Valor | | Parámetro | Valor |
|---|---| |---|---|
| Repositorio Git | `https://git.telcotronics.net/pablinux/Service-Cloud-SINC.git` (privado, rama `main`, último commit documentado `babf1cd`) | | Repositorio Git | `https://git.telcotronics.net/pablinux/Service-Cloud-SINC.git` (privado, rama `main`) |
| Tecnología principal | Rust 2021 · Axum 0.7 · Tokio · rusqlite/SQLite · filesystem local · HTML/CSS/JavaScript para consolas web | | Tecnología principal | Rust 2021 · Axum 0.7 · Tokio · rusqlite/SQLite · filesystem local · HTML/CSS/JavaScript |
| Responsable | pablinux | | Responsable | pablinux |
| Estado actual | 🟡 Primer despliegue y smoke test HTTP aprobados; HTTPS público, auth Cloud dual y pruebas funcionales pendientes | | MCP de Infraestructura | Servicio id 12 · categoría `service` · estado `ACTIVE` |
| Equipo / código local | `siax-amd` (`192.168.10.100`) — `/home/pablinux/Projects/Rust/cloud monitor sinc` | | Estado operativo | Producción HTTP. El 2026-10-17 `/health` respondió HTTP 200, `status: ok`, versión `0.1.0`; harness remoto aislado completó upload/list/download/restore desde `cloud-sync-clients` |
| Servidor de producción | `192.168.10.136` — `/home/user_apps/apps/cloud-sync`; tmux activo, `/health` y consolas HTTP 200 verificados 2026-09-21 | | Servidor de producción | `192.168.10.136:3000`; ruta documentada `/home/user_apps/apps/cloud-sync` |
| Dominio público | Pendiente — VirtualHost HTTPS en Apache | | Hardware / CT | No hay entidad correspondiente a `192.168.10.136` en `infra://hardware`; sin CT confirmado. Feedback MISSING id 24, abierto el 2026-10-17 |
| Puerto interno | `3000` | | Dominio público / HTTPS | Sin dominio confirmado; HTTPS público pendiente |
| Última actualización | 2026-09-30 | | Feedback MCP | Cero reportes al iniciar la revisión del 2026-10-17; se abrió después el MISSING id 24 por la ficha de hardware faltante |
| Reglas de despliegue | Ninguna activa devuelta para alcance `cloud-sync` ni global. Hay una regla global SRI en borrador, no aplicable a este servicio |
| Última actualización | 2026-10-17 |
**BD que usa:** **Almacenamiento de datos:**
| Motor | Host | Nombre | Uso | | Motor | Host / ruta | Uso |
|---|---|---|---| |---|---|---|
| SQLite (embebida, bundled) | `192.168.10.136` — `/home/user_apps/apps/cloud-sync/data` | `server.db` | Empresas, cuotas, tokens, perfiles, sesiones, backups (metadata) y eventos | | SQLite embebida | `192.168.10.136` — `/home/user_apps/apps/cloud-sync/data/server.db` | Empresas, cuotas, perfiles, sesiones, metadatos de backups y eventos |
| SQLite (embebida, en el cliente) | Equipo de origen | `index.db` | Índice local de rutas, checksum SHA-256, backup_id y timestamps | | SQLite local del cliente | Equipo de origen — `index.db` | Rutas, checksum SHA-256, identificadores y timestamps de backups |
| Filesystem | Servidor `192.168.10.136` | Contenido cifrado de los backups, organizado por empresa |
**Servicios que consume y expone:** **Servicios que consume y expone:**
| Método | Endpoint | Auth | Descripción | | Método | Endpoint | Auth | Descripción |
|---|---|---|---| |---|---|---|---|
| GET | `/health` | — | Estado del servidor + info de disco | | GET | `/health` | — | Estado del servidor y capacidad de disco |
| POST | `/auth/token` | — | Login cliente (token UUID) → sesión Bearer | | POST | `/auth/token` | Token de empresa | Compatibilidad con agentes integradores |
| POST | `/auth/admin` | — | Login admin (argon2) → session token | | POST | `/auth/root`, `/auth/admin` | Usuario y contraseña | Login root; `/auth/admin` es alias compatible |
| POST | `/backup/upload` | Bearer token | Subir archivo cifrado (multipart) | | POST | `/auth/empresa` | Usuario y contraseña | Login de administrador de empresa |
| GET | `/backup/list` | Bearer token | Listar backups de la empresa | | POST | `/auth/logout` | Sesión Bearer | Revocar la sesión presentada |
| GET | `/backup/download/{id}` | Bearer token | Descargar backup para restore | | PUT | `/auth/admin/password` | Sesión root | Cambiar contraseña root |
| DELETE | `/backup/{id}` | Bearer token | Eliminar backup | | PUT | `/auth/empresa/password` | Sesión empresa | Cambiar contraseña de empresa |
| GET | `/me/storage` | Bearer token | Uso actual vs cuota asignada | | GET | `/empresa/cuenta` | Sesión empresa | Consultar su cuenta y perfil |
| GET | `/admin/storage` | X-Admin-Token | Capacidad CT146 + resumen global | | POST | `/backup/upload` | Bearer de integración | Subir backup cifrado multipart; límite configurado de hasta 10 GiB y cuota por empresa |
| GET/POST | `/admin/clientes` | X-Admin-Token | Listar / crear empresas | | GET | `/backup/list`, `/backup/status` | Bearer de integración | Listar respaldos y consultar estado |
| PUT | `/admin/clientes/{id}/cuota` | X-Admin-Token | Ajustar cuota por empresa | | GET | `/backup/download/{id}` | Bearer de integración o sesión empresa | Descargar respaldo cifrado propio |
| GET | `/admin/eventos` | X-Admin-Token | Log de auditoría | | DELETE | `/backup/{id}` | Bearer de integración | Eliminar backup propio |
| GET | `/root/` | — | Consola root para empresas, cuotas, estados, perfiles y accesos | | GET | `/me/storage` | Bearer de integración | Uso y cuota de empresa |
| GET | `/admin/` | — | Portal admin de empresa para consultar cuenta y descargar respaldos propios | | GET | `/admin/storage`, `/admin/clientes`, `/admin/eventos` | Sesión root | Capacidad, empresas y auditoría |
| GET | `/panel/` | Token de integración | Portal legado de cliente | | POST | `/admin/clientes` | Sesión root | Crear empresa y token de integración |
| MCP Infraestructura | `http://192.168.10.160:3006/sse` | Uso interno del ecosistema | Inventario; `cloud-sync` registrado como servicio id 12; `cloud-sync-clients` registrado como servicio id 21. No transporta errores de runtime | | PUT | `/admin/clientes/{id}/cuota`, `/estado` | Sesión root | Cambiar cuota o suspender empresa |
| API-SIGMA-WEBCONTROL | `https://api.siax-system.net/api/errores` | `x-api-key` por aplicación | Integración de bitácora de errores pendiente; no hay clave configurada | | GET/PUT | `/admin/clientes/{id}/perfil` | Sesión root | Consultar o editar perfil |
| PUT | `/admin/clientes/{id}/acceso` | Sesión root | Asignar o reemplazar acceso de empresa |
| GET | `/root/`, `/admin/`, `/panel/` | Según consola | Root, administrador de empresa y portal legado |
**Módulos disponibles:** **Estado de módulos y pendientes:**
| Módulo | Estado | | Módulo / tarea | Estado |
|---|---| |---|---|
| Servidor API REST (Axum) | ✅ Completo y probado | | API Rust y consola root | Implementadas y desplegadas; health HTTP verificado |
| Consola web admin (`/admin`) | ✅ Completa | | Consola de empresa | Implementada; validar login y flujos de consola en producción |
| Consola web panel cliente (`/panel`) | ✅ Completa | | Portal `/panel/` | Legado por token de integración |
| `cloud_sync_core` (librería Rust) — crypto, uploader, backup_engine, restore | ✅ Completo | | `cloud-sync-clients` | Proyecto separado, MCP id 21; harness aislado upload/list/download/restore pasó contra `192.168.10.136:3000` el 2026-10-17; Windows pendiente de validación funcional |
| Agente server-to-server (`cloud-sync-clients`) — archivos y dumps | ✅ Base Linux; UI local :3001; harness local/remoto; MCP ID 21; Windows pendiente de validación real | | Autenticación dual | Diseño aprobado; falta cerrar proveedor/login, tokens y registro/revocación de instalaciones |
| Script de despliegue configurable | ✅ Preparado para `192.168.10.136` | | Uploads reanudables y cola durable | Objetivo 10, pendiente de diseño e implementación |
| App desktop (Tauri — Windows/Linux/macOS) | ⏳ Pendiente | | Restauración automatizada y verificada | Objetivo 11; el harness validó un ciclo básico remoto, la automatización de archivos/dumps sigue pendiente |
| SDK Flutter (uniffi-rs → Dart FFI) | ⏳ Pendiente | | HTTPS público | Pendiente confirmar dominio y configurar la entrada aprobada |
| SDK Java (uniffi-rs → JNI) | ⏳ Pendiente | | Bitácora WebControl | Objetivo 8; bloqueada hasta confirmar `app_origen` y obtener `x-api-key` autorizada |
| Deploy en `192.168.10.136` | ✅ Ejecutado; smoke test HTTP aprobado | | App de escritorio Tauri / SDK Flutter / SDK Java | Pendientes |
| HTTPS público detrás de Apache | ⏳ Pendiente de configurar y verificar |
| Bitácora centralizada de errores | ⏳ Pendiente de clave, reportador y consulta operativa |
| Autenticación dual para apps y servicios | ⏳ Diseño aprobado; login Cloud, sesiones cortas y credencial por instalación pendientes |
**Integración con el ecosistema:** **Integración y separación de sistemas:**
- **SIGMAC** (Java ERP, CT 141): SDK Java pendiente — backup automático de archivos y BD de las empresas clientes - **MCP de Infraestructura** (`192.168.10.160:3006`): inventario y reglas operativas. Ficha de servicio id 12; no es proxy de errores de runtime.
- **sigmac_app** (Flutter, `.72`): SDK Flutter pendiente — backup de datos del app sin intervención del usuario - **Feedback MCP:** el 2026-10-17 se reportó MISSING id 24 porque el inventario no contiene una entidad de hardware para `192.168.10.136`. No registrar un CT o ubicación hasta confirmarlos.
- **MCP de Infraestructura** (`192.168.10.160:3006`): inventario actualizado; no es proxy de la bitácora de errores - **API-SIGMA-WEBCONTROL** (`https://api.siax-system.net/api/errores`): destino separado para errores de runtime. No hay `x-api-key` autorizada ni `app_origen` confirmado en este proyecto; la ausencia de consulta no significa ausencia de errores.
- **API-SIGMA-WEBCONTROL**: canal previsto para reportar/consultar errores de runtime cuando exista una clave autorizada - **Reglas de despliegue:** no se devolvieron reglas activas globales ni para `cloud-sync`; no inferir dominio, DNS, ruta pública o contenedor.
- **Autenticación Cloud**: diseño aprobado para login de apps con access/refresh token y credencial protegida por instalación en servicios automáticos; implementación pendiente - **Autenticación Cloud:** la implementación dual sigue pendiente de cerrar el contrato con el proveedor autorizado. No persistir contraseñas Cloud en cloud-sync.
- **Apache**: VirtualHost HTTPS pendiente
**Dónde buscar más información:** `siax-amd:/home/pablinux/Projects/Rust/cloud monitor sinc/agents.md`; cliente server-to-server: `/home/pablinux/Projects/Rust/cloud-sync-clients/agents.md` **Dónde buscar más información:** `siax-amd:/home/pablinux/Projects/Rust/cloud monitor sinc/agents.md`; cliente server-to-server: `/home/pablinux/Projects/Rust/cloud-sync-clients/agents.md`
.agente/proyecto_errores.md
+4 -4
View File
@@ -20,11 +20,11 @@
--- ---
## Incidente #3: Error 1114 al registrar servicio en MCP de Infraestructura ## Incidente #3: Error 1114 al registrar servicio en MCP de Infraestructura
- **Fecha:** 2026-10-16 - **Fecha:** 2026-10-16 / 2026-10-17
- **Síntoma:** Al invocar `crear_servicio` en el MCP de Infraestructura (`192.168.10.160:3006`), MariaDB devolvió: `MysqlError 1114 (HY000): The table 'services' is full`. - **Síntoma:** Al invocar `crear_servicio` en el MCP de Infraestructura (`192.168.10.160:3006`), MariaDB devolvió: `MysqlError 1114 (HY000): The table 'services' is full`.
- **Causa confirmada:** La tabla `services` en la base de datos `mcp_infraestructura` (MariaDB `192.168.10.149:3306`) alcanzó su límite de tamaño o memoria asignada. - **Causa confirmada:** Llenado de disco en CT 114 (`192.168.10.149:3306`), reportado también en feedback #21 como `ER_DISK_FULL`.
- **Solución / Seguimiento:** Se reportó como **Feedback #20** (`helpdesk-services-full-20261016`, severidad `CRITICAL`, estado `OPEN`) en el sistema de feedback del MCP. Reintentar el registro una vez resuelto en MariaDB. - **Solución / Seguimiento:** Se reportó como **Feedback #20** (`helpdesk-services-full-20261016`). Pablinux liberó espacio en disco en CT 114 el 2026-10-17. Se reintentó el registro y se confirmó la inserción exitosa de `help_desk` como **Servicio ID 35** en MariaDB. Feedback #20 cerrado como `RESOLVED`.
- **Estado:** Reportado / Pendiente de resolución externa. - **Estado:** Resuelto (Servicio ID 35 activo en MCP).
--- ---
.agente/proyecto_estructura.md
+1
View File
@@ -18,6 +18,7 @@ help_desk/
│ ├── proyecto_estructura.md # Este archivo: árbol, rutas y dependencias │ ├── proyecto_estructura.md # Este archivo: árbol, rutas y dependencias
│ ├── proyecto_errores.md # Bitácora de incidentes y problemas conocidos │ ├── proyecto_errores.md # Bitácora de incidentes y problemas conocidos
│ ├── objetivos.md # Objetivos pendientes, en curso y completados │ ├── objetivos.md # Objetivos pendientes, en curso y completados
│ ├── tareas.md # Bitácora de tareas, entregables y backlog
│ ├── reglas.md # Restricciones técnicas y de seguridad │ ├── reglas.md # Restricciones técnicas y de seguridad
│ └── ideas.md # Ideas y propuestas pendientes │ └── ideas.md # Ideas y propuestas pendientes
├── config/ ├── config/
.agente/reglas.md
+11 -1
View File
@@ -17,5 +17,15 @@
## 4. Rutina de Actualización Documental ## 4. Rutina de Actualización Documental
- **Alcance:** Mantenimiento y evolución del proyecto. - **Alcance:** Mantenimiento y evolución del proyecto.
- **Restricción:** Al solicitar "actualizar proyecto", se debe revisar y sincronizar `agents.md`, `.agente/proyecto_estructura.md`, `.agente/proyecto_memoria.md`, `.agente/proyecto_errores.md`, `.agente/objetivos.md`, `README.md` y la ficha en el MCP de Infraestructura. - **Restricción:** Al solicitar "actualizar proyecto", se debe revisar y sincronizar `agents.md`, `.agente/proyecto_estructura.md`, `.agente/proyecto_memoria.md`, `.agente/proyecto_errores.md`, `.agente/objetivos.md`, `.agente/tareas.md`, `README.md` y la ficha en el MCP de Infraestructura.
- **Motivo:** Preservar la fuente de verdad técnica y la coherencia en todo el ecosistema. - **Motivo:** Preservar la fuente de verdad técnica y la coherencia en todo el ecosistema.
## 5. Integridad del Módulo FSM (Field Service Management)
- **Alcance:** Creación, despacho y sincronización de visitas técnicas en terreno.
- **Restricción:** Toda visita técnica presencial debe generarse a través de `tareasHubService.js` hacia `tareas.telcotronics.com` con `origen: 'HELP_DESK'` y `origen_externo_id = ticket.id`. El registro local en `ticket_visitas` debe conservar el `external_id` y su `historial_json` en caché. No modificar estados a `completada` sin validación del Hub o de la firma/evidencia en campo.
- **Motivo:** Garantizar la trazabilidad legal y técnica entre la mesa de ayuda y las operaciones de campo.
## 6. Identidad de Agente y Comunicaciones
- **Alcance:** Archivo `id_agente.md` y conexión a `sigma-robot` / MCP de Chat.
- **Restricción:** Mantener la identidad en `pendiente` hasta confirmación formal en `sigma-robot`. Nunca inventar identificadores, nombres ni tokens locales. Nunca incluir secretos o credenciales en `id_agente.md`.
- **Motivo:** Cumplimiento del estándar centralizado de agentes del ecosistema Telcotronics.
.agente/tareas.md
+34
View File
@@ -0,0 +1,34 @@
# Bitácora de Tareas y Sprints — Help Desk
## Tareas en Curso
*(Actualmente todas las tareas del sprint FSM y MCP han sido completadas satisfactoriamente)*
---
## Tareas Completadas
| Fecha | Tarea / Entregable | Responsable | Archivos Afectados |
|---|---|---|---|
| 2026-10-17 | **Registro y Ficha Oficial en MCP de Infraestructura** (Servicio ID 35) | Agente IA | Inventario MCP MariaDB (`http://192.168.10.160:3007/api/services/35`), `.agente/objetivos.md` |
| 2026-10-17 | **Módulo FSM de Visitas Técnicas integrado con Hub de Tareas** (`tareas.telcotronics.com`) | Agente IA | `models/TicketVisita.js`, `config/tareasHubService.js`, `routes/agent.js`, `config/setup.js` |
| 2026-10-17 | **Mini-Timeline Operativo en Vivo con Bitácora de Eventos y Firma Digital** | Agente IA | `views/agent/view-ticket.ejs` |
| 2026-10-17 | **Automatización Bidireccional de Tickets** (Despacho a `en_progreso`, cierre con firma en hilo) | Agente IA | `routes/agent.js` |
| 2026-10-17 | **Script de Prueba End-to-End para FSM** | Agente IA | `scripts/test_visita_flow.js` |
| 2026-10-17 | **Estandarización de Identidad de Agente** (`id_agente.md`) | Agente IA | `id_agente.md` |
| 2026-10-17 | **Sincronización de Espejo Maestro de Infraestructura** | Agente IA | `.agente/infraestructura.md` |
| 2026-10-16 | **Integración de Bitácora Centralizada de Errores** (API-SIGMA-WEBCONTROL) | Agente IA | `config/errorReporter.js`, `app.js`, `scripts/consultar_errores.js` |
| 2026-10-16 | **Configuración de Repositorio Remoto Git** (`git.telcotronics.net/pablinux/help_desk.git`) | Agente IA | `.git/config` |
| 2026-10-16 | **Inicialización Documental Completa bajo Estándar Telcotronics** | Agente IA | `.agente/`, `agents.md`, `README.md`, `.env.example` |
---
## Tareas Pendientes / Backlog
| Prioridad | Tarea | Descripción | Dependencia |
|---|---|---|---|
| **Alta** | **Creación de Repositorio Vacío en Gitea** | Crear el repositorio vacío `pablinux/help_desk` en `https://git.telcotronics.net` para habilitar el `git push -u origin main`. | Humano (Pablinux) |
| **Alta** | **Script `init.sh` Estandarizado** | Script bash con menú interactivo para verificar variables de entorno, pool MariaDB y dependencias npm antes del arranque. | Ninguna |
| **Media** | **Script `desplegar.sh` para Producción** | Automatización de rsync y reinicio de servicio para despliegue en contenedor Proxmox (CT 132 u homólogo). | Ninguna |
| **Media** | **Integración SSE / WebSockets para Timeline en Vivo** | Actualización en tiempo real sin requerir clic manual en "Sincronizar estado con Hub". | FSM Módulo |
| **Baja** | **SLA y Tiempos de Resolución** | Contador de tiempo transcurrido y alerta de vencimiento de SLA según prioridad del ticket. | Ninguna |
README.md
+63 -14
View File
@@ -1,12 +1,16 @@
# Help Desk — Sistema Multi-Tenant de Gestión de Incidencias # Help Desk — Sistema Multi-Tenant de Gestión de Incidencias & FSM
Sistema web modular para gestión de tickets de soporte técnico, atención al cliente y administración multi-tenant (SaaS), construido sobre Node.js, Express 5 y MariaDB. Sistema web SaaS modular para la gestión de tickets de soporte técnico, atención al cliente y despacho de **visitas técnicas en terreno (FSM - Field Service Management)**, integrado con el ecosistema central de Telcotronics sobre Node.js, Express 5 y MariaDB.
--- ---
## 🎯 ¿Qué resuelve? ## 🎯 ¿Qué resuelve?
Centraliza la recepción, triaje, asignación y resolución de solicitudes de soporte técnico dentro de las organizaciones del ecosistema Telcotronics. Permite que múltiples empresas o departamentos gestionen sus tickets de forma completamente aislada a través de una arquitectura SaaS integrada. Centraliza el ciclo completo de atención técnica para las organizaciones del ecosistema Telcotronics:
1. **Recepción y Triaje Digital:** Clientes y agentes registran solicitudes con prioridad y categorización por departamento.
2. **Aislamiento Multi-Tenant (SaaS):** Cada empresa u organización opera con sus propios datos, usuarios y tickets de forma completamente aislada.
3. **Despacho y Trazabilidad de Campo (FSM):** Cuando un ticket requiere atención presencial, el agente programa la visita técnica directamente hacia el sistema central [tareas.telcotronics.com](https://tareas.telcotronics.com) (CT 132), asignando a técnicos reales con checklist de tareas, coordenadas GPS y seguimiento operativo en vivo.
4. **Mini-Timeline en Vivo & Firma Digital:** Visualización de los 4 hitos operativos en el ticket: Programada ➔ Check-in GPS en sitio ➔ Avance de checklist con fotos de evidencia ➔ Cierre con firma digital del cliente.
--- ---
@@ -16,25 +20,44 @@ Centraliza la recepción, triaje, asignación y resolución de solicitudes de so
|---|---|---| |---|---|---|
| **Superadmin** | `/saas/companies` | Alta de empresas, activación/suspensión de tenants y control de cuotas | | **Superadmin** | `/saas/companies` | Alta de empresas, activación/suspensión de tenants y control de cuotas |
| **Admin** | `/admin/dashboard` | Gestión de agentes y clientes, CRUD de departamentos y configuración del tenant | | **Admin** | `/admin/dashboard` | Gestión de agentes y clientes, CRUD de departamentos y configuración del tenant |
| **Agente** | `/agent/dashboard` | Bandeja de tickets, cambio de estado (`abierto`, `en_progreso`, `cerrado`), asignación y respuestas | | **Agente** | `/agent/dashboard` | Bandeja de tickets, cambio de estado (`abierto`, `en_progreso`, `cerrado`), programación de visitas técnicas FSM y respuesta |
| **Cliente** | `/client/dashboard` | Apertura de tickets con prioridad y departamento, consulta de historial y respuestas | | **Cliente** | `/client/dashboard` | Apertura de tickets con prioridad y departamento, consulta de historial y respuestas |
--- ---
## 🚚 Módulo FSM (Visitas Técnicas en Terreno)
Integrado bidireccionalmente con **`tareas.telcotronics.com`**:
- **Programación desde el Modal:** Selecciona técnicos en vivo desde el Hub (`/api/external/users/list`), define fecha/hora, dirección, coordenadas GPS (Lat, Lng), referencia y checklist inicial.
- **Seguimiento con Mini-Timeline:**
1. 📅 **Programada:** Datos del técnico asignado, fecha/hora y dirección.
2. 📍 **Check-in GPS:** Hora de arribo y coordenadas validadas en sitio por el técnico.
3. 📸 **Avance y Evidencias:** Barra de porcentaje de checklist, galería de fotos de campo en terreno y visualización de la firma digital del cliente.
4. 🏁 **Finalización:** Botón `🔄 Sincronizar estado con Hub` para actualizar el timeline y bitácora de eventos a demanda.
- **Automatización en el Hilo del Ticket:**
- Al programar: el ticket pasa automáticamente a `en_progreso` y se publica el detalle del despacho.
- Al completarse la visita: se sella la visita como `completada` y se añade automáticamente una nota con el balance de tareas, observaciones del técnico y el nombre de quien firmó el acta.
---
## 🛠️ Stack Tecnológico ## 🛠️ Stack Tecnológico
- **Backend:** Node.js 18+ con Express 5.2. - **Backend:** Node.js 20+ con Express 5.2.
- **Vistas:** EJS con partials modulares. - **Vistas:** EJS 5 con partials modulares y Bootstrap 5.3 + Font Awesome 6.
- **Base de Datos:** MariaDB / MySQL vía conector nativo `mysql2/promise`. - **Base de Datos:** MariaDB / MySQL vía conector nativo `mysql2/promise` (`192.168.10.149:3306`, Contenedor CT 114).
- **Integración FSM:** API REST externa contra `tareas.telcotronics.com` (CT 132 `192.168.10.160:3000`).
- **Autenticación:** Sesiones del lado del servidor con `express-session` y contraseñas cifradas con `bcryptjs`. - **Autenticación:** Sesiones del lado del servidor con `express-session` y contraseñas cifradas con `bcryptjs`.
- **Frontend:** Bootstrap 5.3 + Font Awesome 6 (vía CDN) y CSS/JS personalizados. - **Auditoría y Bitácora de Errores:** Integración con API-SIGMA-WEBCONTROL (`192.168.10.149:3005`).
- **Inventario Central:** Registrado oficialmente en el MCP de Infraestructura como **Servicio ID 35**.
--- ---
## 📋 Requisitos Previos ## 📋 Requisitos Previos
- Node.js versión 18 o superior. - Node.js versión 18 o superior (recomendado Node 20+).
- MariaDB 10.x / MySQL 8.x con acceso a crear bases de datos y tablas. - MariaDB 10.x / MySQL 8.x con acceso a crear bases de datos y tablas.
- Conectividad a la red interna Telcotronics (`192.168.10.149` y `192.168.10.160`).
--- ---
@@ -42,13 +65,13 @@ Centraliza la recepción, triaje, asignación y resolución de solicitudes de so
### 1. Clonar e instalar dependencias ### 1. Clonar e instalar dependencias
```bash ```bash
git clone <url-repositorio> help_desk git clone https://git.telcotronics.net/pablinux/help_desk.git
cd help_desk cd help_desk
npm install npm install
``` ```
### 2. Configurar variables de entorno ### 2. Configurar variables de entorno
Crea un archivo `.env` en la raíz basándote en la plantilla: Crea un archivo `.env` en la raíz basándote en la plantilla `.env.example`:
```ini ```ini
PORT=3008 PORT=3008
DB_HOST=192.168.10.149 DB_HOST=192.168.10.149
@@ -57,10 +80,17 @@ DB_PASSWORD=tu_password_segura
DB_NAME=help_desk DB_NAME=help_desk
SESSION_SECRET=tu_secreto_de_sesion SESSION_SECRET=tu_secreto_de_sesion
JWT_SECRET=tu_jwt_secret JWT_SECRET=tu_jwt_secret
# Integración Hub de Tareas FSM
HUB_TAREAS_URL=https://tareas.telcotronics.com/api/external
HUB_TAREAS_API_KEY=sigma_crm_test_key_123
# Bitácora Centralizada de Errores
ERROR_API_URL=https://api.siax-system.net/api/errores
``` ```
### 3. Inicializar y migrar la Base de Datos ### 3. Inicializar y migrar la Base de Datos
Ejecuta el script de configuración automática para crear la base de datos, tablas, relaciones y datos semilla (empresa demo y usuarios iniciales): Crea la base de datos, tablas (incluyendo `ticket_visitas`), relaciones y datos semilla (empresa demo y usuarios):
```bash ```bash
node config/setup.js node config/setup.js
``` ```
@@ -77,6 +107,18 @@ Acceso en navegador: `http://localhost:3008`
--- ---
## 🧪 Pruebas y Auditoría
```bash
# Verificar flujo completo de visitas técnicas contra el Hub
node scripts/test_visita_flow.js
# Consultar la bitácora centralizada de errores (API-SIGMA-WEBCONTROL)
npm run check:errors
```
---
## 🔑 Credenciales por Defecto (Seed) ## 🔑 Credenciales por Defecto (Seed)
| Rol | Correo Electrónico | Contraseña | | Rol | Correo Electrónico | Contraseña |
@@ -91,6 +133,13 @@ Acceso en navegador: `http://localhost:3008`
## 📁 Documentación para Agentes e Infraestructura ## 📁 Documentación para Agentes e Infraestructura
- **Punto de Entrada de Agentes:** [agents.md](file:///home/pablinux/Projects/Node/help_desk/agents.md) - **Punto de Entrada de Agentes:** [agents.md](file:///home/pablinux/Projects/Node/help_desk/agents.md)
- **Documentación Interna del Proyecto:** Carpeta [.agente/](file:///home/pablinux/Projects/Node/help_desk/.agente/)
- **Inventario Global del Ecosistema:** [.agente/infraestructura.md](file:///home/pablinux/Projects/Node/help_desk/.agente/infraestructura.md)
- **Identidad del Agente:** [id_agente.md](file:///home/pablinux/Projects/Node/help_desk/id_agente.md) - **Identidad del Agente:** [id_agente.md](file:///home/pablinux/Projects/Node/help_desk/id_agente.md)
- **Documentación Interna del Proyecto:** Carpeta [.agente/](file:///home/pablinux/Projects/Node/help_desk/.agente/)
- [Memoria Técnica de Arquitectura](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_memoria.md)
- [Estructura del Proyecto y Rutas](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_estructura.md)
- [Objetivos y Sprint](file:///home/pablinux/Projects/Node/help_desk/.agente/objetivos.md)
- [Bitácora de Tareas](file:///home/pablinux/Projects/Node/help_desk/.agente/tareas.md)
- [Bitácora de Errores e Incidentes](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_errores.md)
- [Reglas Técnicas y de Operación](file:///home/pablinux/Projects/Node/help_desk/.agente/reglas.md)
- [Ideas y Roadmap](file:///home/pablinux/Projects/Node/help_desk/.agente/ideas.md)
- **Inventario Global del Ecosistema:** [.agente/infraestructura.md](file:///home/pablinux/Projects/Node/help_desk/.agente/infraestructura.md)
agents.md
+16 -3
View File
@@ -71,6 +71,15 @@ Proveer un sistema web robusto, ágil y seguro para la gestión integral de tick
- Gestión global de empresas/tenants (`companies`). - Gestión global de empresas/tenants (`companies`).
- Asignación de planes (`free`, `pro`, `enterprise`) y cuotas máximas de usuarios y tickets. - Asignación de planes (`free`, `pro`, `enterprise`) y cuotas máximas de usuarios y tickets.
### 6. Módulo FSM — Visitas Técnicas en Terreno (`/agent/ticket/:id/visita`)
**Estado: ✅ Operativo**
- Programación y despacho de visitas técnicas directamente hacia `tareas.telcotronics.com` (CT 132 `192.168.10.160:3000`).
- Sincronización de nómina de técnicos en tiempo real (`/api/external/users/list`).
- Creación de tareas operativas con checklist inicial, coordenadas GPS y destino.
- Persistencia en MariaDB (`ticket_visitas`) con caché de timeline en `historial_json`.
- Mini-Timeline de seguimiento en vivo en `view-ticket.ejs`: Programada ➔ Check-in GPS ➔ Evidencias/Fotos ➔ Finalización con firma del cliente.
- Automatización bidireccional de hilos de tickets y estados (`en_progreso` al despachar, `completada` al cerrar).
--- ---
## Infraestructura y Fuentes de Verdad ## Infraestructura y Fuentes de Verdad
@@ -78,11 +87,14 @@ Proveer un sistema web robusto, ágil y seguro para la gestión integral de tick
- **Repositorio Git Oficial:** `https://git.telcotronics.net/pablinux/help_desk.git` (remoto `origin` configurado localmente). - **Repositorio Git Oficial:** `https://git.telcotronics.net/pablinux/help_desk.git` (remoto `origin` configurado localmente).
- **Servidor MCP de Infraestructura:** `http://192.168.10.160:3006/sse` (modo SSE). Panel web: `http://192.168.10.160:3007`. - **Servidor MCP de Infraestructura:** `http://192.168.10.160:3006/sse` (modo SSE). Panel web: `http://192.168.10.160:3007`.
- **Ficha MCP de Help Desk:** - **Ficha MCP de Help Desk:**
- Categoría: `service` / `application` - Categoría: `application`
- Estado en inventario: ⏳ Pendiente de registro remoto. Se intentó registrar vía `crear_servicio`, pero la base de datos del MCP arrojó `MysqlError 1114 (The table 'services' is full)`. Se registró el incidente formalmente en el sistema de feedback del MCP como **Feedback #20** (`helpdesk-services-full-20261016`, estado `OPEN`). - Tipo: `webapp`
- Puerto: `3008`
- Estado en inventario: ✅ **Registrado oficialmente como Servicio ID 35** (`http://192.168.10.160:3007/api/services/35`).
- Incidente previo resuelto: Feedback #20 cerrado como `RESOLVED` tras liberación de espacio en disco en CT 114.
- **Base de Datos Central:** - **Base de Datos Central:**
- Host: `192.168.10.149:3306` (CT 114 en Proxmox). - Host: `192.168.10.149:3306` (CT 114 en Proxmox).
- Base de datos: `help_desk` (Verificada: 5 tablas activas: `companies`, `departments`, `ticket_respuestas`, `tickets`, `users`). - Base de datos: `help_desk` (Verificada: 6 tablas activas: `companies`, `departments`, `ticket_respuestas`, `tickets`, `users`, `ticket_visitas`).
- Usuario: `helpdesk`. - Usuario: `helpdesk`.
- **Puerto Local de Ejecución:** `3008`. - **Puerto Local de Ejecución:** `3008`.
@@ -180,5 +192,6 @@ Acceso web en navegador: `http://localhost:3008`
- [.agente/proyecto_estructura.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_estructura.md): Árbol de archivos y tabla completa de endpoints HTTP. - [.agente/proyecto_estructura.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_estructura.md): Árbol de archivos y tabla completa de endpoints HTTP.
- [.agente/proyecto_errores.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_errores.md): Bitácora de incidentes y problemas conocidos. - [.agente/proyecto_errores.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_errores.md): Bitácora de incidentes y problemas conocidos.
- [.agente/objetivos.md](file:///home/pablinux/Projects/Node/help_desk/.agente/objetivos.md): Registro de objetivos completados, en curso y pendientes. - [.agente/objetivos.md](file:///home/pablinux/Projects/Node/help_desk/.agente/objetivos.md): Registro de objetivos completados, en curso y pendientes.
- [.agente/tareas.md](file:///home/pablinux/Projects/Node/help_desk/.agente/tareas.md): Bitácora de tareas, entregables completados y backlog.
- [.agente/reglas.md](file:///home/pablinux/Projects/Node/help_desk/.agente/reglas.md): Reglas de seguridad y buenas prácticas del proyecto. - [.agente/reglas.md](file:///home/pablinux/Projects/Node/help_desk/.agente/reglas.md): Reglas de seguridad y buenas prácticas del proyecto.
- [.agente/ideas.md](file:///home/pablinux/Projects/Node/help_desk/.agente/ideas.md): Registro de propuestas e ideas en evaluación. - [.agente/ideas.md](file:///home/pablinux/Projects/Node/help_desk/.agente/ideas.md): Registro de propuestas e ideas en evaluación.