Isaac_Aracena/CDC-Fulgencio-V2.0
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Actualizar README.md

Browse Source
This commit is contained in:
Isaac_Aracena
2026-08-07 14:31:18 +00:00
parent 096ce95608
commit 0e8f73ae8e
1 changed files with 0 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+881
View File
@@ -0,0 +1,881 @@
# 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**.