CRM Owelign — documentación técnica

De punta a punta: qué piezas hay, cómo se hablan, qué hace cada archivo, cómo se configura, cómo se despliega y qué trampas ya costaron tiempo.

1. Visión general

El CRM es Chatwoot (licencia MIT, imagen oficial fijada en docker-compose.yaml) más un servicio propio en Node, el sidecar, que agrega todo lo que Chatwoot no trae:

• Elena: bot de calificación por WhatsApp (guion determinista + Gemini opcional).
• Alertas por inactividad en dos niveles y reasignación automática en cadena.
• Aviso de cierre fuera de horario y recordatorios de conversaciones pendientes.
• App del equipo (crm.*): una sola página con chat, resumen del día, marketing, proformas, caja, personas y asistente IA.
• Proformas y caja: lectura con IA de los PDF de SAP que manda un asesor, flujo de cobro.
• Asistente IA: preguntas en lenguaje natural contestadas con SQL de solo lectura sobre vistas en español.
• Atribución de marketing: origen del lead por código en el texto del enlace wa.me o por el referral de Meta.

El código fuente de Chatwoot no vive en el repo: no hay fork. Las personalizaciones de Chatwoot son archivos montados como volumen (overrides/, brand/). Actualizar Chatwoot es cambiar un tag y re-verificar esos archivos (§18.5).

Principios del diseño

• Una sola fuente de verdad: los datos del CRM viven en la base de Chatwoot (Postgres). Lo propio va en custom_attributes (jsonb) o en el esquema crm. Un solo respaldo.
• El estado de Elena se deriva, no se guarda: el paso del bot sale de qué atributos le faltan al contacto.
• Sin build step: el sidecar es Node + Express; la app es HTML + JS plano. Dependencias de producción: express y pg. Nada más.
• Lógica pura separada de los efectos: elena.js, reassign.js, lib.js no hacen red y son lo que se testea; server.js ejecuta.
• Los permisos los pone Chatwoot: la app habla con la API del chat con las credenciales de quien está adentro.

2. Arquitectura

Flujo de un mensaje entrante de WhatsApp

Cliente escribe por WhatsApp
  → Meta llama a https://chat.owelign.com/webhooks/whatsapp/+<numero>
  → Chatwoot crea/actualiza contacto y conversación (nace en "pending" porque hay un Agent Bot)
  → Chatwoot llama al webhook del Agent Bot: https://dashboard.owelign.com/bot/<secreto>
  → sidecar responde 200 al instante y procesa en segundo plano (handleBotEvent)
      → lee contacto + hilo; decide el paso (Gemini o guion)
      → guarda atributos (merge del hash completo), manda el mensaje con el token del bot
      → al terminar: asigna equipo, asigna asesor, pasa a "open", marca traspasado_en, deja el resumen
  → desde ahí la atiende un humano; el ciclo de alertas vigila cada 60 s

Flujo de la app del equipo

Navegador → crm.owelign.com (Caddy) → sidecar :4000
  /login           correo + contraseña del chat → POST /auth/sign_in de Chatwoot → cookie cifrada
  /                index.html + app.js (sin build)
  /cw/…            puente a /api/… de Chatwoot con los tokens devise de esa persona
  /datos/…         tableros, proformas, personas, asistente (lógica del sidecar)
  wss://chat.…/cable  el mismo websocket del chat, con el pubsub_token de la persona

3. Repositorio

GitHub: Owelign-Porceramica/CRM. Ramas: main = producción, develop = dev.

