From 5a7dbf7ab95977e357fd318e1006912f06c4c18f Mon Sep 17 00:00:00 2001 From: pablinux Date: Sat, 17 Oct 2026 03:55:39 -0500 Subject: [PATCH] docs: actualizar documentacion integral (.agente/, README, agents.md) y sincronizar espejo maestro de infraestructura --- .agente/ideas.md | 15 ++++- .agente/infraestructura.md | 111 +++++++++++++++++---------------- .agente/proyecto_errores.md | 8 +-- .agente/proyecto_estructura.md | 1 + .agente/reglas.md | 12 +++- .agente/tareas.md | 34 ++++++++++ README.md | 77 ++++++++++++++++++----- agents.md | 19 +++++- 8 files changed, 199 insertions(+), 78 deletions(-) create mode 100644 .agente/tareas.md diff --git a/.agente/ideas.md b/.agente/ideas.md index a0afc9e..511b4c5 100644 --- a/.agente/ideas.md +++ b/.agente/ideas.md @@ -14,8 +14,21 @@ 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. +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 -- *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. diff --git a/.agente/infraestructura.md b/.agente/infraestructura.md index 1098bad..7d6dca2 100644 --- a/.agente/infraestructura.md +++ b/.agente/infraestructura.md @@ -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). | | **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. | -| **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-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** | `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 + 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 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 | |---|---| -| Repositorio Git | `https://git.telcotronics.net/pablinux/Service-Cloud-SINC.git` (privado, rama `main`, último commit documentado `babf1cd`) | -| Tecnología principal | Rust 2021 · Axum 0.7 · Tokio · rusqlite/SQLite · filesystem local · HTML/CSS/JavaScript para consolas web | +| 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 | | Responsable | pablinux | -| Estado actual | 🟡 Primer despliegue y smoke test HTTP aprobados; HTTPS público, auth Cloud dual y pruebas funcionales pendientes | -| Equipo / código local | `siax-amd` (`192.168.10.100`) — `/home/pablinux/Projects/Rust/cloud monitor sinc` | -| 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 | -| Dominio público | Pendiente — VirtualHost HTTPS en Apache | -| Puerto interno | `3000` | -| Última actualización | 2026-09-30 | +| MCP de Infraestructura | Servicio id 12 · categoría `service` · estado `ACTIVE` | +| 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:3000`; ruta documentada `/home/user_apps/apps/cloud-sync` | +| 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 | +| Dominio público / HTTPS | Sin dominio confirmado; HTTPS público pendiente | +| 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 | -|---|---|---|---| -| 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, en el cliente) | Equipo de origen | `index.db` | Índice local de rutas, checksum SHA-256, backup_id y timestamps | +| Motor | Host / ruta | Uso | +|---|---|---| +| 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 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:** | Método | Endpoint | Auth | Descripción | |---|---|---|---| -| GET | `/health` | — | Estado del servidor + info de disco | -| POST | `/auth/token` | — | Login cliente (token UUID) → sesión Bearer | -| POST | `/auth/admin` | — | Login admin (argon2) → session token | -| POST | `/backup/upload` | Bearer token | Subir archivo cifrado (multipart) | -| GET | `/backup/list` | Bearer token | Listar backups de la empresa | -| GET | `/backup/download/{id}` | Bearer token | Descargar backup para restore | -| DELETE | `/backup/{id}` | Bearer token | Eliminar backup | -| GET | `/me/storage` | Bearer token | Uso actual vs cuota asignada | -| GET | `/admin/storage` | X-Admin-Token | Capacidad CT146 + resumen global | -| GET/POST | `/admin/clientes` | X-Admin-Token | Listar / crear empresas | -| PUT | `/admin/clientes/{id}/cuota` | X-Admin-Token | Ajustar cuota por empresa | -| GET | `/admin/eventos` | X-Admin-Token | Log de auditoría | -| GET | `/root/` | — | Consola root para empresas, cuotas, estados, perfiles y accesos | -| GET | `/admin/` | — | Portal admin de empresa para consultar cuenta y descargar respaldos propios | -| GET | `/panel/` | Token de integración | Portal legado de cliente | -| 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 | -| 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 | `/health` | — | Estado del servidor y capacidad de disco | +| POST | `/auth/token` | Token de empresa | Compatibilidad con agentes integradores | +| POST | `/auth/root`, `/auth/admin` | Usuario y contraseña | Login root; `/auth/admin` es alias compatible | +| POST | `/auth/empresa` | Usuario y contraseña | Login de administrador de empresa | +| POST | `/auth/logout` | Sesión Bearer | Revocar la sesión presentada | +| PUT | `/auth/admin/password` | Sesión root | Cambiar contraseña root | +| PUT | `/auth/empresa/password` | Sesión empresa | Cambiar contraseña de empresa | +| GET | `/empresa/cuenta` | Sesión empresa | Consultar su cuenta y perfil | +| POST | `/backup/upload` | Bearer de integración | Subir backup cifrado multipart; límite configurado de hasta 10 GiB y cuota por empresa | +| GET | `/backup/list`, `/backup/status` | Bearer de integración | Listar respaldos y consultar estado | +| GET | `/backup/download/{id}` | Bearer de integración o sesión empresa | Descargar respaldo cifrado propio | +| DELETE | `/backup/{id}` | Bearer de integración | Eliminar backup propio | +| GET | `/me/storage` | Bearer de integración | Uso y cuota de empresa | +| GET | `/admin/storage`, `/admin/clientes`, `/admin/eventos` | Sesión root | Capacidad, empresas y auditoría | +| POST | `/admin/clientes` | Sesión root | Crear empresa y token de integración | +| PUT | `/admin/clientes/{id}/cuota`, `/estado` | Sesión root | Cambiar cuota o suspender empresa | +| 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 | -| Consola web admin (`/admin`) | ✅ Completa | -| Consola web panel cliente (`/panel`) | ✅ Completa | -| `cloud_sync_core` (librería Rust) — crypto, uploader, backup_engine, restore | ✅ Completo | -| 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 | -| Script de despliegue configurable | ✅ Preparado para `192.168.10.136` | -| App desktop (Tauri — Windows/Linux/macOS) | ⏳ Pendiente | -| SDK Flutter (uniffi-rs → Dart FFI) | ⏳ Pendiente | -| SDK Java (uniffi-rs → JNI) | ⏳ Pendiente | -| Deploy en `192.168.10.136` | ✅ Ejecutado; smoke test HTTP aprobado | -| 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 | +| API Rust y consola root | Implementadas y desplegadas; health HTTP verificado | +| Consola de empresa | Implementada; validar login y flujos de consola en producción | +| Portal `/panel/` | Legado por token de integración | +| `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 | +| Autenticación dual | Diseño aprobado; falta cerrar proveedor/login, tokens y registro/revocación de instalaciones | +| Uploads reanudables y cola durable | Objetivo 10, pendiente de diseño e implementación | +| Restauración automatizada y verificada | Objetivo 11; el harness validó un ciclo básico remoto, la automatización de archivos/dumps sigue pendiente | +| HTTPS público | Pendiente confirmar dominio y configurar la entrada aprobada | +| Bitácora WebControl | Objetivo 8; bloqueada hasta confirmar `app_origen` y obtener `x-api-key` autorizada | +| App de escritorio Tauri / SDK Flutter / SDK Java | Pendientes | -**Integración con el ecosistema:** -- **SIGMAC** (Java ERP, CT 141): SDK Java pendiente — backup automático de archivos y BD de las empresas clientes -- **sigmac_app** (Flutter, `.72`): SDK Flutter pendiente — backup de datos del app sin intervención del usuario -- **MCP de Infraestructura** (`192.168.10.160:3006`): inventario actualizado; no es proxy de la bitácora de errores -- **API-SIGMA-WEBCONTROL**: canal previsto para reportar/consultar errores de runtime cuando exista una clave autorizada -- **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 -- **Apache**: VirtualHost HTTPS pendiente +**Integración y separación de sistemas:** +- **MCP de Infraestructura** (`192.168.10.160:3006`): inventario y reglas operativas. Ficha de servicio id 12; no es proxy de errores de runtime. +- **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. +- **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. +- **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:** la implementación dual sigue pendiente de cerrar el contrato con el proveedor autorizado. No persistir contraseñas Cloud en cloud-sync. **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` diff --git a/.agente/proyecto_errores.md b/.agente/proyecto_errores.md index 7910307..c52ca3b 100644 --- a/.agente/proyecto_errores.md +++ b/.agente/proyecto_errores.md @@ -20,11 +20,11 @@ --- ## 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`. -- **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. -- **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. -- **Estado:** Reportado / Pendiente de resolución externa. +- **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`). 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:** Resuelto (Servicio ID 35 activo en MCP). --- diff --git a/.agente/proyecto_estructura.md b/.agente/proyecto_estructura.md index 76f2b8a..5112f2d 100644 --- a/.agente/proyecto_estructura.md +++ b/.agente/proyecto_estructura.md @@ -18,6 +18,7 @@ help_desk/ │ ├── proyecto_estructura.md # Este archivo: árbol, rutas y dependencias │ ├── proyecto_errores.md # Bitácora de incidentes y problemas conocidos │ ├── 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 │ └── ideas.md # Ideas y propuestas pendientes ├── config/ diff --git a/.agente/reglas.md b/.agente/reglas.md index a51ca81..f0f76bd 100644 --- a/.agente/reglas.md +++ b/.agente/reglas.md @@ -17,5 +17,15 @@ ## 4. Rutina de Actualización Documental - **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. + +## 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. diff --git a/.agente/tareas.md b/.agente/tareas.md new file mode 100644 index 0000000..10418d7 --- /dev/null +++ b/.agente/tareas.md @@ -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 | diff --git a/README.md b/README.md index c50684f..1269c73 100644 --- a/README.md +++ b/README.md @@ -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? -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 | | **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 | --- +## 🚚 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 -- **Backend:** Node.js 18+ con Express 5.2. -- **Vistas:** EJS con partials modulares. -- **Base de Datos:** MariaDB / MySQL vía conector nativo `mysql2/promise`. +- **Backend:** Node.js 20+ con Express 5.2. +- **Vistas:** EJS 5 con partials modulares y Bootstrap 5.3 + Font Awesome 6. +- **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`. -- **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 -- 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. +- 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 ```bash -git clone help_desk +git clone https://git.telcotronics.net/pablinux/help_desk.git cd help_desk npm install ``` ### 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 PORT=3008 DB_HOST=192.168.10.149 @@ -57,10 +80,17 @@ DB_PASSWORD=tu_password_segura DB_NAME=help_desk SESSION_SECRET=tu_secreto_de_sesion 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 -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 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) | Rol | Correo Electrónico | Contraseña | @@ -91,6 +133,13 @@ Acceso en navegador: `http://localhost:3008` ## 📁 Documentación para Agentes e Infraestructura - **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) +- **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) diff --git a/agents.md b/agents.md index e2a1829..fd7dd73 100644 --- a/agents.md +++ b/agents.md @@ -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`). - 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 @@ -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). - **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:** - - Categoría: `service` / `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`). + - Categoría: `application` + - 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:** - 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`. - **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_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/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/ideas.md](file:///home/pablinux/Projects/Node/help_desk/.agente/ideas.md): Registro de propuestas e ideas en evaluación.