help_desk/README.md

# Help Desk — Sistema Multi-Tenant de Gestión de Incidencias & FSM

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 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.

---

## 👥 Roles de Usuario y Capacidades

| Rol | Dashboard / Acceso | Capacidades Principales |
|---|---|---|
| **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`), 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 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`.
- **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 (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`).

---

## 🚀 Instalación y Puesta en Marcha

### 1. Clonar e instalar dependencias
```bash
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 `.env.example`:
```ini
PORT=3008
DB_HOST=192.168.10.149
DB_USER=helpdesk
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
Crea la base de datos, tablas (incluyendo `ticket_visitas`), relaciones y datos semilla (empresa demo y usuarios):
```bash
node config/setup.js
```

### 4. Iniciar la Aplicación
```bash
# Modo producción
npm start

# Modo desarrollo
node app.js
```
Acceso en navegador: `http://localhost:3008`

---

## 🚀 Despliegue a Producción & Orquestación con SIAX Monitor

El proyecto está preparado para desplegarse de manera automatizada conforme a las reglas del Ecosistema Telcotronics y el orquestador **SIAX Monitor**:

- **Servidor de Producción:** `server-webapps` (CT 132 `192.168.10.160`, puerto `3008`).
- **Dominio Público Oficial:** `https://soporte.sigmac.app` (Proxy reverso en `Servidor-web` CT 109 `192.168.10.109`).
- **Gestor de Procesos:** Unidad systemd `siax-app-HELPDESK.service`, administrada por **SIAX Monitor** (`http://192.168.10.160:8080`).
- **Ficha MCP de Infraestructura:** **ID 35** (`category: application`, `type: webapp`, `status: ACTIVE`).

### Pasos para Desplegar:

1. **Configurar servidores de destino:**
   ```bash
   cp servers.conf.example servers.conf
   # servers.conf nunca se commitea en Git
   ```

2. **Ejecutar el script de despliegue:**
   ```bash
   ./desplegar.sh
   ```
   El script realiza:
   - Sincronización atómica de código vía `rsync` hacia `user_apps@192.168.10.160:/home/user_apps/apps/help_desk`.
   - Instalación remota de dependencias de producción y validación de migraciones MariaDB (`node config/setup.js`).
   - Reinicio sin contraseña interactiva vía API de SIAX Monitor (`POST http://192.168.10.160:8080/api/apps/HELPDESK/restart`).
   - Verificación de PID, memoria y socket TCP en LISTEN.
   - Sincronización automática de estado `ACTIVE` y URL en el MCP de Infraestructura (`http://192.168.10.160:3007/api/services/35`).

3. **Auditar estado desde terminal:**
   ```bash
   ./desplegar.sh --check
   ```

---

## 🧪 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
```

---

## 🔑 Estrategia Multicanal de Autenticación & Acceso

La plataforma cuenta con un sistema de acceso segmentado con interfaz moderna y el **Bot de Soporte** oficial del ecosistema (`/img/bot-soporte.svg`):

1. **🏢 Clientes de la Plataforma (SIGMA WebControl):**
   - Los clientes del ecosistema Telcotronics inician sesión utilizando sus credenciales corporativas habituales de **SIGMA WebControl** (`api.siax-system.net`).
   - No requieren registro previo en Help Desk; la cuenta se aprovisiona y sincroniza automáticamente con rol `client` y aislamiento multi-tenant.
2. **🌐 Nuevos Clientes (Social Auth):**
   - Acceso con un solo clic mediante **Google Identity Services (GIS)** y **Facebook Login**.
   - Permite a usuarios nuevos crear y consultar tickets de soporte inmediatamente sin formularios extensos.
3. **🛡️ Personal Técnico & Staff de Guardia (Consola Local):**
   - Reservada exclusivamente para el equipo operativo interno (`superadmin`, `admin`, `agent`).
   - Autenticación sobre MariaDB local con contraseñas seguras bajo `bcrypt`.

---

## 🔑 Credenciales para Personal Técnico (Entorno Local & Demo)

Acceso exclusivo desde la pestaña **"Personal Técnico"** en `/login?tab=staff`:

| Rol | Correo Electrónico | Contraseña | Perfil Operativo |
|---|---|---|---|
| **Superadmin** | `super@helpdesk.com` | `123456` | Administrador general de organizaciones y SaaS |
| **Admin** | `admin@helpdesk.com` | `123456` | Administrador técnico de empresa |
| **Agente** | `agent@helpdesk.com` | `123456` | Agente de soporte de guardia y despacho FSM |

> [!NOTE]
> La interfaz incluye botones de acceso rápido (1 clic) para autocompletar credenciales en ambientes de desarrollo.

---

## 📁 Documentación para Agentes e Infraestructura

- **Punto de Entrada de Agentes:** [agents.md](file:///home/pablinux/Projects/Node/help_desk/agents.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)