docker-compose.yaml     rails, sidekiq, postgres, redis, dashboard (sidecar), caddy (perfil prod)
Caddyfile               dominios y reverse proxy; dominios salen del .env
.env.example            plantilla de configuración (el .env real nunca se commitea)
brand/                  logos, manifest, custom.css y 3 scripts inyectados en el frontend de Chatwoot
overrides/              archivos de Chatwoot pisados por volumen (layout, locales, modelos, controladores)
sidecar/                servicio propio: Node 22 + Express + pg
  src/server.js         rutas HTTP, webhook de Elena, ciclo de alertas, efectos sobre Chatwoot
  src/elena.js          guion determinista de Elena (lógica pura)
  src/gemini.js         Elena con Gemini, mismo contrato que el guion
  src/reassign.js       alertas, ventanas horarias, reparto, cierre, pendientes (lógica pura)
  src/agentes.js        activar/desactivar agentes por SQL; pool de Postgres compartido
  src/personas.js       alta de personas, roles de la app (crm.roles), enlace de contraseña
  src/proformas.js      proformas: tabla, validación, lectura con Gemini, estados, espera
  src/asistente.js      asistente IA: vistas, usuarios de Postgres de solo lectura, bucle con Gemini
  src/auth.js           sesión cifrada AES-GCM, comparación en tiempo constante, límite de intentos
  src/lib.js            agregaciones de tableros (lógica pura)
  src/views.js          páginas de login y de "poner contraseña"
  src/app/index.html    la app del equipo (una página)
  src/app/app.js        la app del equipo (JS plano)
  test.js               tests con node:test (lógica pura)
  probar-gemini.js      conversación real contra Gemini, sin desplegar
  probar-e2e.js         server.js real contra un Chatwoot falso que graba las llamadas
scripts/                operación: deploy, altas, bajas, roles, ajustes, marca, respaldos, dev
docs-site/              este sitio (docs.crm.owelign.com)
*.md                    manuales: MANUAL-SISTEMAS, GUIA-CHATS, DEPLOY, BD-LOCAL, ELENA-GEMINI, MANUAL-MARKETING, INFORME-FASE-1

4. Servicios (Docker Compose)

Volúmenes: storage_data (adjuntos de Chatwoot), postgres_data, redis_data, caddy_data/caddy_config (certificados).

Dominios en el Caddyfile

5. Personalizaciones de Chatwoot

Chatwoot no tiene puntos de extensión para su frontend ni para sus modelos. Todo se hace pisando archivos de la imagen por volumen. Cada actualización de Chatwoot obliga a re-comparar estos archivos.

Configuración de Chatwoot que no está en archivos

• DISABLE_ENTERPRISE=true: MIT puro, permite rebrandear sin licencia.
• InstallationConfig DISPLAY_MANIFEST=false: oculta el banner de "versión nueva" (ver §18).
• PRESENCE_DURATION=300: un agente cuenta como conectado 5 min desde su último latido (de fábrica eran 20 s, igual al intervalo del latido: casi todos aparecían desconectados).
• DEFAULT_LOCALE=es; zona de la cuenta America/Costa_Rica.
• scripts/brand.sh escribe nombre, logos, URLs de términos/privacidad y color de marca.

6. El sidecar

Un proceso Node (node src/server.js) que es a la vez servidor HTTP, receptor del webhook de Elena y un ciclo periódico (setInterval) de alertas. Arranca en :4000 y loguea Dashboard escuchando en :4000.

Al arrancar

• Exige CHATWOOT_URL, CHATWOOT_TOKEN, CHATWOOT_ACCOUNT_ID, DASH_USER, DASH_PASSWORD (≥12 caracteres). Si falta alguna, no arranca.
• Con INTAKE_ENABLED=true exige además INTAKE_BOT_SECRET (≥32), CHATWOOT_BOT_TOKEN e INTAKE_INBOX_IDS.
• Recarga los roles de la app desde crm.roles al arrancar y cada 60 s.
• Loguea si Elena responde con Gemini o con el guion, y el horario de atención.
• Las tablas propias (crm.*) y las vistas (asistente.*) se crean solas con CREATE … IF NOT EXISTS en la primera consulta. No hay migraciones aparte.

Cómo habla con Chatwoot

7. Autenticación y sesiones

Login de la app (POST /login)

