help_desk/agents.md

# agents.md — Punto de Entrada del Proyecto Help Desk

> **Reglas Obligatorias:**
> - Este archivo es el eslabón más importante de la documentación. Leerlo siempre antes de cualquier tarea.
> - Cada cambio significativo debe reflejarse en este archivo y en los demás archivos del índice documental (`.agente/`).
> - Debe ser técnico, claro y detallado para que cualquier humano, agente o IA lo entienda sin explicaciones previas.
> - **Rutina al actualizar el proyecto:** Al actualizar el proyecto, revisar objetivos, errores, memoria, reglas, estructura y README; actualizar la ficha propia en MCP con datos verificados; registrar pruebas y pendientes. Hacer commit de los cambios revisados cuando se solicite actualizar proyecto. El push se realiza según la instrucción vigente del usuario y se confirma contra el remoto; un commit local no prueba publicación.

---

## Antecedentes

Help Desk es la aplicación de soporte técnico y gestión de incidencias del ecosistema Telcotronics. Nació de la necesidad de centralizar las solicitudes de asistencia, reportes de averías y consultas operativas de los usuarios y clientes de los servicios de la red. Evolucionó desde una solución básica monousuario a una arquitectura multi-tenant (SaaS) que permite segregar la atención por empresas manteniendo una única infraestructura backend.

---

## Objetivo General

Proveer un sistema web robusto, ágil y seguro para la gestión integral de tickets de soporte técnico, con separación de roles y aislamiento por empresa (multi-tenant).

### Responsabilidades Principales:
1. **Atención a clientes:** Registro simplificado de incidencias, categorización por departamento, priorización y seguimiento del hilo de conversación.
2. **Gestión técnica de agentes:** Panel operativo para triaje, respuesta, asignación y resolución de tickets.
3. **Administración por tenant:** Gestión de usuarios, departamentos y configuración propia de cada organización.
4. **Control SaaS global:** Creación, activación y control de cuotas de empresas cliente (tenants).

---

## Stack Técnico

| Componente | Tecnología | Versión |
|---|---|---|
| **Runtime / Backend** | Node.js | v18+ |
| **Framework HTTP** | Express | ^5.2.1 |
| **Motor de Vistas** | EJS | ^5.0.2 |
| **Base de Datos** | MariaDB / MySQL (`mysql2/promise`) | 10.11+ / 8.0+ |
| **Autenticación** | `express-session` + `bcryptjs` | ^1.19.0 / ^3.0.3 |
| **UI Framework** | Bootstrap 5 + Font Awesome 6 (CDN) | 5.3 / 6.4 |
| **Middlewares** | `morgan`, `connect-flash`, `cookie-parser`, `express-fileupload` | Estándar |

---

## Módulos del Sistema y Estado

### 1. Autenticación y Control de Acceso
**Estado: ✅ Operativo**
- Control de sesión servidor (`express-session`) con hashing `bcryptjs`.
- Protección por middleware (`middleware/auth.js`) para 4 roles: `superadmin`, `admin`, `agent`, `client`.
- Inyección de datos de contexto (`loadCompany`, `res.locals`).

### 2. Portal de Clientes (`/client`)
**Estado: ✅ Operativo**
- Dashboard de tickets propios filtrados por usuario y empresa.
- Formulario de creación de ticket (asunto, departamento, prioridad, mensaje).
- Hilo de discusión y respuestas en tiempo real por recarga/flash.

### 3. Consola de Agentes (`/agent`)
**Estado: ✅ Operativo**
- Bandeja central de tickets del tenant.
- Cambio de estado: `abierto` -> `en_progreso` -> `cerrado`.
- Reasignación de agente responsable y respuesta a incidencias.

### 4. Administración de Empresa (`/admin`)
**Estado: ✅ Operativo**
- Panel de estadísticas básicas.
- CRUD de departamentos (Soporte Técnico, Facturación, Ventas, etc.).
- Gestión de usuarios del tenant (activación/desactivación y roles).

### 5. Consola SaaS Superadmin (`/saas`)
**Estado: ✅ Operativo**
- 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).

### 7. Coordinación Tripartita Ecosistema (`ideas` <-> `tareas` <-> `help_desk`)
**Estado: ✅ Activo en sigma-robot**
- Identidad oficial: **Agente Help Desk** (ID `90`), autorizado por `pablinux`.
- Centro de Comunicaciones: `sigma-robot` (MCP `sigma-agentes` y API REST `https://sigma-bot.telcotronics.com/ecosistema/v1`).
- **app_tareas (ID 89):** Despacho M2M de visitas técnicas FSM, timeline en vivo, firmas de clientes y checklist de campo.
- **app_ideas (ID 82):** Canalización de tickets recurrentes, solicitudes de clientes (feature requests) y mejoras hacia el Canvas estratégico de ideas para evaluación y posterior generación de objetivos.


---

## Infraestructura y Fuentes de Verdad

- **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: `application`
  - Tipo: `webapp`
  - Puerto: `3008`
  - URL Oficial: `https://soporte.sigmac.app`
  - 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.
- **Despliegue y Orquestación:**
  - Archivo de destinos: `servers.conf` (a partir de `servers.conf.example`, no commiteado).
  - Script de despliegue: `./desplegar.sh` (sincroniza rsync, instala deps, setup MariaDB, solicita reinicio a SIAX Monitor y actualiza MCP).
  - Orquestador de procesos: **SIAX Monitor** (`http://192.168.10.160:8080`) supervisando la unidad `siax-app-HELPDESK.service`.
  - Servidor de ejecución: `server-webapps` (CT 132 `192.168.10.160`).
  - Dominio público: `https://soporte.sigmac.app` (Proxy reverso en `Servidor-web` CT 109 `192.168.10.109`).
