# Manual Maestro de Soporte Técnico y Operativo — SIGNOS Platform

Este manual descargable está optimizado para alimentar bots de asistencia (OpenAI Assistants, Google Gemini Copilots, Dialogflow RAG) y guiar a agentes humanos de soporte técnico.

---

## 1. Arquitectura del Sistema
SIGNOS es una plataforma omnicanal de atención empresarial basada en microservicios, Firebase/Firestore y modelos de Inteligencia Artificial Generativa (Genkit / Gemini / OpenAI).

### Componentes Clave:
- **Frontend App:** Next.js 15 App Router en `src/app/(app)`.
- **Backend Core:** Cloud Functions for Firebase en `functions/src/services`.
- **Motor de IA:** Genkit AI con function calling y recuperación semántica (RAG).
- **Almacenamiento Seguro:** Tenant Vault con encriptación AES-256 en reposo.

---

## 2. Solución Rápida de Problemas Comunes (Troubleshooting Matrix)

| Síntoma / Problema | Causa Probable | Solución / Acción de Soporte |
|---|---|---|
| **WhatsApp no recibe mensajes entrantes** | Webhook de Meta desconectado o Token caducado | Ir a Canales -> WhatsApp -> Verificar estado del Webhook y re-generar Token en Meta Developer Portal. |
| **El AI Agent no responde o arroja error de cuota** | API Key del proveedor agotada o inválida | Verificar en Configuración -> AI Settings. Probar cambiar al modelo de respaldo (ej. Gemini 1.5 Flash). |
| **Llamadas SIP sin transcripción de voz** | Falla de credenciales en Google Cloud Speech-to-Text | Validar que la Service Account del backend tenga habilitada la API `speech.googleapis.com`. |
| **Operador no puede transferir a otra cola** | Operador no asignado a la cola destino o permisos insuficientes | Verificar en Administración -> Equipos y Colas que el usuario posea el rol adecuado (Agente o Supervisor). |

---

## 3. Guía de Combinaciones de Funcionalidades (Recetas Operativas)

### Receta A: Bot E-Commerce con Escalada y Stock
- **Configuración:** Crear un AI Agent asignado al canal WhatsApp.
- **Herramienta asociada:** Habilitar Function Call `check_inventory` apuntando al módulo ERP.
- **Regla de Escalada:** Configurar en el System Prompt: *"Si el producto no tiene stock, ofrecer producto alternativo. Si el cliente solicita hablar con ventas, transferir al departamento comercial."*

### Receta B: Enrutamiento VIP por Workflows
- **Configuración:** En el Workflow entrante, colocar un nodo **CRM Check**.
- **Condición:** Si la etiqueta del contacto en CRM es `VIP` o `Enterprise`, derivar directamente al nodo **Queue Transfer** con prioridad alta (Nivel 1), omitiendo el bot de bienvenida estándar.

---

## 4. Límites Operativos de la Instancia
- **Tamaño máximo de archivo en RAG:** 25 MB por documento PDF/DOCX.
- **Timeout en nodos HTTP Request:** 10 segundos por petición.
- **Reintentos en fallas de webhook saliente:** Hasta 3 intentos con backoff exponencial.

---

## 5. Gateway PBX SIGNOS — SBC Local Instalable (`signospbx-int`)

Cuando un cliente posee una central telefónica en su propia oficina (FreePBX, Asterisk, 3CX) sin IP pública directa, debe instalar el módulo **Gateway PBX SIGNOS (SBC)**.

### Instrucciones para el Operador / Bot:
1. **Instalación:** Indicar al cliente que ejecute `npm install && npm start` dentro del directorio `signospbx-int` en un servidor Node.js local de su red.
2. **Puertos:**
   - **Puerto 3456 (HTTP):** Panel Web de Administración (acceso en `http://localhost:3456`).
   - **Puerto 3457 (HTTP):** Servidor Outbound para túneles (Ngrok / Cloudflare).
   - **Puerto 5080 (SIP UDP/TCP):** Puerto donde la central FreePBX enviará las llamadas entrantes.
3. **Enlace con SIGNOS:** En `config.json`, el cliente debe completar `instanceId`, `integrationId` y `webhookUrl` (apuntando a la Cloud Function de SIGNOS).