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

This commit is contained in:
2026-10-17 03:55:39 -05:00
parent 5324d5f433
commit 5a7dbf7ab9
8 changed files with 199 additions and 78 deletions
+14 -1
View File
@@ -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.
+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). |
| **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`
+4 -4
View File
@@ -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).
---
+1
View File
@@ -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/
+11 -1
View File
@@ -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.
+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 |