Isaac_Aracena/chat-de-whatsapp-propuestas-ejecutadas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8280eafcbb948023c78d2778f68f2d1b293af925
chat-de-whatsapp-propuestas…/README.md
T
Isaac_Aracena 8280eafcbb Actualizar README.md
2026-06-25 03:08:50 +00:00

856 lines
36 KiB
Markdown
Raw Blame History

# Chat de WhatsApp - Propuestas Ejecutadas
> 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.
---
Reference in New Issue View Git Blame Copy Permalink