1. Si usuario y contraseña coinciden con DASH_USER/DASH_PASSWORD (comparación en tiempo constante, sin revelar cuál de los dos falló) → sesión rol panel (Marketing, sin chat).
2. Si no, se intenta POST /auth/sign_in en Chatwoot. Si la persona no pertenece a la cuenta o tiene MFA, se rechaza con un mensaje claro.
3. El rol: admin si es administrador de la cuenta; si no, el de crm.roles, y si no tiene fila, las listas CAJERAS/RECEPCIONISTAS del .env; por defecto vendedor.

La cookie

• dash_session, cifrada con AES-256-GCM (no solo firmada: lleva el token de sesión del chat). Clave = SHA-256 de dash-session-v2: + DASH_PASSWORD.
• HttpOnly, SameSite=Strict, Secure cuando FORCE_SSL=true. Dura 12 h.
• Cambiar DASH_PASSWORD cierra todas las sesiones.
• Si Chatwoot responde 401 por el puente, se borra la cookie (evita el bucle login → app → 401).
• POST /logout cierra también la sesión del chat (DELETE /auth/sign_out).

Protecciones

• Límite de intentos: 8 fallos por IP cada 15 min → 429. Con FORCE_SSL se confía en un proxy (trust proxy 1) para leer la IP real; sin proxy no, para que no se pueda falsear.
• CSRF: /cw/* y /datos/asistente exigen la cabecera X-CRM: 1, que un formulario de otro sitio no puede mandar.
• CORS de /api: solo el origen FRONTEND_URL (el chat). Cualquier otro origen → 403.
• Poner contraseña: /login?t=<token> usa el mismo reset_password_token de Devise (lo genera personas.js o agente.sh, vence en 6 h). Exige la complejidad de Chatwoot (6+, mayúscula, minúscula, número, símbolo) y entra directo.

8. Roles y permisos

Chatwoot solo conoce administrador y agente. Los demás roles los define el sidecar.

Fuente del rol, en orden: tabla crm.roles (lo que se elige en Configuración → Personas) → lista CAJERAS → lista RECEPCIONISTAS → vendedor. El servidor revalida el rol en cada endpoint; el ocultar vistas en app.js es solo presentación.

9. API HTTP del sidecar

Públicas (sin sesión)

Desde el frontend del chat (/api, cabeceras devise access-token, client, uid)

Con sesión de la app

Errores: una caída del chat devuelve 502 con {error, detalle}; la app lo muestra como error, nunca como "no hay datos". Tamaño excedido → 413.

10. La app del equipo (crm.*)

• Una página (src/app/index.html + app.js), sin librerías ni build. Lo que ve cada quien sale de VISTAS[rol].
• Vistas: Asistente IA · Conversaciones · Resumen del día · Equipo (chat interno, Próximamente) · Nuevo cliente · Proformas · Caja · Marketing · Configuración (agentes y personas). La búsqueda del encabezado (clientes) está para todos.
• Tiempo real: abre el mismo websocket de Chatwoot (wss://chat…/cable) con el pubsub_token de la persona; si se cae, reintenta, y de respaldo refresca cada 30 s.
• Conversaciones: respuestas predefinidas con /, notas privadas con Shift+Enter, adjuntos, asignar, resolver, estado del lead. Las plantillas de WhatsApp (fuera de las 24 h) se mandan desde el chat clásico.
• Presencia: con acceso al chat, la app mantiene la presencia como el chat; caja no tiene websocket, así que nunca aparece conectada ni recibe asignaciones.

11. Elena — bot de calificación

Mecanismo

Elena es un Agent Bot de Chatwoot (tipo webhook) asignado a las bandejas de INTAKE_INBOX_IDS. Con un bot asignado, la conversación nace en pending; mientras siga así, el sidecar contesta. En cuanto pasa a open, Elena no vuelve a meterse.

Eventos que procesa (handleBotEvent)

• Solo message_created. Los salientes públicos se revisan por proformas (§13). Se ignoran privados, otras bandejas y conversaciones que no estén en pending.
• Si el cliente contesta una plantilla que mandó un asesor (quienLoReactivo), la conversación se abre con ese asesor sin pasar por Elena.

El guion (elena.js, 10 nodos)

• Estado derivado: si falta nombre toca N1; si falta motivo_contacto, N2; etc. Un reinicio no pierde el hilo y un cliente que vuelve no repite el cuestionario. Solo las repreguntas van en memoria (flowState).
• Una sola repregunta (MAX_REPREGUNTAS=1); después traspasa con lo que haya. intake=incompleto no vuelve a recibir preguntas.
• Cédula: física 9 dígitos, jurídica 10, DIMEX 11–12; con o sin guiones. Separa nombre y cédula en cualquier orden y descarta teléfonos de 8 dígitos. No valida dígito verificador.
• Botones reales de WhatsApp (input_select), máx. 3 y 20 caracteres por título (se recorta por palabra).
• Merge obligatorio: el PUT /contacts/:id reemplaza el hash completo de custom_attributes; se relee el contacto y se mezcla, o se borraría la atribución de marketing.

Gemini (gemini.js)

const step = (GEMINI_API_KEY && await geminiStep(...)) || nextStep(contact, payload.content, opts);

• Mismo contrato que el guion: {action, message, items, save, cola, resumen}. Gemini decide; server.js ejecuta igual.
• geminiStep devuelve null ante cualquier problema (sin clave, cuota, timeout de GEMINI_TIMEOUT_MS=12 s, JSON roto, salida inválida) y contesta el guion. El guion nunca se apaga.
• La salida del modelo es entrada no confiable: solo puede escribir 6 campos; enums cerrados; un dato solo se guarda si el cliente lo dijo (se cerró el caso de inventar tipo_proyecto/zona); parseNombreYCedula rellena lo que el modelo omita. Detalle en ELENA-GEMINI.md.
• Llamada con fetch nativo a generativelanguage.googleapis.com/v1beta; sin SDK.

Traspaso (el orden importa)

1. Cola: INTAKE_COLA_UNICA (hoy general) o, si está vacía, por motivo (cotizar→ventas, problema→soporte, otra_consulta→general). Los equipos se buscan por nombre exacto, en minúscula.
2. Candidatos: toda la cuenta (no los miembros del equipo), sin recepción ni caja.
3. Asesor: el que atendió la última conversación del contacto si está conectado (asesorPrevio); si no, el conectado con menos abiertas (pickLeastLoaded). Si nadie está conectado, igual se asigna al de menos carga: un lead sin dueño no lo ve nadie.
4. POST assignments {team_id} y después POST assignments {assignee_id} — dos llamadas: el controlador es if assignee_id … elsif team_id.
5. Recién entonces toggle_status → open. Asignar antes de abrir: si se abre primero, el auto-reparto de Chatwoot ("Default Policy") corre en el after_save y pisa la elección.
6. Marca traspasado_en en la conversación (arranca el reloj de alertas) y deja el resumen como nota privada: "📋 David busca porcelanato tipo mármol para un proyecto en construcción desde Guanacaste. Cédula …"

Origen del lead

• Meta Click-to-WhatsApp: content_attributes.referral del primer mensaje → utm_source=meta-ads|meta-post, utm_campaign=<id del anuncio>. Gana sobre el código.
• Código en el texto: WhatsApp descarta los parámetros de wa.me, así que el código viaja en el texto pre-escrito: https://wa.me/506XXXXXXXX?text=Hola,%20quiero%20info%20[IG-JUL01]. Regex \[([A-Za-z]{2,6})-([A-Za-z0-9]{2,20})\]; redes: ig, fb, tt, go, wa, web, qr.
• Se guarda el primer origen y nunca se sobrescribe. Sin origen → "Directo / sin origen". Guía de códigos: MANUAL-MARKETING.md.

Fuera de horario

HORARIO_ATENCION (hoy 08:00-18:00, zona del servidor). Elena avisa el horario completo en el saludo y en el cierre, pero califica igual: el asesor encuentra el lead listo al abrir. No distingue fines de semana ni feriados; no admite franjas que crucen medianoche.

12. Alertas, reparto y ciclo periódico

Con REASSIGN_ENABLED=true, cada REASSIGN_EVERY_SECONDS (60) corre revisarAlertas(), en este orden: aviso de cierre → recordatorios de pendientes → detección de asignación manual → aviso suave → escalación.

Dos relojes

• Desde cuándo espera (esperaDesde): el mayor de waiting_since (cliente escribió y nadie respondió) y traspasado_en (Elena entregó y nadie saludó: su despedida limpia waiting_since). Los mensajes del bot no cuentan como respuesta.
• Las horas cerradas no cuentan: el reloj arranca a la apertura.
• Escalación en cadena sin tope: pasa al siguiente conectado con menos carga que no la haya tenido en esta vuelta (createReassignTracker); al agotar la lista, vuelve a empezar; nunca dos veces seguidas al mismo. Si nadie está conectado, no se mueve y deja la nota "no hay ningún asesor conectado".
• Asignación manual respetada: si alguien reasigna a mano (cambio de asesor entre dos vueltas que no hizo el ciclo), el elegido recibe su plazo completo y el aviso suave de bienvenida.
• Solo actúa sobre conversaciones con asesor y fuera de Elena. Recepción y caja nunca reciben escalaciones. Todo lo firma el bot.
• Estado en memoria del proceso (tracker, avisados, último asesor visto): un reinicio lo olvida, a lo sumo no detecta un cambio manual de ese mismo minuto.

Aviso de cierre (AVISO_CIERRE)

• Al que escribió y nadie le contestó: "Ya cerramos por hoy 🌙 Tu mensaje quedó anotado…". Al que dejó de responder y la conversación estuvo viva hoy: variante sin "quedó anotado".
• Una sola vez por noche; vuelve a habilitarse cuando el asesor contesta. Da 2 min de gracia. No se manda fuera de la ventana de 24 h de WhatsApp.

Pendientes (PENDIENTE_AVISO)

• Conversaciones que una persona puso en pendiente (no las que está calificando Elena): etiqueta pendiente + recordatorio que menciona al asesor cada PENDIENTE_CADA_MINUTOS (2), hasta PENDIENTE_MAX_AVISOS (10). Al reabrir o resolver, la etiqueta se cae.

13. Proformas y caja

Tres formas de entrar

1. Por WhatsApp: cuando un asesor manda un PDF al cliente, el webhook (evento saliente) lo baja y Gemini lo lee con un esquema JSON estricto. Si es una proforma, queda en crm.proformas_espera y se deja nota privada. En la conversación aparece la barra "Proforma … pendiente · Enviar" (brand/proformas.js). Cuando el cliente llega a la tienda, el asesor toca Enviar y recién ahí se crea en crm.proformas y la ve caja. Descartar la saca sin crearla.
2. Foto o PDF desde la app: /datos/proformas/leer devuelve los datos para el formulario; el vendedor revisa y guarda.
3. Manual: formulario en la app.

Reglas

• Los montos del navegador no se creen: totales() recalcula subtotal, IVA (13 %) y total desde las líneas. El precio por línea se guarda neto de descuento.
• Si los montos leídos por la IA no cuadran entre sí, la proforma entra en estado revisar.
• Estados: revisar · pendiente · pagada · anulada. Los cambian caja y admin. El vendedor solo puede reenviar a pendiente las suyas que caja devolvió a revisar.
• Devolver a revisar exige motivo. pagada exige medio (SINPE Móvil, Transferencia, Tarjeta, Efectivo), monto > 0 y referencia (salvo efectivo).
• Cada cambio se agrega a historial (de, a, por, cuándo, pago, nota). El UPDATE es condicional al estado de origen cuando aplica: si otro lo cambió, 409.
• numero es único: no se puede crear dos veces la misma oferta (doble clic, o ya cargada a mano).

14. Asistente IA

• Gemini no ve las tablas de Chatwoot: ve el esquema asistente, vistas en español ya filtradas a la cuenta, con horas en Costa Rica y sin nada sensible: asesores, conversaciones, contactos, mensajes, proformas, proforma_lineas.
• El modelo escribe un SELECT, el sidecar lo corre y le devuelve las filas; puede encadenar hasta 6 consultas por pregunta (200 filas, 400 caracteres por celda, 40 000 caracteres por resultado). Historial de 12 turnos. Timeout ASISTENTE_TIMEOUT_MS (30 s).
• La barrera es Postgres, no el prompt:
  • Cada consulta entra con un usuario de login propio: crm_ia_todo (admin, panel, recepción) o crm_ia_u<id> (vendedor). Solo tienen SELECT sobre las vistas (vía el rol crm_ia), contraseña aleatoria por arranque en memoria, máx. 3 conexiones.
  • Lo que ve el vendedor lo decide current_user dentro de la vista; ese usuario no es miembro de otro rol, así que SET ROLE no lo saca.
  • Transacción READ ONLY y statement_timeout de 5 s.
• Admin ve también el SQL usado, para confiar en el número.

15. Tableros

• Leen con CHATWOOT_TOKEN y caché de 60 s (contactos y rendimiento). Contactos paginados de 15 en 15 hasta 200 páginas (~3000).
• Resumen del día: leads hoy/ayer; embudo de 7 días (Leads → Contactados → Cotizados → Vendidos, por estado_lead); equipo con métricas de 30 días (/api/v2 summary_reports/agent) y abiertas. Si el reporte falla, se dice; no se pinta vacío.
• Marketing: 30 días contra los 30 anteriores; canales siempre visibles (instagram, facebook, tiktok, sin origen); campañas con cotizados y vendidos. La conversión se mide sobre el total de leads, no sobre los cerrados.
• Configuración: agentes (activar/desactivar) y personas (alta, rol, enlace).

Activar / desactivar (agentes.js)

Chatwoot solo sabe borrar (y el borrado se lleva el nombre del historial). Desactivar hace por SQL: quita account_users, quita equipos y bandejas, pone confirmed_at=NULL y tokens='{}' (cierra sesiones). Todo lo quitado queda en users.custom_attributes->'desactivado' para que Reactivar lo reponga igual. No deja desactivar al último admin, a uno mismo ni a un super admin.

16. Base de datos

Un Postgres, base chatwoot_production. ~99 tablas de Chatwoot (casi sin foreign keys declaradas: las sostiene Rails) + dos esquemas propios.

Tablas de Chatwoot que importan

Esquema crm (propio)

Esquema asistente: solo vistas (§14), recreadas con CREATE OR REPLACE. Las migraciones de Chatwoot no tocan ninguno de los dos, y el respaldo de la base los lleva.

17. Configuración (.env)

El .env se lee al arrancar: tras editarlo hay que recrear el servicio (docker compose --profile prod up -d --no-deps --force-recreate <servicio>); deploy.sh no lo hace porque no viene por git.

18. Despliegue

18.1 Ambientes

Los clones son del usuario deploy con llave de solo lectura del repo. Nunca se copian archivos a mano: se despliega lo que está en la rama.

18.2 scripts/deploy.sh

git pull --ff-only y reinicia solo lo que cambió:

Todo el script va entre { }: bash lee el archivo por partes mientras corre y el pull lo puede reescribir (tumbó prod un minuto el 2026-10-09). Si el propio script cambió, se relanza la versión nueva.

18.3 Flujo de un cambio

PR → develop → (deploy dev) → probar en dev.chat.owelign.com
   → merge develop → main → el admin corre en el VPS:  cd /opt/crm && ./scripts/deploy.sh

Verificar: docker ps; docker logs --tail 20 crm-dashboard-1 debe decir Dashboard escuchando en :4000; curl https://chat.owelign.com/health → {"status":"woot"}; curl https://dashboard.owelign.com/health → {"ok":true}.

18.4 Instalación desde cero

1. DNS: registros A de cada dominio a la IP del VPS (Spaceship, zona owelign.com). Antes de levantar Caddy: si no resuelven, Let's Encrypt bloquea reintentos por horas.
2. Docker oficial + ufw con solo 22, 80, 443.
3. Clonar en /opt/crm, cp .env.example .env, generar secretos (openssl rand).
4. docker compose up -d postgres redis → docker compose run --rm rails bundle exec rails db:chatwoot_prepare (obligatorio la primera vez) → docker compose --profile prod up -d.
5. ./scripts/brand.sh; crear el admin; zona horaria de la cuenta; ./scripts/ajustes.sh.
6. WhatsApp Cloud (bandeja manual, webhook en Meta suscrito a messages) y el Agent Bot de Elena. Paso a paso en DEPLOY.md.
7. Respaldo diario con BACKUP_REMOTE fuera del servidor.

18.5 Actualizar Chatwoot

./scripts/backup.sh
sed -i 's|chatwoot/chatwoot:vX.Y.Z|chatwoot/chatwoot:vA.B.C|' docker-compose.yaml
docker compose --profile prod pull && docker compose --profile prod up -d
docker compose exec -T rails bundle exec rails db:chatwoot_prepare   # las migraciones NO corren solas
docker compose restart rails sidekiq

Checklist después de actualizar:

• Comparar overrides/*.rb y vueapp.html.erb con los de la imagen nueva (fuera de lo nuestro, deben ser iguales).
• Ajustes → Agentes muestra Desactivar; admin entra con Todos; vendedor sin pestañas; panel de conversación con solo dos secciones; barra de proforma visible.
• rel="manifest" presente y DISPLAY_MANIFEST en false.
• Los títulos de notificaciones.es.yml siguen aplicando (I18n.t(...)).

18.6 Este sitio de documentación

Vive en docs-site/ y lo sirve el mismo Caddy de prod como archivos estáticos (bloque {$DOCS_DOMAIN:docs.crm.owelign.com}, volumen ./docs-site:/srv/docs:ro). Requiere el registro DNS A docs.crm → IP del VPS. Editar el HTML y desplegar main lo actualiza; no hace falta reiniciar nada.

19. Scripts de operación

20. Pruebas

cd sidecar
npm test                      # node --test, lógica pura, TZ=America/Costa_Rica
node probar-gemini.js         # conversación de 5 turnos contra Gemini real
node probar-e2e.js            # server.js real contra un Chatwoot falso que graba las llamadas
node probar-e2e.js --guion    # lo mismo forzando el guion

Sin frameworks ni dependencias de desarrollo. Varios tests documentan fallos reales de producción (un saludo guardado como nombre, un origen sobrescrito, el eje del gráfico mintiendo). El E2E comprueba lo que los unitarios no pueden: el merge de atributos, el token del bot, el orden equipo → asesor → open, y el resumen como nota privada. Antes de mergear a main, los tests en verde.

Base local

BD-LOCAL.md: bajar una copia fresca de prod, restaurarla en local y levantar el CRM contra ella. Los respaldos restaurados se prueban: un respaldo que nunca se restauró no es un respaldo.

21. Trampas conocidas

22. Límites conocidos

• El horario no sabe de fines de semana ni feriados: el aviso de cierre de un viernes dice "mañana".
• Sin SMTP: no hay invitaciones por correo ni recuperación de contraseña por correo.
• La clave compartida del panel no deja auditoría de quién entró.
• Ocultar menús es interfaz, no permiso (salvo Contactos).
• Estado de alertas en memoria: un reinicio olvida el historial de la cadena.
• Topes "ponytail": ~3000 contactos en tableros, 300 filas en Clientes, 250 conversaciones abiertas en el resumen. Paginar si el negocio crece.
• Las proformas se leen solo si hay GEMINI_API_KEY.

Fuente: el código y los manuales del repositorio Owelign-Porceramica/CRM. Si algo de aquí contradice al código, manda el código: corregir este archivo (docs-site/index.html).