Guia completa de uso del WACRM (revisado en vivo: webhook, envios, Sofia/Hermes, integracion SKEEN, limitaciones)

docs/wacrm-guia-uso.md

@@ -0,0 +1,258 @@
+# WACRM — Guía de uso (SKEEN)
+
+> **Audiencia:** recepción, administración y personal no técnico de SKEEN.
+> **Última revisión:** 2026-09-06 (basada en revisión del código y pruebas en vivo del sistema; ver sección 6 "Estado actual").
+> Documento de referencia técnica general: `docs/arquitectura.md`.
+
+---
+
+## 1. ¿Qué es y para qué sirve?
+
+**WACRM** es el CRM de WhatsApp de la clínica. Permite que el personal de SKEEN:
+
+- **Reciba en una bandeja** todos los mensajes de WhatsApp que los pacientes mandan al número de la clínica.
+- **Responda** esos mensajes desde la computadora, como equipo (varias personas pueden ver la misma bandeja).
+- **Asigne cada conversación a un agente** (quién se hace cargo del paciente).
+- **Administre leads** (pacientes potenciales que escriben por primera vez) y conviértelos en **pacientes** del sistema, quedando todo ligado a la clínica.
+- Tenga un **asistente de inteligencia artificial ("Sofía")** que atiende automáticamente: responde dudas, y sobre todo **agenda citas reales** en el sistema (consulta la disponibilidad de Odoo y crea la cita).
+
+Hay **dos formas de usarlo** (sección 2): integrado dentro del sistema SKEEN (recomendado para el trabajo diario) o el WACRM "completo" en su propia pantalla (para administración: plantillas, difusiones, automatizaciones, configuración).
+
+---
+
+## 2. Cómo acceder
+
+### 2.1 Desde el sistema SKEEN (recomendado para el día a día)
+
+1. Entre a **http://192.168.10.114** (el sistema SKEEN normal) e inicie sesión con su usuario y contraseña habituales.
+2. En el menú lateral encontrará dos secciones:
+   - **Mensajes WACRM** (`/wacrm/messages`) — la bandeja de WhatsApp.
+   - **Leads WACRM** (`/wacrm/leads`) — el embudo de leads.
+
+> Si no ve esas opciones en su menú, pida al administrador que se las habilite desde *Configuración → menús por usuario*.
+
+### 2.2 WACRM directo (standalone)
+
+- **URL en la red de la clínica:** `http://192.168.10.114:3000`
+- **Dominio público configurado:** `https://skeencrm.consultoria-as.com` (el dominio interno es `skeencrm.consultoria-as.com`; el túnel Cloudflare activo en la VM enruta hoy solo `skeen.consultoria-as.com` — si el dominio de WACRM no abre, use la IP :3000 o pida a TI revisarlo).
+- **Login:** correo + contraseña (cuentas existentes: `admin@skeen.mx`, `recepcion@skeen.mx`, `ivan@horuxfin.com`; hay también una cuenta de prueba `test@skeen.mx`). Si olvida la contraseña, use "¿Olvidaste tu contraseña?" o pida a un administrador que la restablezca.
+- Al crear una cuenta nueva desde "Sign up" se entra a una **cuenta propia**; para trabajar en el mismo equipo se entra por **enlace de invitación** que el administrador envía desde Configuración (se acepta en la pantalla `/join/<token>`).
+
+### 2.3 Roles en WACRM directo
+
+Cada cuenta tiene roles: **owner** (dueño), **admin**, **agent** y **viewer**. Las configuraciones críticas (número de WhatsApp, plantillas, equipo) solo las maneja owner/admin.
+
+---
+
+## 3. Flujo diario de trabajo
+
+El ciclo normal de un paciente que escribe por WhatsApp es:
+
+```
+Paciente escribe al WhatsApp de la clínica
+        │
+        ▼
+Sofía (IA) lo saluda y atiende sola  ◄────────────┐
+   • agenda citas (disponibilidad real)          │  mientras la conversación
+   • da precios/servicios                        │  NO esté asignada a un humano
+   • consulta pagos / monedero                   │
+        │  (si el paciente pide un agente,        │
+        │   o recepción ASIGNA la conversación)   │
+        ▼                                         │
+Agente humano toma el hilo ───────────────────────┘
+        │
+        ▼
+Leads WACRM: se crea un lead "New Lead" por cada contacto con conversación
+        │  mover etapa / asignar responsable
+        ▼
+Lead ganado → "Convertir" → se crea (o liga) el PACIENTE en SKEEN
+```
+
+**Rutina recomendada cada mañana (y cada hora pico):**
+
+1. Entre a **Mensajes WACRM**. Presione **Sincronizar** (tarda hasta ~1 minuto la primera vez; trae todo lo nuevo).
+   - La pantalla también se refresca sola cada ~15 segundos.
+2. Filtre por **"No leídas"** y **"Sin asignar"**: esos son los chats que necesitan atención.
+3. Si Sofía ya resolvió el caso (ej. la cita ya quedó agendada), no hay que hacer nada.
+4. Si hay que atender a mano: **Asignar** la conversación a una persona → **seleccione "Responder como…"** (su identidad de agente) → escriba y envíe.
+   - **Al responder, la conversación queda automáticamente asignada a usted y el bot deja de intervenir** en ese chat.
+5. Si el contacto es nuevo, use el enlace **"No es paciente — Crear paciente"** para darlo de alta desde la misma pantalla (o hágalo después desde Leads).
+6. En **Leads WACRM** revise los leads nuevos: clasifíquelos (etapas), asígnelos, y cuando el paciente agenda/compra, márquelos **ganado** (idealmente con "Convertir en paciente").
+
+---
+
+## 4. Pantalla por pantalla
+
+### 4.1 Mensajes WACRM (sistema SKEEN → `/wacrm/messages`)
+
+| Elemento | Qué hace |
+|---|---|
+| Buscador | Busca conversaciones por nombre o teléfono del contacto. |
+| Botón **Sincronizar** | Trae a la pantalla los datos más recientes de WACRM (contactos, conversaciones, mensajes). Dura hasta ~1 minuto porque baja los ~9,700 contactos; espere el mensaje de confirmación. |
+| **Responder como...** | Selector de identidad de agente. **Obligatorio** para poder escribir: los mensajes salen a nombre del agente elegido y asignan la conversación a él. |
+| Filtros: Todas / Mías / Sin asignar / No leídas | "Mías" usa la identidad seleccionada. |
+| Lista de conversaciones | Nombre, teléfono, último mensaje, hora y contador de no leídos. Chip azul = asignada a alguien. |
+| Panel de chat | Historial completo. Cada burbuja indica quién escribió: **Cliente**, **Agente** o **Sofía (Bot)**. Botón **Asignar/Reasignar** arriba a la derecha (modal con el equipo; también "Desasignar conversación" en rojo — al desasignar, el bot vuelve a tomar el chat). |
+| **Ficha del paciente** | Sobre el chat se muestra el paciente de SKEEN cuyo teléfono coincide (nombre, última visita, puntos de monedero). Si no existe, aparece **"No es paciente — Crear paciente"** para crearlo con un clic. |
+| Caja de respuesta | Escriba y Enter/Enviar. El envío se hace por el mismo canal de WhatsApp de la clínica. |
+
+### 4.2 Leads WACRM (sistema SKEEN → `/wacrm/leads`)
+
+- **Vistas:** Kanban (tarjetas por etapa) y Lista. Botón **Sincronizar** igual que en Mensajes.
+- **Filtros:** pipeline, estado (Abierto/Ganado/Perdido) y asignación (Todos / Sin asignar / Míos). Resumen con conteos y valores abiertos/ganados/perdidos.
+- **Etapa** del lead: clic sobre la etapa (p. ej. "New Lead") para moverlo a otra etapa. Pipeline actual: **New Lead → Qualified → Proposal Sent → Negotiation → Won**.
+- **Estado:** botones ✔ (ganado) y ✖ (perdido) en cada fila/tarjeta.
+- **Asignar responsable** a cada lead (modal con los agentes).
+- **Convertir en paciente:** botón que crea (o liga si ya existe) el **paciente en SKEEN** usando el teléfono del contacto, y marca el lead como ganado. Es idempotente: si ya estaba convertido, solo muestra el paciente.
+- **Ir a la conversación:** enlace directo al chat del lead en Mensajes WACRM.
+- Los leads **se crean automáticamente**: cada vez que se sincroniza, todo contacto con conversación de WhatsApp y sin lead abierto recibe un lead "New Lead". No es necesario crearlos a mano.
+
+### 4.3 WACRM directo (standalone)
+
+| Sección | Para qué sirve |
+|---|---|
+| **Dashboard** | KPIs generales de la operación de WhatsApp. |
+| **Inbox** | La misma bandeja de conversaciones, versión nativa de WACRM (equivalente a "Mensajes WACRM" del sistema SKEEN). |
+| **Contacts** | Directorio de contactos: teléfono, nombre, etiquetas, notas y campos personalizados. Aquí están los ~9,700 contactos históricos. |
+| **Pipelines** | El embudo de leads (mismo pipeline que se ve en SKEEN), en tablero Kanban. |
+| **Broadcasts** | Envíos masivos por **plantilla de WhatsApp**. **Hoy no es utilizable: no hay plantillas cargadas/aprobadas** (ver sección 6). |
+| **Automations** | Reglas automáticas ("cuando entra un mensaje nuevo → hacer X"). Hoy tiene una sola regla activa: *"Nuevo mensaje → Webhook Hermes Bridge"*, que es la que conecta con Sofía — **no desactivarla**. |
+| **Flows** | Flujos conversacionales con nodos (menús con botones para el cliente). Hay un flujo "Welcome menu" en **borrador** (no activo); el agendamiento real lo hace Sofía, no los flows. |
+| **Agents** | Playground de IA (pruebas de respuestas). |
+| **Notifications** | Notificaciones internas de la plataforma. |
+| **Settings** | Perfil/contraseña, **WhatsApp** (número y tokens de Meta), **plantillas**, equipo e invitaciones, API keys, apariencia, seguridad. La configuración del número de WhatsApp solo la debe tocar un administrador. |
+
+---
+
+## 5. Sofía, la asistente de IA (WhatsApp)
+
+**Qué es:** el agente automático que contesta el WhatsApp de la clínica. En la bandeja sus mensajes aparecen como **"Sofía (Bot)"**.
+
+**Qué puede hacer por sí sola:**
+
+- **Agendar citas reales** paso a paso: pregunta el servicio (catálogo real de SKEEN), el día, muestra los **horarios disponibles de la agenda real**, pide el nombre y **crea la cita en el sistema** y la confirma al paciente. El paciente puede interrumpir o escribir "cancelar" en cualquier momento.
+- Informar de **servicios y precios** (consulta el catálogo de SKEEN).
+- Consultar **pagos pendientes** y **monedero/puntos** del paciente (por teléfono).
+- Orientar en general sobre la clínica (horarios, dirección) cuando la pregunta no encaja en lo anterior.
+
+**Reglas de conducta (cómo decide cuándo responder):**
+
+1. Responde **únicamente a mensajes que el paciente envía** (no a los que la clínica manda). Responde **24/7** — no tiene restricción de horario.
+2. **Si la conversación está asignada a un agente humano, Sofía NO responde** en ese chat. Desasignar la conversación devuelve el control al bot.
+3. Si el paciente escribe **"agente", "humano", "especialista", "doctor(a)" o "recepcionista"**, Sofía anuncia que la atenderá recepción y deja de responder automáticamente ese chat (el equipo debe verlo en la bandeja y hacerse cargo).
+4. Si hay un agendamiento en curso, continúa donde se quedó aunque el paciente escriba varias cosas ("mañana", "a las 9 am", etc.).
+5. Tiene memoria por número de teléfono (recuerda el hilo reciente de cada paciente).
+
+**Cómo tomar el control humano:** simplemente **asigne la conversación a un agente** (o respóndala; el envío la asigna solo). Para devolverla al bot, **desasígnela**.
+
+**Dónde ver sus respuestas:** en la misma bandeja (Mensajes WACRM / Inbox), con la etiqueta "Sofía (Bot)".
+
+---
+
+## 6. Estado actual y limitaciones (revisado el 2026-09-06)
+
+**Lo que FUNCIONA hoy (verificado en vivo):**
+
+- ✅ Recepción de mensajes: el webhook de WhatsApp está configurado y firmado; los mensajes de clientes entran y aparecen en la bandeja.
+- ✅ Envío de respuestas: el número de WhatsApp **+52 1 663 700 6400** está conectado, con token válido y calidad **GREEN** ante Meta; las respuestas del equipo y de Sofía salen de verdad por WhatsApp.
+- ✅ Sofía responde y agenda citas (probado con flujos reales: el 10-jul-2026 completó un agendado completo, y el 3-sep-2026 contestó un saludo).
+- ✅ Bandeja y leads integradas en el sistema SKEEN, con asignación y conversión a paciente.
+- ✅ Sincronización SKEEN ↔ WACRM funcionando (ver abajo cuánto tarda).
+
+**Lo que está a medias o apagado — importante:**
+
+- ⚠️ **Recordatorios automáticos de citas: APAGADOS a propósito.** El módulo existe (recordatorio 24 h antes, follow-up post-tratamiento, re-engagement a 90 días) y hasta está programado en la configuración, pero está **desactivado deliberadamente** hasta que la clínica use un **número de WhatsApp propio de SKEEN** (el número actual está registrado a nombre *"Consultoria Alcaraz Salazar"*). No activarlo hasta que el cliente lo autorice.
+- ⚠️ **Plantillas de WhatsApp: ninguna cargada (0).** Consecuencias: (a) los **Broadcasts** (difusiones masivas) no funcionan; (b) **no se puede escribir a un paciente fuera de la ventana de 24 horas** (regla de WhatsApp: solo con plantilla aprobada se puede iniciar conversación). Las plantillas requieren aprobación de Meta — pendiente del cliente.
+- ⚠️ **La IA "nativa" de WACRM está desactivada** (no hay configuración IA en la cuenta). La IA que atiende es **Sofía (Hermes)**. Si alguien activa la IA nativa en Settings sin coordinación, podría haber doble respuesta al cliente — no hacerlo.
+- ⚠️ **El botón "Sincronizar" tarda ~1 minuto** (baja los 9,747 contactos completos). Es normal; no repetirlo insistentemente.
+- ⚠️ Si se **elimina** una conversación en WACRM, en el sistema SKEEN puede seguir apareciendo un tiempo (la sincronización agrega/actualiza pero **no borra** registros viejos). Filtre por los chats activos.
+- ⚠️ Definir si los chats **entran en horario no laboral**: Sofía responde de noche y fines de semana (no tiene límite horario). Si la clínica prefiere que no responda fuera de horario, es un ajuste pendiente de definir.
+
+---
+
+## 7. Solución de problemas
+
+| Síntoma | Causa probable / qué hacer |
+|---|---|
+| **No llegan mensajes nuevos de clientes** | 1) Presione **Sincronizar** y espere ~1 min. 2) Si tampoco aparecen en el WACRM directo (Inbox), el problema es del webhook de Meta → avise a TI (revisar token/número en Settings → WhatsApp). |
+| **No me deja escribir** ("Selecciona tu identidad de agente") | Elija su nombre en el selector **"Responder como..."** de la barra superior. |
+| **Envío falla / no sale el mensaje** | Verifique que el mensaje sea a un número válido. Si el paciente **no ha escrito en las últimas 24 h**, WhatsApp bloquea el mensaje libre → se necesita plantilla aprobada (hoy ninguna cargada). Avise a TI si el error persiste. |
+| **El bot responde cuando no debe** | **Asigne la conversación a un agente** (botón Asignar). En cuanto esté asignada, Sofía se calla. Desasignar vuelve a activarla. |
+| **El bot no responde cuando debería** | ¿La conversación quedó asignada a alguien? Desasígnela. ¿El paciente escribió "agente/humano/doctor"? Es handoff intencional — atiéndalo usted o desasigne si fue error. Si sigue sin responder, avise a TI (revisar servicios del bridge/gateway, sección 8). |
+| **Veo conversaciones que ya no existen** | El listado del sistema SKEEN es un caché; la sincronización no borra. Use Sincronizar y concentre el trabajo en los chats activos. |
+| **Sincronizar tarda mucho o parece travado** | Normal hasta ~1 minuto (9,747 contactos). Si falla, reintente; si falla dos veces, avise a TI. |
+| **No me llegan recordatorios de citas a los pacientes** | **Esperado por ahora** — los recordatorios están apagados hasta tener el número de SKEEN y plantillas aprobadas (sección 6). |
+
+---
+
+## 8. Anexo técnico (breve)
+
+### 8.1 Arquitectura
+
+```
+Paciente (WhatsApp) 
+   │  Meta Cloud API (número +52 1 663 700 6400, calidad GREEN)
+   ▼
+Webhook → WACRM Next.js :3000  (valida firma Meta, guarda contacto/
+          conversación/mensaje, corre flows + automations)
+   │  notifica message.received
+   ▼
+Hermes Bridge :8090  (webhook-bridge.js)
+   │  omite la conversación si está asignada a humano (consulta a Odoo)
+   ▼
+Hermes Gateway :8080  (LLM "Sofía" — proveedor Nan Builders, modelo qwen3.6)
+   │  intents: agendar / servicios / monedero / pagos / otro
+   │  agendado: disponibilidad y creación de CITA real vía API de Odoo
+   ▼
+Respuesta → WACRM API (/api/v1/messages) → Meta → paciente
+
+Sistema SKEEN (React :80 + Odoo :8069) 
+   └─ proxy /skeen/frontend/v1/wacrm/*  →  caché local skeen.wacrm.* 
+      (sync desde Supabase; envío vía bridge; asignación; leads; conversión)
+```
+
+- **BD del WACRM:** Supabase self-hosted (Docker, API en :8000; tablas: contacts, conversations, messages, deals, pipelines, message_templates, automations, flows, ai_configs, whatsapp_config…). Los mensajes **se guardan en Supabase**; Odoo guarda una **copia de trabajo** (modelos `skeen.wacrm.*`).
+- **Odoo** es la fuente de verdad de: catálogo/servicios, disponibilidad de agenda, citas creadas por Sofía y pacientes (la conversión de lead crea `res.partner` con `is_patient=True, source='whatsapp'`).
+
+### 8.2 Componentes y servicios
+
+| Componente | Puerto | Servicio / proceso | Reinicio |
+|---|---|---|---|
+| WACRM (Next.js) | 3000 | `wacrm.service` (`npm start`, dir `/root/skeen-wacrm`) | `systemctl restart wacrm` |
+| Hermes Gateway (IA) | 8080 | `hermes-gateway.service` (venv `/root/hermes-venv`) | `systemctl restart hermes-gateway` |
+| Hermes Bridge | 8090 | **⚠️ ver nota** — el unit `hermes-bridge.service` está en bucle de reinicios; el proceso real sirve desde un `nohup node webhook-bridge.js` (dir `/root/skeen-roadmap-hermes/hermes`) | Matar el PID real y luego `systemctl restart hermes-bridge` (ver nota) |
+| Odoo | 8069 | `odoo-skeen.service` | `systemctl restart odoo-skeen` |
+| Nginx | 80 | `nginx` | `systemctl reload nginx` |
+| Supabase | 8000 | Docker (contenedores `supabase-*`) | `docker compose restart` en su dir |
+| Túnel público | — | `cloudflared-skeen.service` (`/root/.cloudflared/config.yml`) | `systemctl restart cloudflared-skeen` |
+
+**⚠️ Nota sobre el bridge (verificada el 2026-09-06):** desde el 14-ago-2026 existe un proceso `node webhook-bridge.js` iniciado con `nohup` (log en `/tmp/hermes-bridge.log`) que **ocupa el puerto 8090**. El servicio systemd `hermes-bridge` arranca cada 5 s, encuentra el puerto ocupado (EADDRINUSE) y sale con código 0 — acumulando cientos de miles de "reinicios" en el log. **Consecuencia práctica:** el bridge SÍ está funcionando (es el proceso nohup), pero `systemctl stop hermes-bridge` **no** lo detiene. Para operar de forma limpia: `kill <PID de "node webhook-bridge.js" con padre nohup>` y dejar que systemd lo levante (en puerto libre arranca y queda estable), o desactivar el nohup viejo. Es un pendiente de mantenimiento.
+
+**Health-check rápido:**
+- Bridge: `curl http://localhost:8090/health` → `{"status":"ok",...}`
+- WACRM: `curl -o /dev/null -w '%{http_code}' http://localhost:3000/login` → `200`
+- Gateway (IA): `systemctl status hermes-gateway`
+
+### 8.3 Configuración y datos (rutas)
+
+| Componente | Ubicación |
+|---|---|
+| Código WACRM | `/root/skeen-wacrm` (Next.js + Supabase; credenciales Meta en `wacrm.service` / `.env.local`) |
+| Bridge | `/root/skeen-roadmap-hermes/hermes/webhook-bridge.js` (memoria de Sofía por teléfono en `.../hermes/memory/<tel>.json`) |
+| Config Hermes | `/root/.hermes/config.yaml` (gateway :8080, plataforma webhook :8644, skills SKEEN) |
+| Proxy/ caché Odoo | `/root/skeen-odoo/addons/skeen_whatsapp/controllers/wacrm_proxy.py` y `models/wacrm_sync.py` |
+| Páginas del sistema SKEEN | `/root/skeen-frontend/src/pages/WacrmMessages.tsx`, `WacrmLeads.tsx` |
+| Webhook público del bridge | `https://skeen.consultoria-as.com/webhook/wacrm` (nginx → :8090) |
+
+### 8.4 Endpoints del proxy (para TI)
+
+`POST /skeen/frontend/v1/wacrm/sync` · `GET /wacrm/conversations` · `GET|POST /wacrm/messages` · `GET /wacrm/members` · `POST /wacrm/conversations/<id>/assign` · `GET /wacrm/conversations/<id>/assigned` · `GET /wacrm/pipelines` · `GET /wacrm/leads` · `PUT /wacrm/leads/<id>/status` · `POST /wacrm/leads/<id>/convert` — todos bajo `/skeen/frontend/v1/`, autenticados con token del frontend SKEEN.
+
+### 8.5 Interruptores conocidos (pendientes del cliente)
+
+| Interruptor | Dónde | Estado |
+|---|---|---|
+| Recordatorios de citas | bridge `REMINDERS_ENABLED=true` + heartbeat | **OFF a propósito** (hasta número SKEEN + plantillas + opt-in). Cron del gateway también sin ejecuciones. |
+| Re-engagement 90 días | bridge `REENGAGE_ENABLED=true` | OFF |
+| Plantillas de WhatsApp | Meta Business + Settings → Templates del WACRM | 0 cargadas → Broadcasts inoperantes |
+| IA nativa WACRM (`ai_configs`) | Settings → AI | Desactivada; usar Sofía (Hermes) |