882 lines
29 KiB
Markdown
882 lines
29 KiB
Markdown
# CDC-Fulgencio-V2.0
|
|
|
|
> Ecosistema interno de GomezLee Marketing (GLM) para consultar propuestas, briefs y ejecuciones, y para registrar evidencias de propuestas ejecutadas o externas desde Google Chat y WhatsApp mediante automatizaciones en n8n.
|
|
|
|
---
|
|
|
|
## INFORMACIÓN GENERAL
|
|
|
|
| Campo | Detalle |
|
|
|---|---|
|
|
| Proyecto | CDC-Fulgencio-V2.0 / Fulgencio Fumado |
|
|
| Área | Creatividad y Diseño / IT |
|
|
| Estado | Operativo con mejoras activas |
|
|
| Developer Principal | Isaac Aracena |
|
|
| IT Manager | Luis Matos |
|
|
| Fecha de Inicio | No documentada en este repositorio |
|
|
| Fecha de Cierre Estimada | Evolución continua |
|
|
| Ciclo Shape Up | Por documentar |
|
|
| Board de Ejecución | Pendiente de enlazar |
|
|
| PRD del Proyecto | Pendiente de enlazar |
|
|
|
|
---
|
|
|
|
## OBJETIVO
|
|
|
|
### Problema que resuelve
|
|
|
|
Antes de Fulgencio, la consulta de propuestas, briefs y referencias creativas, así como el registro de evidencias de ejecuciones, dependía en gran medida de búsquedas manuales, conocimiento individual del equipo, carpetas de Drive, presentaciones y seguimiento por mensajería.
|
|
|
|
Esto hacía más lento:
|
|
|
|
- Encontrar propuestas anteriores por cliente, marca, país, año, canal o tipo de acción.
|
|
- Consultar briefs de CDC.
|
|
- Localizar propuestas ejecutadas y sus evidencias.
|
|
- Documentar nuevas ejecuciones recibidas desde los Country Managers.
|
|
- Centralizar fotos, videos, notas de voz, links y presentaciones.
|
|
- Mantener actualizado el banco de propuestas.
|
|
|
|
### Solución implementada
|
|
|
|
Fulgencio Fumado centraliza varios procesos de creatividad y propuestas mediante flujos de n8n:
|
|
|
|
1. **Chat interno en Google Chat** para consultar propuestas, briefs y propuestas ejecutadas.
|
|
2. **Registro por WhatsApp** de propuestas ejecutadas y propuestas externas mediante nota de voz, fotos y videos.
|
|
3. **Análisis con Gemini** para interpretar la información recibida y estructurar metadata.
|
|
4. **Google Drive / Sheets / Slides** como repositorio documental, base operativa y salida visual.
|
|
5. **Procesamiento automático de propuestas en bruto** para alimentar el banco de propuestas.
|
|
6. **Flujos auxiliares de alertas y seguimiento** asociados a las hojas operativas.
|
|
|
|
### Usuarios / Beneficiarios
|
|
|
|
- Country Managers de GLM.
|
|
- Equipo de Creatividad / CDC.
|
|
- Usuarios internos que necesitan consultar propuestas o briefs.
|
|
- Equipo de IT responsable de soporte, evolución y monitoreo.
|
|
- Líderes que necesitan acceder rápidamente a referencias, presentaciones y evidencias.
|
|
|
|
---
|
|
|
|
## ARQUITECTURA
|
|
|
|
### Diagrama general
|
|
|
|
```text
|
|
┌─────────────────────────────┐
|
|
│ FULGENCIO FUMADO │
|
|
└──────────────┬──────────────┘
|
|
│
|
|
┌──────────────────────┴──────────────────────┐
|
|
│ │
|
|
▼ ▼
|
|
┌─────────────────┐ ┌─────────────────┐
|
|
│ GOOGLE CHAT │ │ WHATSAPP │
|
|
└────────┬────────┘ └────────┬────────┘
|
|
│ │
|
|
▼ ▼
|
|
Webhook Google Chat Evolution API / Webhook
|
|
│ │
|
|
▼ ▼
|
|
n8n - Chat n8n - Registro
|
|
│ │
|
|
┌─────────┼──────────┐ ┌─────────────┼─────────────┐
|
|
▼ ▼ ▼ ▼ ▼ ▼
|
|
Banco de CDC Briefs Propuestas Nota de voz Fotos Videos
|
|
propuestas ejecutadas │ │ │
|
|
│ │ │ └──────┬──────┴──────┬──────┘
|
|
└─────────┴──────────┘ ▼ ▼
|
|
│ Gemini Drive / Redis
|
|
▼ │
|
|
Gemini ▼
|
|
│ Consolidación final
|
|
▼ │
|
|
Respuesta Google Chat ▼
|
|
Match banco propuestas
|
|
│
|
|
▼
|
|
Google Sheets / Google Drive
|
|
│
|
|
▼
|
|
Google Slides
|
|
│
|
|
▼
|
|
Respuesta final WhatsApp
|
|
```
|
|
|
|
### Procesamiento de propuestas en bruto
|
|
|
|
```text
|
|
Google Drive
|
|
│
|
|
├─ fileCreated
|
|
└─ fileUpdated
|
|
│
|
|
▼
|
|
n8n - Procesar propuesta
|
|
│
|
|
▼
|
|
Gemini - Extraer metadata
|
|
│
|
|
▼
|
|
Google Sheets - Banco de propuestas
|
|
│
|
|
▼
|
|
Mover archivo a carpeta de procesadas
|
|
```
|
|
|
|
---
|
|
|
|
## STACK TECNOLÓGICO
|
|
|
|
| Componente | Tecnología | Propósito |
|
|
|---|---|---|
|
|
| Automatización | n8n | Orquestación de todos los flujos |
|
|
| IA | Google Gemini | Clasificación, extracción, análisis y respuesta |
|
|
| Chat interno | Google Chat API | Interfaz de consulta para Fulgencio |
|
|
| Mensajería | WhatsApp + Evolution API | Registro de evidencias desde Country Managers |
|
|
| Datos operativos | Google Sheets | Sesiones, eventos, propuestas, briefs y resultados |
|
|
| Archivos | Google Drive | Almacenamiento de propuestas, fotos, videos y audios |
|
|
| Presentaciones | Google Slides API | Generación automática de reportes de ejecución |
|
|
| Coordinación de proceso | Redis | Locks/estado temporal en etapas de procesamiento donde aplica |
|
|
| Control de versiones | Gitea | Versionado de exports de workflows |
|
|
| Infraestructura | n8n en infraestructura GLM / Digital Compass | Ejecución de automatizaciones |
|
|
|
|
---
|
|
|
|
## INTEGRACIONES EXTERNAS
|
|
|
|
| Sistema | Tipo de integración | Datos que fluyen |
|
|
|---|---|---|
|
|
| Google Chat | Webhook + API | Preguntas de usuarios y respuestas de Fulgencio |
|
|
| Google Sheets | OAuth | Banco de propuestas, CDC Briefs, ejecuciones, sesiones y eventos |
|
|
| Google Drive | OAuth | Archivos de propuestas y evidencias |
|
|
| Google Slides | API | Copia de template, reemplazo de placeholders e inserción de imágenes |
|
|
| Google Gemini | API / credencial n8n | Análisis de texto, audio, imágenes y contexto |
|
|
| Evolution API | REST / Webhook | Entrada y salida de WhatsApp |
|
|
| Redis | Credencial n8n | Coordinación temporal, locks y validaciones de procesamiento |
|
|
| Gitea | Git | Versionado y respaldo de workflows |
|
|
|
|
---
|
|
|
|
## COMPONENTES DEL REPOSITORIO
|
|
|
|
Actualmente el repositorio contiene exports JSON de los principales workflows de n8n:
|
|
|
|
```text
|
|
CDC-Fulgencio-V2.0/
|
|
├── Flujo de n8n: Chat de Fulgencio.json
|
|
├── Flujo de n8n: Chat de WhatsApp - Propuestas Ejecutadas - Evolution API.json
|
|
├── Flujo de n8n: Chat de WhatsApp de Propuestas Ejecutadas - API Oficial.json
|
|
├── Flujo de n8n: Fulgencio Alertas Sheets - GLM.json
|
|
└── Flujo de n8n: Fulgencio Procesar Propuestas en Bruto - GLM.json
|
|
```
|
|
|
|
> **Importante:** existen variantes de integración de WhatsApp en el repositorio. Antes de modificar o activar un workflow, verificar en n8n cuál variante está actualmente en producción.
|
|
|
|
---
|
|
|
|
## FLUJOS PRINCIPALES
|
|
|
|
### 1. Chat de Fulgencio - Google Chat
|
|
|
|
Permite consultar información desde Google Chat.
|
|
|
|
Fuentes principales:
|
|
|
|
- Banco de propuestas.
|
|
- CDC Briefs.
|
|
- Propuestas ejecutadas / externas registradas.
|
|
|
|
Consultas soportadas incluyen:
|
|
|
|
- Marca.
|
|
- Cliente.
|
|
- País.
|
|
- Año.
|
|
- Canal.
|
|
- Tipo de acción.
|
|
- Estado.
|
|
- Brief ID.
|
|
- Solicitante.
|
|
- Tema.
|
|
- Propuestas ejecutadas.
|
|
- Propuestas externas.
|
|
- Links de presentaciones y evidencias.
|
|
|
|
Ejemplos:
|
|
|
|
```text
|
|
Dame las 5 últimas propuestas de Motorola.
|
|
Busca propuestas de Nestlé en República Dominicana.
|
|
Dame los últimos briefs creados.
|
|
Busca briefs relacionados con Motorola.
|
|
Tenemos alguna propuesta ejecutada?
|
|
Envíame la presentación de la ejecución de [marca/propuesta].
|
|
```
|
|
|
|
#### Comportamiento para mensajes genéricos
|
|
|
|
Saludos, cortesías o mensajes cortos sin intención de búsqueda no deben devolver propuestas aleatorias. Fulgencio responde con una bienvenida breve y ejemplos de uso.
|
|
|
|
#### Envío de respuestas
|
|
|
|
La app de Google Chat usa la Google Chat API para enviar la respuesta final.
|
|
|
|
**Regla técnica crítica:**
|
|
|
|
El campo `space_name` debe mantenerse completo:
|
|
|
|
```text
|
|
spaces/XXXXXXXXXXX
|
|
```
|
|
|
|
No remover el prefijo `spaces/` al enviar la respuesta mediante el nodo de Google Chat.
|
|
|
|
---
|
|
|
|
### 2. WhatsApp - Propuestas Ejecutadas / Externas
|
|
|
|
El flujo recibe evidencias desde WhatsApp y crea un reporte estructurado.
|
|
|
|
#### Inicio
|
|
|
|
Comando:
|
|
|
|
```text
|
|
HEY
|
|
```
|
|
|
|
#### Paso 1 - Nota de voz
|
|
|
|
El usuario envía una nota de voz indicando:
|
|
|
|
- Si se trata de propuesta ejecutada o propuesta externa.
|
|
- Propuesta / referencia.
|
|
- Marca / cliente.
|
|
- País.
|
|
- Ubicación.
|
|
- Fecha.
|
|
- Qué se implementó o reportó.
|
|
- Resultados / comentarios.
|
|
|
|
#### Paso 2 - Imágenes
|
|
|
|
El usuario envía una o varias imágenes, una por mensaje.
|
|
|
|
Comando para terminar:
|
|
|
|
```text
|
|
FOTOS LISTAS
|
|
```
|
|
|
|
#### Paso 3 - Videos
|
|
|
|
Los videos son opcionales y se envían uno por uno.
|
|
|
|
Comandos:
|
|
|
|
```text
|
|
LISTO
|
|
SIN VIDEO
|
|
```
|
|
|
|
Cancelación:
|
|
|
|
```text
|
|
CANCELAR
|
|
```
|
|
|
|
#### Procesamiento final
|
|
|
|
```text
|
|
WhatsApp
|
|
-> Recuperar media
|
|
-> Analizar audio / imágenes / videos
|
|
-> Consolidar análisis
|
|
-> Gemini final
|
|
-> Clasificar reporte
|
|
-> Match contra banco de propuestas
|
|
-> Crear carpeta de evidencias
|
|
-> Guardar archivos
|
|
-> Registrar en Google Sheets
|
|
-> Crear presentación Google Slides
|
|
-> Responder al grupo con links finales
|
|
```
|
|
|
|
---
|
|
|
|
### 3. Clasificación de reportes
|
|
|
|
Valores principales:
|
|
|
|
```text
|
|
PROPUESTA_EJECUTADA
|
|
PROPUESTA_EXTERNA
|
|
NO_DETERMINADO
|
|
```
|
|
|
|
#### PROPUESTA_EJECUTADA
|
|
|
|
Evidencia de una propuesta que ya fue implementada, instalada, realizada o activada.
|
|
|
|
#### PROPUESTA_EXTERNA
|
|
|
|
Actividad, referencia, propuesta o material recibido fuera del banco interno y que debe documentarse.
|
|
|
|
#### NO_DETERMINADO
|
|
|
|
No existe información suficiente para clasificar el reporte con seguridad.
|
|
|
|
---
|
|
|
|
### 4. Presentación automática de ejecución
|
|
|
|
La salida visual está diseñada para ser ejecutiva y presentable.
|
|
|
|
Estructura actual esperada:
|
|
|
|
```text
|
|
Slide 1 - Portada
|
|
Slide 2 - Objetivo
|
|
Slide 3 - Datos importantes
|
|
Slide 4+ - Evidencia visual
|
|
```
|
|
|
|
#### Slide 1 - Portada
|
|
|
|
Incluye información como:
|
|
|
|
- Marca.
|
|
- Propuesta de referencia.
|
|
- País.
|
|
- Ubicación.
|
|
- Fecha de ejecución.
|
|
- Manager.
|
|
|
|
#### Slide 2 - Objetivo
|
|
|
|
Placeholder principal:
|
|
|
|
```text
|
|
{{OBJETIVO}}
|
|
```
|
|
|
|
El flujo usa la mejor fuente disponible en este orden:
|
|
|
|
```text
|
|
objetivo
|
|
-> descripcion_ejecucion
|
|
-> resumen_ia
|
|
-> No disponible
|
|
```
|
|
|
|
#### Slide 3 - Datos importantes
|
|
|
|
Placeholders principales:
|
|
|
|
```text
|
|
{{UBICACION}}
|
|
{{FECHA_EJECUCION}}
|
|
{{MARCA}}
|
|
{{CLIENTE}}
|
|
{{PAIS}}
|
|
{{PROPUESTA_REFERENCIA}}
|
|
{{MEDIA_FOLDER_URL}}
|
|
{{FOTOS_COUNT}}
|
|
{{VIDEOS_COUNT}}
|
|
```
|
|
|
|
#### Slides de evidencia
|
|
|
|
Las fotografías enviadas por el usuario se insertan en los slides visuales correspondientes. Los slides de fotos que no se utilizan deben eliminarse automáticamente.
|
|
|
|
---
|
|
|
|
### 5. Procesar Propuestas en Bruto
|
|
|
|
Automatiza la incorporación de nuevas propuestas al banco.
|
|
|
|
#### Trigger
|
|
|
|
Google Drive:
|
|
|
|
```text
|
|
fileCreated
|
|
fileUpdated
|
|
```
|
|
|
|
Se usan ambos eventos porque una propuesta puede:
|
|
|
|
- Ser subida directamente a la carpeta.
|
|
- Ser movida desde otra carpeta existente.
|
|
|
|
#### Convención de nombre
|
|
|
|
Formato recomendado:
|
|
|
|
```text
|
|
[PAIS=NOMBRE DEL PAIS] AÑO_CLIENTE_MARCA_NOMBRE DE LA PROPUESTA
|
|
```
|
|
|
|
Ejemplo:
|
|
|
|
```text
|
|
[PAIS=REPUBLICA DOMINICANA] 2026_NESTLE_KIT KAT_ACTIVACION F1
|
|
```
|
|
|
|
Países soportados actualmente:
|
|
|
|
- El Salvador.
|
|
- Panamá.
|
|
- República Dominicana.
|
|
- Colombia.
|
|
- Puerto Rico.
|
|
- Honduras.
|
|
- México.
|
|
- Venezuela.
|
|
- Jamaica.
|
|
- Trinidad y Tobago.
|
|
- Costa Rica.
|
|
- Nicaragua.
|
|
- Guatemala.
|
|
|
|
#### Flujo
|
|
|
|
```text
|
|
Drive Trigger
|
|
-> Loop de archivos
|
|
-> Preparar archivo
|
|
-> Gemini extrae metadata
|
|
-> Normalizar respuesta
|
|
-> Agregar propuesta a Google Sheets
|
|
-> Mover archivo a procesadas
|
|
-> Continuar loop
|
|
```
|
|
|
|
---
|
|
|
|
## REGLAS DE NEGOCIO
|
|
|
|
1. El acceso al flujo de WhatsApp se controla por pertenencia al grupo oficial autorizado.
|
|
2. No se depende de una tabla individual de usuarios para permitir el uso del bot.
|
|
3. Una ejecución activa pertenece al usuario/sender dentro del grupo correspondiente.
|
|
4. Solo se procesa una propuesta/reporte por sesión.
|
|
5. La nota de voz es obligatoria.
|
|
6. Debe existir al menos una imagen antes de cerrar el paso de fotos.
|
|
7. Los videos son opcionales.
|
|
8. Las imágenes se reciben una por mensaje.
|
|
9. Los videos se reciben uno por uno.
|
|
10. `FOTOS LISTAS` cierra la etapa de imágenes.
|
|
11. `SIN VIDEO` finaliza sin videos.
|
|
12. `LISTO` finaliza después de enviar videos.
|
|
13. `CANCELAR` cancela la sesión actual.
|
|
14. Una propuesta con match bajo no debe actualizar automáticamente el banco original.
|
|
15. Se debe evitar duplicar un link en el banco si ya existe.
|
|
16. Las propuestas y los briefs son fuentes distintas y no deben mezclarse.
|
|
17. Fulgencio no debe inventar propuestas, briefs, enlaces ni datos que no existan en el contexto.
|
|
18. Un saludo o mensaje ambiguo no debe disparar resultados arbitrarios.
|
|
19. En Google Chat, el nombre del space debe enviarse con el formato completo `spaces/...`.
|
|
20. Las credenciales y secretos nunca deben almacenarse deliberadamente en el README ni exponerse en logs o documentación pública.
|
|
|
|
---
|
|
|
|
## CONFIGURACIÓN Y SETUP
|
|
|
|
### Prerrequisitos
|
|
|
|
- Acceso a la instancia de n8n correspondiente.
|
|
- Acceso al proyecto de Google Cloud de Fulgencio.
|
|
- Google Chat API habilitada.
|
|
- Credencial Google Service Account para Google Chat.
|
|
- Credenciales OAuth de Google Sheets.
|
|
- Credenciales OAuth de Google Drive.
|
|
- Acceso a Google Slides API.
|
|
- Credencial de Gemini.
|
|
- Acceso a Evolution API.
|
|
- Acceso a Redis, cuando aplique.
|
|
- Acceso a las carpetas y Sheets utilizados por los workflows.
|
|
- Acceso al repositorio Gitea.
|
|
|
|
### Importar workflows
|
|
|
|
1. Clonar o descargar el repositorio.
|
|
2. Abrir n8n.
|
|
3. Ir a **Workflows**.
|
|
4. Importar cada JSON necesario.
|
|
5. Reasignar las credenciales del ambiente.
|
|
6. Revisar IDs de Sheets, carpetas, templates y endpoints.
|
|
7. Verificar los webhooks antes de activar producción.
|
|
8. Ejecutar la batería mínima de pruebas.
|
|
9. Activar/publicar únicamente después de validar el output.
|
|
|
|
### Clonar repositorio
|
|
|
|
```bash
|
|
git clone <URL_GITEA>/Isaac_Aracena/CDC-Fulgencio-V2.0.git
|
|
cd CDC-Fulgencio-V2.0
|
|
```
|
|
|
|
---
|
|
|
|
## CONFIGURACIÓN SENSIBLE
|
|
|
|
Los valores reales deben almacenarse en **n8n Credentials**, variables seguras o el mecanismo aprobado por GLM IT.
|
|
|
|
| Configuración | Propósito | Ubicación recomendada |
|
|
|---|---|---|
|
|
| Google Chat Service Account | Enviar mensajes como Fulgencio | n8n Credentials |
|
|
| Google Sheets OAuth | Leer/escribir Sheets | n8n Credentials |
|
|
| Google Drive OAuth | Administrar archivos | n8n Credentials |
|
|
| Gemini Credential | Análisis con IA | n8n Credentials |
|
|
| Evolution API Key | Mensajes WhatsApp | n8n Credentials / Variables |
|
|
| Evolution API Base URL | Endpoint de WhatsApp | n8n Variables |
|
|
| Redis Credential | Estado/locks | n8n Credentials |
|
|
| Google Slides Template ID | Template de reportes | Variable/configuración del workflow |
|
|
| IDs de Sheets | Fuentes y tablas operativas | Variables/configuración del workflow |
|
|
| IDs de carpetas Drive | Ingesta y outputs | Variables/configuración del workflow |
|
|
|
|
> **SEGURIDAD:** no commitear API keys, private keys, tokens OAuth, contraseñas ni secretos dentro de los JSON exportados. Antes de compartir o publicar un workflow exportado, revisar especialmente nodos HTTP Request y campos configurados manualmente.
|
|
|
|
---
|
|
|
|
## GOOGLE CHAT - CONFIGURACIÓN OPERATIVA
|
|
|
|
### Endpoint de producción
|
|
|
|
La Google Chat App debe apuntar al webhook de producción del workflow activo.
|
|
|
|
Ambiente actual documentado:
|
|
|
|
```text
|
|
https://agenteit.digitalcompass.agency/webhook/googlechat
|
|
```
|
|
|
|
Antes de modificar este endpoint:
|
|
|
|
1. Guardar el endpoint anterior para rollback.
|
|
2. Confirmar que el workflow de n8n está activo.
|
|
3. Validar la credencial de Google Chat.
|
|
4. Realizar una prueba controlada.
|
|
|
|
### Autenticación de salida
|
|
|
|
La respuesta final utiliza autenticación de app mediante Google Service Account.
|
|
|
|
Scope esperado:
|
|
|
|
```text
|
|
https://www.googleapis.com/auth/chat.bot
|
|
```
|
|
|
|
### Nota crítica de Space ID
|
|
|
|
Correcto:
|
|
|
|
```text
|
|
spaces/7uYcGyAAAAE
|
|
```
|
|
|
|
Incorrecto:
|
|
|
|
```text
|
|
7uYcGyAAAAE
|
|
```
|
|
|
|
---
|
|
|
|
## WHATSAPP - CONFIGURACIÓN OPERATIVA
|
|
|
|
El flujo de WhatsApp usa Evolution API para recibir eventos y enviar mensajes.
|
|
|
|
Validar antes de producción:
|
|
|
|
- Webhook registrado.
|
|
- Instancia correcta.
|
|
- API key almacenada de forma segura.
|
|
- Grupo autorizado.
|
|
- Número/identidad del bot.
|
|
- Formato de `@g.us` para grupos.
|
|
- Formato de `@s.whatsapp.net` para usuarios cuando aplique.
|
|
|
|
---
|
|
|
|
## CÓMO FUNCIONA - FLUJO PASO A PASO
|
|
|
|
### Consulta en Google Chat
|
|
|
|
1. El usuario escribe a Fulgencio.
|
|
2. Google Chat envía el evento al webhook de n8n.
|
|
3. n8n responde inmediatamente con un mensaje de procesamiento.
|
|
4. El flujo lee las fuentes relevantes.
|
|
5. Se filtran candidatos.
|
|
6. Gemini responde usando únicamente el contexto disponible.
|
|
7. Se limpia/formatea la respuesta.
|
|
8. Google Chat API publica la respuesta final.
|
|
|
|
### Registro de ejecución en WhatsApp
|
|
|
|
1. El usuario escribe `HEY`.
|
|
2. Se valida acceso y sesión.
|
|
3. Se solicita nota de voz.
|
|
4. Se registra y analiza el audio.
|
|
5. Se solicitan fotos.
|
|
6. Las fotos se reciben y registran.
|
|
7. `FOTOS LISTAS` avanza al paso de videos.
|
|
8. El usuario envía videos o escribe `SIN VIDEO`.
|
|
9. El flujo recupera y analiza toda la media.
|
|
10. Gemini genera el análisis consolidado.
|
|
11. Se clasifica como ejecutada/externa/no determinada.
|
|
12. Se busca match en el banco.
|
|
13. Se crea carpeta de evidencia.
|
|
14. Se guardan archivos.
|
|
15. Se registra el resultado en Sheets.
|
|
16. Se genera la presentación.
|
|
17. Se envían links finales al usuario/grupo.
|
|
|
|
---
|
|
|
|
## SCHEDULES / TRIGGERS
|
|
|
|
| Trigger | Frecuencia | Descripción |
|
|
|---|---|---|
|
|
| Google Chat Webhook | On demand | Recibe mensajes enviados a Fulgencio |
|
|
| Evolution API Webhook | On demand | Recibe eventos de WhatsApp |
|
|
| Google Drive `fileCreated` | Evento | Procesa nuevas propuestas en bruto |
|
|
| Google Drive `fileUpdated` | Evento | Detecta propuestas movidas/actualizadas |
|
|
| Alertas Sheets | Según configuración del workflow | Seguimiento auxiliar sobre hojas operativas |
|
|
|
|
---
|
|
|
|
## TESTING
|
|
|
|
### Casos mínimos
|
|
|
|
| Caso | Input | Output esperado | Estado |
|
|
|---|---|---|---|
|
|
| Saludo Google Chat | `Hi`, `Hola`, saludo no listado | Bienvenida/ayuda, sin propuestas aleatorias | Validado |
|
|
| Consulta propuestas | Marca/cliente/país | Resultados relevantes con links | Validado |
|
|
| Últimas propuestas | Cantidad + recientes | Respeta cantidad y orden | Validado |
|
|
| CDC Briefs | Solicitud de briefs | Devuelve briefs, no propuestas | Validado |
|
|
| Crear brief | Solicitud de nuevo brief | Comparte formulario oficial | Validado |
|
|
| Tablero CDC | Solicitud de acceso | Comparte link del tablero | Validado |
|
|
| Propuesta ejecutada | Consulta de ejecuciones | Devuelve ejecuciones relevantes | Revalidar tras cambios recientes |
|
|
| Grupo WhatsApp autorizado | `HEY` desde grupo permitido | Inicia sesión | Validado |
|
|
| Grupo no permitido | Mensaje desde grupo no autorizado | Bloquea flujo | Validado |
|
|
| Ejecutada sin video | Audio + fotos + `SIN VIDEO` | Reporte completo | Validado |
|
|
| Ejecutada con video | Audio + fotos + videos + `LISTO` | Reporte completo | Validado |
|
|
| Propuesta externa | Audio identificado como externa | Clasificación y registro correctos | Validado |
|
|
| Match bajo | Evidencia sin match confiable | No actualiza automáticamente banco | Validado |
|
|
| Template de presentación V3 | Ejecución completa | Portada + objetivo + datos + fotos | Pendiente de regresión final |
|
|
| Media múltiple | Varias imágenes/videos | Procesamiento sin duplicados | Validado |
|
|
|
|
---
|
|
|
|
## TROUBLESHOOTING
|
|
|
|
| Error | Causa probable | Solución |
|
|
|---|---|---|
|
|
| Google Chat solo muestra "Procesando..." | El flujo falló después del Webhook | Revisar `Executions` y localizar el primer nodo rojo |
|
|
| `404 Not Found` en Google Chat | `space_name` sin prefijo | Enviar el valor completo `spaces/...` |
|
|
| `Forbidden` en Google Chat | Credencial/permisos incorrectos | Verificar Google Service Account y scope `chat.bot` |
|
|
| Propuestas aleatorias ante saludo | Mensaje ambiguo llegó a búsquedas | Aplicar regla de mensajes ambiguos en System Message/filtro |
|
|
| Asteriscos `**` visibles | Markdown no interpretado por Google Chat | Limpiar Markdown antes del nodo de salida |
|
|
| `fecha_sort is not defined` | Propiedad referenciada con nombre incorrecto | Usar `fecha_sort: fechaSort` |
|
|
| No inicia WhatsApp | No existe sesión válida o grupo no autorizado | Revisar resolución de sesión, `group_jid` y permisos |
|
|
| Imágenes no contabilizadas | Eventos/media no asociados a la sesión | Revisar `session_id`, eventos y conteos |
|
|
| Presentación con placeholders | Falta replacement en Slides | Revisar `slides_replacements` y placeholders del template |
|
|
| `{{OBJETIVO}}` visible | No se generó reemplazo | Mapear objetivo -> descripción -> resumen |
|
|
| Slides de fotos vacíos | Limpieza final no se ejecutó | Revisar nodo de borrado de slides vacíos |
|
|
| Output de IA vacío | Gemini no devolvió estructura esperada | Revisar análisis consolidado y normalización JSON |
|
|
|
|
---
|
|
|
|
## MONITOREO
|
|
|
|
### n8n Executions
|
|
|
|
Revisar especialmente:
|
|
|
|
- Ejecuciones rojas.
|
|
- Reintentos repetidos.
|
|
- Sesiones atascadas en `PROCESANDO`.
|
|
- Fallos en Gemini.
|
|
- Fallos de Drive/Sheets/Slides.
|
|
- Fallos de Evolution API.
|
|
- Errores al responder Google Chat.
|
|
|
|
### Condiciones normales
|
|
|
|
Google Chat:
|
|
|
|
```text
|
|
Mensaje usuario
|
|
-> Procesando
|
|
-> Respuesta final
|
|
```
|
|
|
|
WhatsApp:
|
|
|
|
```text
|
|
HEY
|
|
-> audio
|
|
-> fotos
|
|
-> FOTOS LISTAS
|
|
-> videos o SIN VIDEO
|
|
-> procesamiento
|
|
-> links finales
|
|
```
|
|
|
|
---
|
|
|
|
## ESTRUCTURA DEL REPOSITORIO
|
|
|
|
### Estructura actual
|
|
|
|
El repositorio está orientado principalmente a respaldar los exports de n8n.
|
|
|
|
```text
|
|
CDC-Fulgencio-V2.0/
|
|
├── README.md
|
|
├── Flujo de n8n: Chat de Fulgencio.json
|
|
├── Flujo de n8n: Chat de WhatsApp - Propuestas Ejecutadas - Evolution API.json
|
|
├── Flujo de n8n: Chat de WhatsApp de Propuestas Ejecutadas - API Oficial.json
|
|
├── Flujo de n8n: Fulgencio Alertas Sheets - GLM.json
|
|
└── Flujo de n8n: Fulgencio Procesar Propuestas en Bruto - GLM.json
|
|
```
|
|
|
|
### Estructura recomendada a futuro
|
|
|
|
Sin necesidad de migrarla inmediatamente:
|
|
|
|
```text
|
|
CDC-Fulgencio-V2.0/
|
|
├── README.md
|
|
├── CHANGELOG.md
|
|
├── DECISIONS.md
|
|
├── n8n/
|
|
│ ├── chat-fulgencio.json
|
|
│ ├── whatsapp-ejecutadas-evolution.json
|
|
│ ├── whatsapp-ejecutadas-api-oficial.json
|
|
│ ├── alertas-sheets.json
|
|
│ └── procesar-propuestas-bruto.json
|
|
└── docs/
|
|
└── architecture.png
|
|
```
|
|
|
|
---
|
|
|
|
## CHANGELOG
|
|
|
|
### 2026-08-07
|
|
|
|
- README inicial del repositorio estandarizado según GLM IT.
|
|
- Documentada la arquitectura general de Fulgencio V2.0.
|
|
- Documentados flujos de Google Chat, WhatsApp, propuestas ejecutadas/externas y procesamiento de propuestas en bruto.
|
|
- Documentadas reglas de seguridad, testing y troubleshooting.
|
|
- Integración de nueva estructura de presentación V3 en proceso de regresión final.
|
|
|
|
> Para cambios futuros, mantener esta sección sincronizada con los commits relevantes del repositorio.
|
|
|
|
---
|
|
|
|
## DECISIONS LOG
|
|
|
|
### DEC-001 - Acceso de WhatsApp controlado por grupo
|
|
|
|
- **Contexto:** Se necesitaba controlar quién podía utilizar el registro de propuestas ejecutadas.
|
|
- **Opciones consideradas:** tabla individual de usuarios vs. pertenencia al grupo oficial.
|
|
- **Decisión:** usar pertenencia al grupo oficial autorizado.
|
|
- **Razón:** simplifica administración y refleja el acceso operativo real.
|
|
|
|
### DEC-002 - Flujo único para ejecutadas y externas
|
|
|
|
- **Contexto:** El equipo necesita documentar tanto propuestas ejecutadas como referencias externas.
|
|
- **Decisión:** utilizar un único flujo y clasificar el tipo de reporte a partir de la evidencia recibida.
|
|
- **Razón:** evita mantener dos procesos casi idénticos.
|
|
|
|
### DEC-003 - Imágenes y videos uno por uno
|
|
|
|
- **Contexto:** El procesamiento de álbumes/batches de WhatsApp generaba mayor complejidad.
|
|
- **Decisión:** procesar imágenes y videos individualmente.
|
|
- **Razón:** mejora control, trazabilidad y estabilidad.
|
|
|
|
### DEC-004 - Match bajo no actualiza el banco
|
|
|
|
- **Contexto:** Un match de baja confianza podría asociar una ejecución a una propuesta incorrecta.
|
|
- **Decisión:** no actualizar automáticamente el banco original cuando la confianza no es suficiente.
|
|
- **Razón:** proteger la calidad de los datos históricos.
|
|
|
|
### DEC-005 - Google Chat responde como app
|
|
|
|
- **Contexto:** OAuth de usuario produjo problemas al responder en determinados espacios.
|
|
- **Decisión:** utilizar autenticación de app con Google Service Account.
|
|
- **Razón:** la respuesta debe pertenecer a Fulgencio y no depender de la sesión personal de un usuario.
|
|
|
|
### DEC-006 - Mantener `spaces/` en Google Chat
|
|
|
|
- **Contexto:** el nodo de Google Chat devolvía 404 al recibir únicamente el ID.
|
|
- **Decisión:** pasar `space_name` completo (`spaces/...`).
|
|
- **Razón:** es el formato esperado por la operación utilizada.
|
|
|
|
### DEC-007 - Presentación ejecutiva V3
|
|
|
|
- **Contexto:** el template anterior era percibido como demasiado técnico.
|
|
- **Decisión:** simplificar la presentación a portada, objetivo, datos importantes y evidencia visual.
|
|
- **Razón:** producir un reporte más presentable y útil para equipos comerciales/creativos.
|
|
|
|
---
|
|
|
|
## CONTACTOS DEL PROYECTO
|
|
|
|
| Rol | Nombre | Contacto |
|
|
|---|---|---|
|
|
| Product / Functional Owner | Por confirmar | Directorio corporativo GLM |
|
|
| IT Manager | Luis Matos | Directorio corporativo GLM |
|
|
| Developer Principal | Isaac Aracena | Directorio corporativo GLM |
|
|
|
|
---
|
|
|
|
## DEFINITION OF DONE
|
|
|
|
Un cambio de Fulgencio se considera listo cuando:
|
|
|
|
- [ ] Los criterios funcionales del cambio fueron verificados.
|
|
- [ ] El workflow actualizado fue probado en n8n.
|
|
- [ ] No se rompieron las rutas de Google Chat ni WhatsApp.
|
|
- [ ] Google Sheets/Drive/Slides continúan funcionando.
|
|
- [ ] Las respuestas de Gemini son consistentes con las reglas del sistema.
|
|
- [ ] No existen placeholders visibles inesperados en outputs.
|
|
- [ ] Se validaron los casos mínimos de regresión.
|
|
- [ ] No existen secretos nuevos hardcodeados en el export.
|
|
- [ ] El workflow JSON actualizado fue exportado.
|
|
- [ ] El JSON fue commiteado y pusheado a Gitea.
|
|
- [ ] El README/CHANGELOG fue actualizado cuando el cambio lo amerita.
|
|
- [ ] El cambio fue probado en ambiente real o QA equivalente.
|
|
- [ ] El output final fue validado por IT/owner correspondiente.
|
|
|
|
---
|
|
|
|
## SEGURIDAD
|
|
|
|
- No compartir private keys de Google Service Accounts.
|
|
- No commitear API keys de Evolution API.
|
|
- No commitear access tokens ni refresh tokens.
|
|
- No copiar credenciales en README, Issues o commits.
|
|
- Evitar guardar información sensible en `raw_preview` más allá de lo estrictamente necesario.
|
|
- Limitar el acceso a grupos, carpetas, Sheets y Google Cloud según el principio de menor privilegio.
|
|
- Revocar y rotar inmediatamente cualquier secreto expuesto accidentalmente.
|
|
|
|
---
|
|
|
|
## NOTAS OPERATIVAS
|
|
|
|
- Antes de modificar un endpoint de producción, guardar siempre el valor anterior para rollback.
|
|
- No realizar pruebas disruptivas en el grupo real de Country Managers cuando pueda validarse con datos históricos o QA.
|
|
- Antes de cambiar templates de Google Slides, validar que todos los placeholders tengan un replacement correspondiente en n8n.
|
|
- Mantener el banco de propuestas y el registro de propuestas ejecutadas como fuentes conceptualmente separadas.
|
|
- Cualquier cambio al filtrado de Google Chat debe probar consultas genéricas, específicas y de seguimiento.
|
|
|
|
---
|
|
|
|
Documento mantenido por el equipo **GLM IT**.
|