diff --git a/README_CDC-Fulgencio-V2.0.md b/README_CDC-Fulgencio-V2.0.md new file mode 100644 index 0000000..450b053 --- /dev/null +++ b/README_CDC-Fulgencio-V2.0.md @@ -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 /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**.