From 8280eafcbb948023c78d2778f68f2d1b293af925 Mon Sep 17 00:00:00 2001 From: Isaac_Aracena Date: Thu, 25 Jun 2026 03:08:50 +0000 Subject: [PATCH] Actualizar README.md --- README.md | 857 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 855 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 084c588..402ec62 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,856 @@ -# chat-de-whatsapp-propuestas-ejecutadas +# Chat de WhatsApp - Propuestas Ejecutadas -Backup público automático del workflow n8n: Chat de WhatsApp - Propuestas Ejecutadas \ No newline at end of file +> Workflow n8n que permite registrar propuestas ejecutadas y propuestas externas desde WhatsApp, analizar evidencias con IA, generar una presentación automática, guardar el reporte en Google Sheets y relacionarlo con el banco original de propuestas cuando existe un match confiable. + +--- + +## INFORMACIÓN GENERAL + +| Campo | Detalle | +| ------------------------ | -------------------------------------------------------- | +| Proyecto | Chat de WhatsApp - Propuestas Ejecutadas | +| Área | CDC | +| Estado | Versión Final | +| Developer Principal | Isaac Aracena | +| IT Manager | Luis Matos | +| Product Owner | Máximo Gómez | +| Ciclo Shape Up | CDC Fulgencio V2.0 | +| Repositorio Gitea | `chat-de-whatsapp-propuestas-ejecutadas` | +| Workflow n8n | Chat de WhatsApp - Propuestas Ejecutadas - Versión Final | +| Estado del workflow | Activo | +| Canal principal | WhatsApp | + + +--- + +## OBJETIVO + +### Problema que resuelve + +Antes de este workflow, las evidencias de propuestas ejecutadas o propuestas externas podían recibirse por mensajes sueltos, fotos, videos o notas de voz sin una estructura clara. Esto dificultaba mantener trazabilidad, generar presentaciones de ejecución, relacionar la evidencia con propuestas originales y alimentar correctamente el ecosistema de Fulgencio. + +El proceso manual también podía provocar pérdida de evidencias, duplicidad de links, falta de resumen ejecutivo, archivos desorganizados en Drive y poca visibilidad para futuras consultas desde FulgencioChat. + +### Solución implementada + +Este workflow permite que los usuarios autorizados registren evidencias desde un grupo oficial de WhatsApp. El bot guía al usuario por un flujo controlado: + +1. Inicio del reporte. +2. Nota de voz obligatoria. +3. Imágenes obligatorias. +4. Videos opcionales. +5. Análisis con Gemini. +6. Generación de presentación. +7. Registro en Google Sheets. +8. Organización de evidencias en Drive. +9. Relación con el banco original si hay match confiable. +10. Respuesta final por WhatsApp con el link de presentación. + +El flujo soporta propuestas ejecutadas y propuestas externas. Si la ejecución corresponde con alta confianza a una propuesta del banco original, actualiza el banco con el enlace de la presentación ejecutada. Si no hay match suficiente, registra el caso sin modificar el banco original. + +### Usuarios / Beneficiarios + +| Usuario | Beneficio | +| --------------------------- | ----------------------------------------------------------------------- | +| Managers / equipo operativo | Pueden registrar evidencias directamente desde WhatsApp. | +| Equipo CDC | Recibe presentaciones de ejecución ordenadas y consultables. | +| Equipo IT | Mantiene trazabilidad técnica y control del flujo automatizado. | +| FulgencioChat V3 | Puede consultar luego las propuestas ejecutadas y externas. | +| Responsables de proyectos | Tienen visibilidad sobre ejecuciones reales y evidencias. | +| GomezLee Marketing | Centraliza información histórica para futuras propuestas y referencias. | + +--- + +## ARQUITECTURA + +### Diagrama de flujo + +```txt id="itjmke" +[Webhook Evolution WhatsApp] + ↓ +[Normalizar evento WhatsApp] + ↓ +[Filtro origen / grupo permitido] + ↓ +[Leer sesiones existentes] + ↓ +[Resolver sesión] + ↓ +[Switch decisión sesión] + ├── Crear sesión + ├── Continuar sesión + ├── Cancelar sesión + └── Avisos controlados + +[Flujo activo] + ↓ +[Audio obligatorio] + ↓ +[Imágenes obligatorias] + ↓ +[Videos opcionales] + ↓ +[Enviar aviso procesando] + ↓ +[Recuperar media] + ↓ +[Subir evidencias a Drive] + ↓ +[Analizar audio / imágenes / videos con Gemini] + ↓ +[Control Redis de conteo y lock] + ↓ +[Consolidar análisis multimedia] + ↓ +[Gemini genera JSON final] + ↓ +[Match contra Banco de Propuestas] + ↓ +[Guardar propuesta ejecutada / externa] + ↓ +[Crear carpeta y presentación] + ↓ +[Insertar imágenes y limpiar slides vacíos] + ↓ +[Actualizar links en Sheets] + ↓ +[Actualizar banco original si match alto] + ↓ +[Enviar mensaje final por WhatsApp] +``` + +### Stack tecnológico + +| Componente | Tecnología | Propósito | +| ----------------------- | -------------------------- | ------------------------------------------------ | +| Automatización | n8n | Orquestación del flujo | +| Sesiones | Google Sheets | Controlar estado de cada reporte | +| Evidencias | Google Drive | Guardar audios, imágenes, videos y presentación | +| IA multimedia | Gemini | Analizar audio, imágenes y videos | +| IA final | Gemini | Generar JSON estructurado del reporte | +| Control de concurrencia | Redis | Contar análisis y evitar cierres duplicados | +| Registro operativo | Google Sheets | Guardar eventos, media, análisis y reporte final | +| Presentaciones | Google Slides / Drive | Crear presentación automática de ejecución | +| Banco original | Google Sheets | Relacionar ejecución con propuesta original | +| Versionado | Gitea | Backup del workflow y documentación | + +### Integraciones externas + +| Sistema | Tipo de integración | Datos que fluyen | +| ------------------- | ---------------------- | --------------------------------------------------------------- | +| Google Sheets | OAuth | Sesiones, eventos, media, análisis y reporte final | +| Google Drive | OAuth | Carpetas, evidencias y presentación generada | +| Google Slides API | OAuth / HTTP Request | Reemplazo de textos, inserción de imágenes y limpieza de slides | +| Gemini | API / n8n nodes | Análisis de audio, imagen, video y JSON final | +| Redis | Redis node | Conteo de análisis, locks y control de cierre | +| Banco de Propuestas | Google Sheets | Match y actualización de link ejecutado | +| Gitea | Git / backup | Export del workflow y README | + +--- + +## FUENTES Y DESTINOS + +### Google Sheet principal + +| Campo | Detalle | +| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------- | +| Documento | Fulgencio - Propuestas Ejecutadas | +| Uso | Registro operativo del flujo de WhatsApp | +| Hojas principales | `wa_ejecuciones_sesiones`, `wa_ejecuciones_eventos`, `wa_ejecuciones_media`, `wa_ejecuciones_analisis_media`, `propuestas_ejecutadas` | + +### Banco original de propuestas + +| Campo | Detalle | +| ------------- | ----------------------------------------------------------------------------- | +| Documento | BANCO DE PROPUESTAS DE CDC PARA FULGENCIO FUMADO | +| Hoja | propuestas | +| Uso | Fuente para identificar si una ejecución corresponde a una propuesta original | +| Actualización | Solo cuando existe match de alta confianza | + +### Google Drive + +| Carpeta / Recurso | Uso | +| ------------------------ | -------------------------------------------------- | +| PROPUESTAS EJECUTADAS | Carpeta principal para evidencias y presentaciones | +| Carpeta por ejecución | Guarda audios, imágenes, videos y presentación | +| Template de presentación | Plantilla base para generar presentación final | + +--- + +## REGLAS DE NEGOCIO + +### Acceso y permisos + +* El flujo está diseñado para operar desde un grupo oficial de WhatsApp. +* El permiso de uso se controla por pertenencia al grupo autorizado. +* Los mensajes que no provienen del grupo permitido deben bloquearse o ignorarse. +* En grupos, el bot debe identificar al usuario real mediante el participante del mensaje, no solo el ID del grupo. +* La respuesta debe enviarse al grupo cuando el reporte inicia desde el grupo. + +### Comandos oficiales + +| Comando | Uso | +| -------------- | ------------------------------------------- | +| `Hey` | Iniciar reporte | +| `FOTOS LISTAS` | Confirmar que terminó el envío de imágenes | +| `SIN VIDEO` | Cerrar reporte sin videos | +| `LISTO` | Cerrar reporte cuando sí se enviaron videos | +| `CANCELAR` | Cancelar reporte activo | + +### Reglas del reporte + +* Una propuesta por reporte. +* Una sesión activa por usuario dentro del grupo. +* Nota de voz obligatoria. +* Imágenes obligatorias. +* Videos opcionales. +* Las imágenes pueden enviarse juntas o separadas. +* Los videos deben enviarse uno por uno, en mensajes separados. +* No se deben mezclar evidencias de varias propuestas en un mismo reporte. +* El usuario no debe iniciar otro reporte hasta terminar o cancelar el actual. + +### Reglas de sesión + +* Al escribir `Hey`, si no existe sesión activa, se crea una nueva sesión. +* Si ya existe sesión activa, se informa al usuario que debe completar o cancelar la sesión actual. +* Si el usuario escribe `CANCELAR`, la sesión activa se cancela. +* Si el usuario escribe comandos fuera de etapa, el flujo responde con la instrucción correspondiente. +* Cuando el flujo pasa a procesamiento, no debe aceptar nuevos archivos para esa sesión. + +### Reglas multimedia + +* El audio se analiza como fuente principal de contexto. +* Las imágenes se analizan como evidencias visuales. +* Los videos se analizan solo si el usuario los envía. +* Si el usuario no tiene videos, debe escribir `SIN VIDEO`. +* Si envió videos, debe escribir `LISTO`. +* Cada archivo multimedia queda registrado con su tipo, nombre, mime type, link, Drive ID y sesión. + +### Reglas de IA + +Gemini debe analizar: + +* Nota de voz. +* Imágenes. +* Videos opcionales. +* Contexto consolidado. + +La salida final debe estructurar: + +* Tipo de reporte. +* Marca. +* Cliente. +* País. +* Ubicación. +* Propuesta de referencia. +* Descripción de ejecución. +* Resumen IA. +* Elementos detectados. +* Tags. +* Match contra banco. +* Estado de revisión. + +### Reglas para propuesta ejecutada + +Una propuesta ejecutada es una implementación real relacionada con una propuesta o referencia del banco interno. + +Si el match contra el banco original es alto: + +* Se guarda la ejecución. +* Se genera presentación. +* Se actualiza el banco original con el link de la presentación ejecutada. +* Se evita duplicar el link si ya existía. + +### Reglas para propuesta externa + +Una propuesta externa es un reporte recibido fuera del banco interno o sin match confiable con una propuesta original. + +En este caso: + +* Se guarda en `propuestas_ejecutadas`. +* Se genera presentación. +* Se conserva la evidencia. +* No se actualiza el banco original automáticamente. +* Puede quedar marcada para revisión manual si aplica. + +### Reglas de match + +* Match alto: permite actualizar el banco original. +* Match bajo/manual: registra la ejecución, pero no actualiza el banco original. +* Sin match: registra como externa o revisión, sin modificar el banco original. +* No se debe afirmar relación definitiva si el match no es confiable. + +### Reglas de duplicado + +* Antes de guardar el reporte final, el flujo verifica si la propuesta ejecutada ya existe. +* Si ya existe, debe evitar guardar duplicados innecesarios. +* Si el banco original ya tiene link de ejecución, no debe duplicarlo. +* Los links nuevos deben agregarse solo cuando corresponde. + +### Reglas de presentación + +* La presentación se genera copiando una plantilla base. +* El flujo reemplaza textos con información del reporte. +* Inserta imágenes en los placeholders disponibles. +* Si hay menos imágenes que placeholders, se eliminan o limpian los slides vacíos configurados. +* La presentación final debe incluir link accesible para el equipo autorizado. + +### Reglas de seguridad + +* No commitear API keys, tokens, webhooks ni credenciales en el README. +* No publicar capturas que expongan API keys. +* Las credenciales deben vivir en n8n Credentials o vault interno GLM. +* El repo de Gitea debe servir como backup del workflow y documentación, no como almacén de secretos. + +--- + +## CONFIGURACIÓN Y SETUP + +### Prerrequisitos + +* Acceso a n8n en el entorno GLM. +* Acceso a Evolution API. +* Instancia WhatsApp configurada. +* Grupo oficial de WhatsApp creado. +* Webhook de Evolution apuntando al workflow. +* Acceso a Google Sheets. +* Acceso a Google Drive. +* Acceso a Google Slides API. +* Credencial Gemini configurada. +* Credencial Redis configurada. +* Acceso al Banco de Propuestas de Fulgencio. +* Acceso al repositorio Gitea `chat-de-whatsapp-propuestas-ejecutadas`. + +### Credenciales / variables + +| Credencial / Variable | Descripción | Dónde se obtiene | +| ------------------------------ | --------------------------------------------------------- | --------------------- | +| N8N_WEBHOOK_PATH | Path del webhook de entrada | n8n | +| GOOGLE_SHEETS_OAUTH | Permite leer y escribir registros | n8n Credentials | +| GOOGLE_DRIVE_OAUTH | Permite crear carpetas, mover archivos y copiar plantilla | n8n Credentials | +| GOOGLE_SLIDES_OAUTH | Permite modificar presentación generada | n8n Credentials | +| GEMINI_API | Permite analizar multimedia y generar JSON final | n8n Credentials | +| REDIS_CREDENTIAL | Permite conteo y locks de análisis | n8n Credentials | +| SHEET_PROPUESTAS_EJECUTADAS_ID | ID del Sheet Fulgencio - Propuestas Ejecutadas | Google Sheets | +| BANCO_PROPUESTAS_SHEET_ID | ID del banco original de propuestas | Google Sheets | +| DRIVE_FOLDER_EJECUTADAS_ID | Carpeta base de propuestas ejecutadas | Google Drive | +| SLIDES_TEMPLATE_ID | Plantilla de presentación | Google Slides | + +> Nunca commitear credenciales al repo. Todas las keys, tokens, URLs sensibles y webhooks deben mantenerse en n8n Credentials, variables seguras o vault interno GLM. + + +### Instalación / Deploy + +```bash id="fkmkf4" +git clone https://git.digitalcompass.agency/Isaac_Aracena/chat-de-whatsapp-propuestas-ejecutadas.git + +# En n8n: +# 1. Abrir n8n. +# 2. Importar el JSON del workflow. +# 3. Validar credenciales de Google Sheets. +# 4. Validar credenciales de Google Drive. +# 5. Validar credenciales de Google Slides. +# 6. Validar credencial de Gemini. +# 7. Validar credencial Redis. +# 8. Validar Evolution API URL e instancia. +# 9. Validar webhook de entrada. +# 10. Validar grupo permitido. +# 11. Ejecutar prueba end-to-end desde WhatsApp. +# 12. Revisar n8n Executions. +# 13. Activar el workflow. +``` + +--- + +## CÓMO FUNCIONA + +### Flujo paso a paso + +1. **Webhook - Evolution WhatsApp** + + * Recibe mensajes desde WhatsApp. + +2. **Code - Normalizar evento WhatsApp** + + * Normaliza el evento. + * Detecta si viene de grupo. + * Identifica usuario real. + * Detecta texto, comandos, audio, imagen, video o documento. + * Define `whatsapp_to`, `sender_phone`, `group_jid` e idioma base. + +3. **Filtro origen WhatsApp** + + * Valida que el mensaje venga del origen permitido. + * Bloquea o ignora mensajes no autorizados. + +4. **Sheets - Leer sesiones existentes** + + * Lee sesiones activas en `wa_ejecuciones_sesiones`. + +5. **Code - Resolver sesión WhatsApp** + + * Decide si debe crear sesión, continuar, cancelar o avisar sesión activa. + +6. **Switch - Decisión sesión WhatsApp** + + * Enruta según la decisión: + + * Crear sesión. + * Avisar sesión activa. + * Cancelar sesión. + * Continuar sesión. + * Sin sesión activa. + +7. **Crear sesión** + + * Guarda una nueva sesión en Sheets. + * Envía bienvenida y pide nota de voz. + +8. **Continuar sesión** + + * Lee etapa activa. + * Resuelve qué debe hacer según mensaje recibido. + +9. **Paso 1 — Audio** + + * Si recibe audio, lo guarda como evento. + * Actualiza sesión a espera de imágenes. + * Pide imágenes al usuario. + +10. **Paso 2 — Imágenes** + +* Guarda una o varias imágenes. +* Soporta lote de imágenes. +* Cuando el usuario escribe `FOTOS LISTAS`, valida que existan imágenes. +* Pasa a videos opcionales. + +11. **Paso 3 — Videos** + +* Recibe videos opcionales uno por uno. +* Si no hay videos, usuario escribe `SIN VIDEO`. +* Si sí hubo videos, usuario escribe `LISTO`. +* Pasa a procesamiento. + +12. **Aviso procesando** + +* Envía mensaje de “Reporte recibido” y notifica que se analizarán evidencias. + +13. **Recuperación de media** + +* Busca eventos multimedia de la sesión. +* Recupera archivos desde Evolution. +* Convierte media a binario. +* Sube evidencias a Google Drive. +* Guarda metadata en Sheets. + +14. **Análisis Gemini por media** + +* Analiza audio. +* Analiza imágenes. +* Analiza videos si existen. +* Guarda cada análisis en `wa_ejecuciones_analisis_media`. + +15. **Control Redis** + +* Cuenta cuántos análisis terminaron. +* Usa lock para evitar que el cierre final corra varias veces. +* Si falta análisis, espera y reintenta verificación. + +16. **Consolidar análisis** + +* Lee análisis guardados. +* Consolida audio, imágenes y videos. +* Construye prompt final. + +17. **Gemini - JSON final** + +* Genera un JSON estructurado del reporte. + +18. **Normalizar JSON final** + +* Limpia y estandariza campos. +* Clasifica el reporte. +* Prepara datos para match y guardado. + +19. **Match contra Banco de Propuestas** + +* Lee banco original. +* Busca coincidencias. +* Determina estado y confianza del match. + +20. **Verificar duplicado** + +* Revisa si la ejecución ya existe. +* Evita duplicar registros finales. + +21. **Guardar propuesta ejecutada** + +* Guarda el reporte final en `propuestas_ejecutadas`. + +22. **Crear carpeta y presentación** + +* Crea/copia presentación desde plantilla. +* Mueve evidencias a carpeta de ejecución. +* Reemplaza textos en Google Slides. +* Inserta imágenes. +* Limpia slides de fotos vacías cuando aplica. + +23. **Actualizar links** + +* Actualiza link de presentación en el Sheet. +* Si match es alto, actualiza el banco original con el link de propuesta ejecutada. + +24. **Cerrar sesión** + +* Actualiza sesión como completada. +* Envía mensaje final por WhatsApp con link de presentación. + +--- + +## TRIGGERS + +| Trigger | Frecuencia | Descripción | +| ----------------------- | ------------ | ----------------------------------------------------------- | +| Webhook POST `/factura` | On demand | Se dispara cuando Evolution API envía un evento de WhatsApp | +| Ejecución manual | Bajo demanda | Permite pruebas desde n8n con eventos fijados | + +--- + +## COMANDOS OFICIALES + +| Comando | Descripción | +| -------------- | -------------------------------------------------- | +| `Hey` | Inicia un nuevo reporte | +| `FOTOS LISTAS` | Confirma que el usuario terminó de enviar imágenes | +| `SIN VIDEO` | Cierra el reporte sin videos | +| `LISTO` | Cierra el reporte después de enviar videos | +| `CANCELAR` | Cancela el reporte actual | + +--- + +## OUTPUTS + +### Respuesta por WhatsApp + +El usuario recibe mensajes como: + +* Bienvenida y solicitud de nota de voz. +* Solicitud de imágenes. +* Solicitud de videos opcionales. +* Aviso de procesamiento. +* Link final de presentación. +* Mensajes de error controlado o instrucciones. + +### Registro en Google Sheets + +El flujo registra información en: + +| Hoja | Uso | +| ------------------------------- | ------------------------------------- | +| `wa_ejecuciones_sesiones` | Estado de sesiones | +| `wa_ejecuciones_eventos` | Eventos recibidos | +| `wa_ejecuciones_media` | Metadata de media | +| `wa_ejecuciones_analisis_media` | Análisis de Gemini por archivo | +| `propuestas_ejecutadas` | Registro final de ejecución o externa | + +### Presentación final + +El flujo genera una presentación con: + +* Título del reporte. +* Resumen IA. +* Datos de cliente, marca, país y ubicación. +* Relación con propuesta original si existe. +* Imágenes de evidencia. +* Link final compartido por WhatsApp. + +### Banco original + +Si hay match alto: + +* Se actualiza la columna de enlaces a propuestas ejecutadas. +* Se evita duplicar links existentes. + +Si no hay match alto: + +* No se modifica el banco original. + +--- + +## TESTING + +### Casos de prueba mínimos + +| Caso | Input | Output esperado | Estado | +| ---------------------------------- | -------------------------------------------- | ------------------------------------------- | ----------- | +| Inicio correcto | Usuario en grupo escribe `Hey` | Crea sesión y pide nota de voz | A completar | +| Sesión duplicada | Usuario escribe `Hey` con sesión activa | Avisa que ya existe sesión activa | A completar | +| Audio válido | Usuario envía nota de voz | Guarda audio y pide imágenes | A completar | +| Texto en vez de audio | Usuario envía texto en etapa audio | Pide nota de voz obligatoria | A completar | +| Una imagen | Usuario envía una imagen | Guarda imagen y permite seguir | A completar | +| Varias imágenes juntas | Usuario envía lote de imágenes | Guarda todas y confirma recepción | A completar | +| FOTOS LISTAS sin imágenes | Usuario escribe comando sin imágenes | Pide imágenes obligatorias | A completar | +| SIN VIDEO | Usuario cierra sin videos | Procesa reporte completo | A completar | +| Un video | Usuario envía video y luego `LISTO` | Procesa reporte con video | A completar | +| Varios videos uno por uno | Usuario envía varios videos separados | Guarda todos y procesa al cerrar | A completar | +| CANCELAR | Usuario cancela sesión | Sesión queda cancelada | A completar | +| Grupo no permitido | Mensaje desde grupo no autorizado | No procesa el flujo | A completar | +| Propuesta ejecutada con match alto | Reporte coincide con banco | Guarda ejecución y actualiza banco original | A completar | +| Match bajo/manual | Reporte no coincide con confianza suficiente | Guarda ejecución y no actualiza banco | A completar | +| Propuesta externa | Reporte indica externa | Guarda como externa y no actualiza banco | A completar | +| Duplicado de link | Banco ya tiene link ejecutado | No duplica link | A completar | +| Menos imágenes que placeholders | Reporte con pocas imágenes | Presentación sin slides vacíos visibles | A completar | + +### Checklist de prueba rápida + +* [ ] El webhook recibe eventos de WhatsApp. +* [ ] El filtro de grupo permitido funciona. +* [ ] `Hey` crea sesión. +* [ ] La nota de voz es obligatoria. +* [ ] Las imágenes son obligatorias. +* [ ] Las imágenes múltiples funcionan. +* [ ] Los videos opcionales funcionan uno por uno. +* [ ] `SIN VIDEO` cierra correctamente. +* [ ] `LISTO` cierra correctamente con videos. +* [ ] El aviso de procesamiento se envía. +* [ ] Gemini analiza audio, imagen y video. +* [ ] Redis evita cierres duplicados. +* [ ] Se guarda registro final. +* [ ] Se crea presentación. +* [ ] Se limpia presentación si hay placeholders vacíos. +* [ ] Se envía link final. +* [ ] El banco original solo se actualiza con match alto. +* [ ] n8n Executions queda en verde. +* [ ] Workflow exportado y commiteado en Gitea. + +--- + +## ERRORES CONOCIDOS Y TROUBLESHOOTING + +| Error | Causa probable | Solución | +| ----------------------------------- | ----------------------------------------------------- | ---------------------------------------------------------- | +| Bot no responde | Webhook no recibe evento o workflow desactivado | Revisar Evolution webhook y n8n Executions | +| Mensaje va al usuario y no al grupo | `whatsapp_to` mal resuelto | Revisar `group_jid`, `remoteJid` y normalización de evento | +| Usuario equivocado en grupo | Se usó `participant` en vez de `participantAlt` | Validar sender real en evento Evolution | +| Sesión no aparece | Error leyendo o escribiendo `wa_ejecuciones_sesiones` | Revisar credencial Google Sheets | +| Pide audio aunque ya se envió | Audio no se registró como `message_type = audio` | Revisar normalización de media | +| Imágenes no se guardan | Evolution envió álbum/lote con estructura distinta | Revisar separación de media en items | +| Videos fallan en Gemini | Binario no llega como `data` o mime type incorrecto | Revisar preparación Gemini video | +| Prompt final vacío | No se consolidaron análisis media | Revisar `wa_ejecuciones_analisis_media` y sesión filtrada | +| Procesamiento se queda esperando | Falta análisis o Redis no detecta conteo completo | Revisar contador Redis y rows de análisis | +| Doble cierre | Lock Redis no se adquirió correctamente | Revisar `Redis - Lock análisis final` | +| No crea presentación | Error en Drive o plantilla | Revisar credencial Drive y template | +| Slides vacíos | No se eliminaron placeholders no usados | Revisar payload de limpieza de Slides | +| No actualiza banco | Match bajo o condición de alta confianza no cumplida | Revisar estado de match | +| Duplica link | Validación de link existente falló | Revisar lógica de actualización de banco | +| Error 401/403 Google | Credencial sin permiso | Renovar o compartir recurso con cuenta OAuth | +| Error Evolution 401 | API key inválida | Rotar key en n8n Credentials / variables seguras | + +--- + +## MONITOREO + +* Revisar n8n Executions después de pruebas o cambios. +* Verde = ejecución correcta. +* Rojo = revisar el nodo exacto del fallo. +* Revisar que el grupo oficial siga autorizado. +* Revisar que Evolution API esté activo. +* Revisar que Google Sheets no cambie encabezados. +* Revisar que Drive y Slides mantengan permisos. +* Revisar que Redis esté disponible. +* Revisar periódicamente propuestas con revisión manual. +* Confirmar que las presentaciones generadas abran correctamente. +* Mantener backup del workflow actualizado en Gitea. + +### Output esperado normal + +El flujo debe: + +* Recibir evento de WhatsApp. +* Crear o continuar sesión. +* Solicitar audio, imágenes y videos. +* Procesar evidencias. +* Analizar con IA. +* Generar registro final. +* Crear presentación. +* Actualizar links cuando corresponda. +* Responder por WhatsApp. +* Terminar sin errores. + +--- + +## ESTRUCTURA DEL REPOSITORIO + +```txt id="y2xjdy" +/chat-de-whatsapp-propuestas-ejecutadas +|-- README.md +|-- chat-de-whatsapp-propuestas-ejecutadas.json +|-- /docs +| └-- [capturas o documentación adicional si aplica] +|-- CHANGELOG.md +└-- DECISIONS.md +``` + +> Si el repo solo contiene `README.md` y el JSON del workflow, mantener esta estructura simple. Si el proyecto crece, agregar `/docs`, `CHANGELOG.md` y `DECISIONS.md`. + +--- + +## CHANGELOG + +### 2026-06 — v2.0 / Versión Final + +* Flujo final de WhatsApp para propuestas ejecutadas y externas. +* Soporte de grupo oficial de WhatsApp. +* Identificación correcta de usuario real en grupo. +* Control de sesiones por usuario/grupo. +* Nota de voz obligatoria. +* Imágenes obligatorias. +* Soporte de múltiples imágenes. +* Videos opcionales uno por uno. +* Análisis de audio, imagen y video con Gemini. +* Control Redis para conteo de análisis y cierre final. +* Generación automática de presentación. +* Limpieza de slides vacíos. +* Registro final en `propuestas_ejecutadas`. +* Match contra banco original. +* Actualización del banco con link ejecutado solo en match alto. +* Prevención de duplicados. +* Respuesta final por WhatsApp. +* Backup del workflow en Gitea. +* Documentación inicial del README. + +--- + +## DECISIONS LOG + +### DEC-001 — Usar WhatsApp como canal operativo + +* **Fecha:** 2026-06 +* **Contexto:** Los equipos operativos reportan evidencias desde campo. +* **Opciones consideradas:** App web, Google Chat, WhatsApp. +* **Decisión:** Usar WhatsApp. +* **Razón:** Es el canal más natural para enviar audios, fotos y videos desde campo. + +### DEC-002 — Controlar acceso por grupo oficial + +* **Fecha:** 2026-06 +* **Contexto:** El flujo debía ser fácil de operar sin una tabla manual de usuarios. +* **Opciones consideradas:** Lista de teléfonos vs pertenencia al grupo. +* **Decisión:** Permitir uso desde grupo oficial autorizado. +* **Razón:** Simplifica operación: agregar usuario al grupo equivale a darle acceso. + +### DEC-003 — Nota de voz obligatoria + +* **Fecha:** 2026-06 +* **Contexto:** Las imágenes por sí solas no explican completamente la ejecución. +* **Decisión:** Requerir nota de voz. +* **Razón:** Aporta contexto de marca, país, ubicación, referencia y tipo de reporte. + +### DEC-004 — Imágenes obligatorias y videos opcionales + +* **Fecha:** 2026-06 +* **Contexto:** Toda ejecución necesita evidencia visual, pero no siempre hay video. +* **Decisión:** Imágenes obligatorias; videos opcionales. +* **Razón:** Mantiene evidencia mínima sin frenar reportes cuando no hay video. + +### DEC-005 — Permitir varias imágenes, pero videos uno por uno + +* **Fecha:** 2026-06 +* **Contexto:** WhatsApp permite enviar varias imágenes juntas; los videos pueden ser más pesados y menos consistentes. +* **Decisión:** Soportar múltiples imágenes y pedir videos separados. +* **Razón:** Mejora experiencia sin arriesgar estabilidad del flujo. + +### DEC-006 — Usar Redis para control de cierre + +* **Fecha:** 2026-06 +* **Contexto:** El análisis multimedia puede terminar en paralelo y provocar cierres duplicados. +* **Decisión:** Usar contador y lock en Redis. +* **Razón:** Evita duplicar análisis final, registros o presentaciones. + +### DEC-007 — Actualizar banco original solo con match alto + +* **Fecha:** 2026-06 +* **Contexto:** No se debe vincular una ejecución a una propuesta original sin confianza suficiente. +* **Decisión:** Actualizar banco solo cuando el match sea confiable. +* **Razón:** Protege la calidad del banco y evita relaciones incorrectas. + +### DEC-008 — Registrar propuestas externas sin actualizar banco original + +* **Fecha:** 2026-06 +* **Contexto:** Algunas evidencias pueden pertenecer a propuestas externas o no existentes en el banco. +* **Decisión:** Guardarlas en `propuestas_ejecutadas` sin modificar el banco. +* **Razón:** Mantiene trazabilidad sin contaminar la fuente original. + +### DEC-009 — Generar presentación automática + +* **Fecha:** 2026-06 +* **Contexto:** El equipo necesita un entregable ordenado, no solo archivos sueltos. +* **Decisión:** Crear presentación desde template. +* **Razón:** Estandariza el reporte y facilita consulta posterior. + +### DEC-010 — No guardar credenciales en Gitea + +* **Fecha:** 2026-06 +* **Contexto:** El workflow usa APIs y webhooks sensibles. +* **Decisión:** Mantener credenciales fuera del repositorio. +* **Razón:** Evita exposición de secretos y mantiene buenas prácticas de seguridad. + +--- + +## CONTACTOS DEL PROYECTO + +| Rol | Nombre | +| ------------- | ------------- | +| Product Owner | Máximo Gómez | +| IT Manager | Luis Matos | +| Developer | Isaac Aracena | + +--- + +## DEFINITION OF DONE + +* [ ] Workflow activo en n8n. +* [ ] Webhook de Evolution validado. +* [ ] Grupo oficial autorizado validado. +* [ ] Inicio con `Hey` validado. +* [ ] Nota de voz obligatoria validada. +* [ ] Imágenes obligatorias validadas. +* [ ] Múltiples imágenes validadas. +* [ ] Videos opcionales validados. +* [ ] `SIN VIDEO` validado. +* [ ] `LISTO` validado. +* [ ] `CANCELAR` validado. +* [ ] Gemini analiza audio correctamente. +* [ ] Gemini analiza imágenes correctamente. +* [ ] Gemini analiza videos correctamente si existen. +* [ ] Redis controla conteo y lock de cierre. +* [ ] Registro final en Sheets validado. +* [ ] Presentación generada correctamente. +* [ ] Slides vacíos limpiados o eliminados. +* [ ] Banco original actualiza solo con match alto. +* [ ] Propuesta externa no actualiza banco original. +* [ ] Duplicado de link prevenido. +* [ ] Mensaje final por WhatsApp validado. +* [ ] n8n Executions sin errores. +* [ ] Workflow exportado y subido a Gitea. +* [ ] README completo y actualizado. +* [ ] Link del repo agregado al Kan.bn de CDC Fulgencio V2.0. +* [ ] Validado por IT. +* [ ] Validado por responsable del proceso si aplica. + +--- + +## NOTAS OPERATIVAS + +* Este repositorio contiene el backup/documentación del workflow n8n. +* No debe contener credenciales, API keys, tokens ni webhooks sensibles. +* Si cambia el grupo oficial, actualizar el filtro de origen. +* Si cambia Evolution API, revisar URL, instancia y credenciales. +* Si cambian los encabezados del Sheet, actualizar nodos de mapeo. +* Si cambia la plantilla de Slides, validar placeholders y limpieza de slides. +* Si cambia el banco original, revisar lógica de match y actualización. +* Si se agregan más países, idiomas o reglas, actualizar normalización. +* Si se cambia la lógica de Gemini, documentar en CHANGELOG. +* Si se rota la API key de Evolution, actualizar únicamente n8n/vault. + +--- \ No newline at end of file