- **Base de Datos Central:**
  - Host: `192.168.10.149:3306` (CT 114 en Proxmox).
  - 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`.

### Documentos Compartidos del Ecosistema
- `/home/pablinux/Projects/infraestructura.md`: Respaldado localmente en `.agente/infraestructura.md`.
- `/home/pablinux/Projects/design-system.md`: Estándar visual SIGMA.
- `/home/pablinux/Projects/roadmap.md`: Decisiones y prioridades estratégicas.

---

## Bitácora Centralizada de Errores (Ecosistema Telcotronics)

Este proyecto reporta sus errores de runtime a la bitácora centralizada de **API-SIGMA-WEBCONTROL** (`https://api.siax-system.net`). Esto tiene dos direcciones — implementar el reporte es solo la mitad: quien mantenga este proyecto (agente o humano) debe además **consultar** periódicamente qué se reportó, no asumir que reportar es "trabajo terminado".

**Fuente autoritativa del contrato:**
- Swagger en vivo: `https://api.siax-system.net/api-docs` → tag "Errores de Sistemas".
- `agents.md` de API-SIGMA-WEBCONTROL y MCP de Infraestructura (`infra://guias/bitacora-errores`).

**Separación de canales:**
- La bitácora humana está en `https://siax-system.net` (WebControlSigma).
- El único destino de reporte de runtime es `POST https://api.siax-system.net/api/errores`.
- El MCP interno distribuye guías e inventario; no transporta errores ni hace de proxy de la API de errores.

### Reportar — `POST https://api.siax-system.net/api/errores`
- Auth: `x-api-key` a nivel-app (`WEBCONTROL_API_KEY`).
- Implementado en Express vía middleware en [config/errorReporter.js](file:///home/pablinux/Projects/Node/help_desk/config/errorReporter.js).
- Parámetros: `app_origen: "Help Desk"`, `mensaje`, `detalle` (stack trace), `categoria` (`sistema`, `bd`, `auth`, `red`), `codigo`, `clase`, `metodo`, `usuario`, `cuenta`, `version`, `fecha_evento`.
- Deduplicación automática en memoria con throttle de 10 minutos por firma de error.

### Consultar — Descargar lo que ya se reportó de esta app
Al empezar una sesión de mantenimiento de este proyecto (o cuando se pida revisar errores/bugs reportados por usuarios reales), traer los propios antes de asumir que no hay nada nuevo:
- **CLI rápido:** `npm run check:errors` (ejecuta [scripts/consultar_errores.js](file:///home/pablinux/Projects/Node/help_desk/scripts/consultar_errores.js)).
- **HTTP directo:** `GET https://api.siax-system.net/api/errores?app_origen=Help Desk` (con header `x-api-key`).
- **Resumen:** `GET https://api.siax-system.net/api/errores/resumen?dias=7`.
- **Conversión a Objetivos:** Cualquier error nuevo se registra en [.agente/objetivos.md](file:///home/pablinux/Projects/Node/help_desk/.agente/objetivos.md) como objetivo verificable y en [.agente/proyecto_errores.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_errores.md).

---

## Variables de Entorno (`.env`)

```ini
PORT=3008
DB_HOST=192.168.10.149
DB_USER=helpdesk
DB_PASSWORD=[PROTEGIDO_VER_ENV_LOCAL]
DB_NAME=help_desk
SESSION_SECRET=[SECRETO_SESION]
JWT_SECRET=[SECRETO_JWT]

# Bitácora de Errores (API-SIGMA-WEBCONTROL)
ERROR_REPORTING_URL=https://api.siax-system.net/api/errores
WEBCONTROL_API_KEY=[API_KEY_WEBCONTROL]
```

---

## Migraciones y Configuración de Base de Datos

Para inicializar las tablas y datos semilla de la base de datos:
```bash
node config/setup.js
```
El script verifica la conexión, crea las tablas si no existen, aplica migraciones de columnas multi-tenant y siembra las 3 empresas oficiales con sus administradores y departamentos:
- **Telcotronics (ID 1):** `admin@telcotronics.com` / `admin@telcotronics.local`
- **XSYSTEM (ID 2):** `admin@xsystem.com`
- **DOMUS (ID 3):** `admin@domus.com`
- **Superadmin Global:** `super@helpdesk.com` / `123456`
- **Personal de soporte:** `agent@helpdesk.com` / `123456`, `client@helpdesk.com` / `123456`

---

## Arranque Local

```bash
# Instalación de dependencias
npm install

# Inicializar/verificar BD
node config/setup.js

# Arrancar aplicación
npm start
# O desarrollo
node app.js
```
Acceso web en navegador: `http://localhost:3008`

---

## Índice de Archivos del Proyecto

- [id_agente.md](file:///home/pablinux/Projects/Node/help_desk/id_agente.md): Identidad del agente asignada por sigma-robot.
- [README.md](file:///home/pablinux/Projects/Node/help_desk/README.md): Manual y guía general para operadores humanos.
- [.agente/infraestructura.md](file:///home/pablinux/Projects/Node/help_desk/.agente/infraestructura.md): Espejo 100% sincronizado del inventario global.
- [.agente/proyecto_memoria.md](file:///home/pablinux/Projects/Node/help_desk/.agente/proyecto_memoria.md): Memoria técnica y decisiones de diseño.
- [.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.