fulgenciochat-v3-glm/README.md

FulgencioChat V3 - GLM

Chat interno de Google Chat para consultar propuestas en bruto, CDC Briefs, propuestas ejecutadas y propuestas externas de GomezLee Marketing usando contexto filtrado, memoria conversacional y Gemini.

---

INFORMACIÓN GENERAL

Campo	Detalle
Proyecto	FulgencioChat V3 - GLM
Á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	fulgenciochat-v3-glm
Workflow n8n	FulgencioChat V3 - GLM - Versión Final
Estado del workflow	Activo
Canal principal	Google Chat

---

OBJETIVO

Problema que resuelve

GomezLee Marketing maneja múltiples fuentes de información creativa: banco de propuestas, briefs, propuestas ejecutadas y propuestas externas. Antes de FulgencioChat V3, buscar información entre estas fuentes podía ser lento, manual y dependiente de conocer exactamente dónde estaba cada archivo o registro.

El equipo podía necesitar encontrar propuestas por cliente, marca, país, año, tipo de acción o canal; consultar briefs recientes; ubicar presentaciones ejecutadas; revisar evidencias; o recuperar enlaces relacionados con propuestas externas. Hacer esto manualmente en Google Drive o Sheets consumía tiempo y podía provocar respuestas incompletas.

Solución implementada

FulgencioChat V3 funciona como un asistente interno en Google Chat. El usuario escribe una pregunta y el flujo:

• Recibe la consulta desde Google Chat.
• Responde inmediatamente que está procesando.
• Lee las fuentes oficiales de información.
• Filtra candidatos relevantes antes de enviar contexto a Gemini.
• Une las fuentes manteniéndolas separadas.
• Construye un prompt con reglas de negocio.
• Usa Gemini para responder con información real.
• Envía la respuesta final al mismo espacio de Google Chat.
• Mantiene memoria corta de conversación para preguntas de seguimiento.

Usuarios / Beneficiarios

Usuario	Beneficio
Equipo CDC	Encuentra propuestas, briefs y ejecuciones de forma rápida.
Equipo IT	Mantiene una fuente consultable sin crear una app adicional.
Usuarios internos GLM	Pueden consultar documentos y enlaces sin buscar manualmente en Drive o Sheets.

---

ARQUITECTURA

Diagrama de flujo

[Google Chat Webhook]
        ↓
[Respond to Webhook: procesando]
        ↓
[Code - Preparar mensaje]
        ├── [Sheets - Leer propuestas]
        │       ↓
        │   [Code - Filtrar propuestas relevantes]
        │
        ├── [Sheets - Leer briefs CDC]
        │       ↓
        │   [Code - Filtrar briefs CDC]
        │
        └── [Sheets - Leer propuestas ejecutadas]
                ↓
            [Code - Filtrar propuestas ejecutadas relevantes]

        ↓
[Merge - Unir propuestas y briefs Fulgencio]
        ↓
[Code - Construir contexto Fulgencio]
        ↓
[AI Agent - Gemini Fulgencio]
        ↓
[Code - Formatear respuesta Chat]
        ↓
[Chat - Enviar respuesta]

Stack tecnológico

Componente	Tecnología	Propósito
Automatización	n8n	Orquestación del flujo
Canal de entrada	Google Chat Webhook	Recibe preguntas de usuarios
Canal de salida	Google Chat API	Envía respuestas al usuario
IA	Gemini	Genera respuesta con contexto filtrado
Memoria	Simple Memory / Buffer Window	Mantiene contexto breve de la conversación
Fuente de propuestas	Google Sheets	Banco de Propuestas de Fulgencio
Fuente de briefs	Google Sheets	CDC Briefs
Fuente de ejecuciones	Google Sheets	Propuestas Ejecutadas / Externas
Versionado	Gitea	Backup del workflow y documentación

Integraciones externas

Sistema	Tipo de integración	Datos que fluyen
Google Chat	Webhook / OAuth	Preguntas entrantes y respuestas salientes
Google Sheets	OAuth	Lectura de propuestas, briefs y ejecuciones
Gemini	API / LangChain Agent	Generación de respuestas contextualizadas
n8n Memory	Memoria temporal	Contexto de seguimiento por hilo o espacio
Gitea	Git / backup	Export del workflow y README

---

FUENTES DE DATOS

1. Banco de Propuestas

Campo	Detalle
Documento	BANCO DE PROPUESTAS DE CDC PARA FULGENCIO FUMADO
Hoja	propuestas
Nodo	Sheets - Leer propuestas
Uso	Consultar propuestas originales, casos, campañas, presentaciones base y referencias creativas

2. CDC Briefs

Campo	Detalle
Documento	CDC Brief - Base para Fulgencio
Hoja	Briefs
Nodo	Sheets - Leer briefs CDC
Uso	Consultar briefs, solicitudes creativas y requerimientos existentes

3. Propuestas Ejecutadas / Externas

Campo	Detalle
Documento	Fulgencio - Propuestas Ejecutadas
Hoja	propuestas_ejecutadas
Nodo	Sheets - Leer propuestas ejecutadas
Uso	Consultar ejecuciones reales, presentaciones de ejecución, evidencias, propuestas externas y relaciones con propuestas originales

---

REGLAS DE NEGOCIO

Reglas generales

• Fulgencio responde usando únicamente el contexto entregado por el flujo.
• No debe inventar propuestas, briefs, enlaces, países, clientes, marcas, años, estados, fechas ni solicitantes.
• Si no encuentra coincidencias, debe indicarlo claramente.
• Si hay varias coincidencias, debe listarlas y no asumir una sola sin aclararlo.
• Si un dato aparece como PENDIENTE, vacío o no disponible, no debe inventarlo.
• No debe mencionar detalles técnicos como n8n, workflows, nodos, prompts, Sheets internos o memoria técnica.
• No debe prometer modificar sistemas, aprobar proyectos, crear documentos o actualizar datos.
• No crea imágenes. Si el usuario pide imágenes, debe indicar que esa función no está disponible actualmente.

Reglas para Banco de Propuestas

Fulgencio debe priorizar esta fuente cuando el usuario pregunte por:

• Propuestas originales.
• Casos.
• Activaciones.
• Presentaciones base.
• Campañas.
• Referencias creativas.
• Propuestas por cliente, marca, país, año, canal o tipo de acción.

Cuando responda sobre propuestas, debe incluir cuando esté disponible:

• Nombre.
• Cliente / marca.
• País.
• Año.
• Tipo de acción.
• Breve descripción.
• Enlace de la propuesta.
• Enlaces a propuestas ejecutadas si existen.

Reglas para CDC Briefs

Fulgencio debe priorizar esta fuente cuando el usuario pregunte por:

• Briefs.
• Solicitudes creativas.
• Requerimientos.
• Pedidos creativos.
• Brief ID.
• Solicitante.
• Estado de una solicitud.
• Fecha de entrega.
• Tema registrado en CDC Brief.

Cuando responda sobre briefs, debe incluir cuando esté disponible:

• Brief ID.
• Fecha de creación.
• Solicitante.
• Correo.
• Estado.
• Fecha de entrega.
• Resumen.
• Link del documento brief.
• Link de carpeta Drive.

Reglas para Propuestas Ejecutadas / Externas

Fulgencio debe priorizar esta fuente cuando el usuario pregunte por:

• Propuesta ejecutada.
• Ejecución.
• Evidencias.
• Presentación ejecutada.
• Presentación de ejecución.
• Fotos.
• Videos.
• Implementación.
• Propuesta externa.
• Carpeta de evidencias.

Cuando responda sobre ejecuciones, debe incluir cuando esté disponible:

• Presentación de ejecución.
• Resumen IA.
• Descripción de ejecución.
• Marca.
• Cliente.
• País.
• Ubicación.
• Carpeta de evidencias.
• Propuesta original link si existe.
• Estado de match o revisión si aplica.

Si el registro es PROPUESTA_EXTERNA, debe aclarar que es una propuesta externa registrada y no una propuesta original del banco.

Si el match es bajo, manual, pendiente o no determinado, no debe afirmar que corresponde definitivamente a una propuesta original.

Reglas de intención especial

Si el usuario solo saluda o envía un mensaje corto como:

Hola
Buenas
Hi
Hello
Gracias
Ok
Listo
Perfecto

Fulgencio no debe buscar propuestas ni briefs. Debe responder con una bienvenida breve y ejemplos de uso.

Si el usuario pide crear un brief, debe compartir el enlace general del formulario de brief.

Si el usuario pide acceder al Tablero CDC, debe compartir el enlace general del Tablero CDC.

---

CONFIGURACIÓN Y SETUP

Prerrequisitos

• Acceso a n8n en el entorno GLM.
• Acceso al Google Chat donde está instalado Fulgencio.
• Acceso al Banco de Propuestas de Fulgencio.
• Acceso al Sheet de CDC Briefs.
• Acceso al Sheet de Propuestas Ejecutadas.
• Credencial Google Sheets configurada.
• Credencial Google Chat configurada.
• Credencial Gemini configurada.
• Acceso al repositorio Gitea fulgenciochat-v3-glm.

Credenciales / variables

Credencial / Variable	Descripción	Dónde se obtiene
Google Sheets OAuth	Permite leer las fuentes de datos	n8n Credentials
Google Chat OAuth	Permite enviar respuesta al espacio de Google Chat	n8n Credentials
Google Chat Webhook	Recibe mensajes desde Google Chat	n8n Webhook
Gemini API	Permite generar respuestas con IA	n8n Credentials
BANCO_PROPUESTAS_SHEET_ID	ID del banco de propuestas	Google Sheets
CDC_BRIEFS_SHEET_ID	ID del Sheet de CDC Briefs	Google Sheets
PROPUESTAS_EJECUTADAS_SHEET_ID	ID del Sheet de propuestas ejecutadas	Google Sheets
ERROR_WORKFLOW_ID	Workflow de error configurado si aplica	n8n

Nunca commitear credenciales al repo. Todas las keys, tokens, credenciales OAuth y webhooks deben mantenerse en n8n Credentials, variables seguras o vault interno GLM.

Esquema de base de datos

No aplica.

Este flujo no usa Supabase/Postgres directamente. Sus fuentes son Google Sheets y Google Chat.

Instalación / Deploy

git clone https://git.digitalcompass.agency/Isaac_Aracena/fulgenciochat-v3-glm.git

# En n8n:
# 1. Abrir n8n.
# 2. Importar el JSON del workflow.
# 3. Validar Webhook de Google Chat.
# 4. Validar credencial de Google Sheets.
# 5. Validar credencial de Google Chat.
# 6. Validar credencial de Gemini.
# 7. Ejecutar prueba desde Google Chat.
# 8. Revisar n8n Executions.
# 9. Activar el workflow.

---

CÓMO FUNCIONA

Flujo paso a paso

1. Webhook1

   • Recibe el evento POST desde Google Chat.

2. Respond to Webhook

   • Responde inmediatamente al usuario con:

   ⏳ Procesando tu solicitud, dame un momento...
   

3. Code - Preparar mensaje

   • Extrae la pregunta del usuario.
   • Limpia mención del bot.
   • Captura usuario, correo, espacio, hilo y nombre del mensaje.
   • Prepara los datos para las búsquedas.

4. Sheets - Leer propuestas

   • Lee el Banco de Propuestas.

5. Code - Filtrar propuestas relevantes

   • Detecta intención especial.
   • Extrae filtros como cantidad, país, año, canal y estado.
   • Calcula score de relevancia.
   • Devuelve candidatos y contexto de propuestas.

6. Sheets - Leer briefs CDC

   • Lee el Sheet de CDC Briefs.

7. Code - Filtrar briefs CDC

   • Detecta si la pregunta corresponde a briefs.
   • Calcula candidatos relevantes.
   • Devuelve contexto de briefs.

8. Sheets - Leer propuestas ejecutadas

   • Lee el Sheet de Propuestas Ejecutadas / Externas.

9. Code - Filtrar propuestas ejecutadas relevantes

   • Detecta intención de ejecución o propuesta externa.
   • Filtra por tipo, país, año, marca, cliente o tokens relevantes.
   • Devuelve contexto de ejecuciones.

10. Merge - Unir propuestas y briefs Fulgencio

• Une las 3 fuentes en un solo flujo.
• Mantiene cada fuente separada por source_type.

11. Code - Construir contexto Fulgencio

• Construye el prompt final con:

  • Contexto de propuestas.
  • Contexto de CDC Briefs.
  • Contexto de propuestas ejecutadas / externas.

• Define reglas para que Gemini responda sin mezclar fuentes.

12. AI Agent - Gemini Fulgencio

• Genera la respuesta usando el contexto filtrado.
• Usa memoria simple para seguimiento.

13. Code - Formatear respuesta Chat

• Limpia la respuesta.
• Aplica límite de longitud.
• Devuelve texto final.

14. Chat - Enviar respuesta

• Envía la respuesta al espacio de Google Chat correspondiente.

---

TRIGGERS

Trigger	Frecuencia	Descripción
Webhook POST /googlechat	On demand	Se dispara cuando un usuario escribe a Fulgencio en Google Chat
Ejecución manual	Bajo demanda	Permite pruebas desde n8n con data fijada

---

EJEMPLOS DE USO

Propuestas originales

Dame las 5 últimas propuestas de Motorola.

Busca propuestas de Nestlé en República Dominicana.

Dame propuestas aprobadas de activación en PDV.

CDC Briefs

Dame los últimos briefs creados.

Busca briefs relacionados con Motorola.

Dame el brief ID BRF-123.

Propuestas ejecutadas

Envíame la presentación de la propuesta ejecutada de Pollo Campero Guatemala.

¿Tenemos ejecuciones de Pollo Campero en Guatemala?

Dame el resumen y la carpeta de evidencias de la ejecución de Pollo Campero.

Propuestas externas

Dame propuestas externas registradas.

Busca propuestas externas relacionadas con retail.

Relación propuesta original + ejecución

Dame la propuesta original y la ejecución relacionada de Pollo Campero Guatemala WMC.

---

OUTPUTS

Respuesta inmediata

El usuario recibe primero:

⏳ Procesando tu solicitud, dame un momento...

Respuesta final

La respuesta final puede incluir:

• Lista de propuestas.
• Resumen de una propuesta.
• Link a presentación original.
• Lista de briefs.
• Link a documento de brief.
• Link a carpeta Drive.
• Link a presentación ejecutada.
• Link a carpeta de evidencias.
• Resumen IA de ejecución.
• Aclaraciones si no hay resultados.
• Sugerencias de filtros.

---

TESTING

Casos de prueba mínimos

Caso	Input	Output esperado	Estado
Saludo simple	Hola	Bienvenida breve y ejemplos de uso	A completar
Propuesta por marca	Dame propuestas de Motorola	Lista de propuestas Motorola	A completar
Propuesta por país	Busca propuestas de Nestlé en República Dominicana	Propuestas filtradas por país/marca	A completar
Últimas propuestas	Dame las 5 últimas propuestas	5 resultados recientes según contexto	A completar
Briefs recientes	Dame los últimos briefs creados	Lista de briefs recientes	A completar
Brief específico	Busca briefs relacionados con Motorola	Briefs relacionados si existen	A completar
Ejecución específica	Envíame la presentación de la propuesta ejecutada de Pollo Campero	Link de presentación ejecutada si existe	A completar
Propuestas externas	Dame propuestas externas registradas	Lista de externas o mensaje sin resultados	A completar
Sin resultados	Busca propuestas de una marca inexistente	Mensaje indicando que no encontró coincidencias	A completar
Crear brief	Necesito crear un brief	Link del formulario de brief	A completar
Tablero CDC	Necesito acceder al Tablero CDC	Link al Tablero CDC	A completar
Imagen	Créame una imagen	Indica que crear imágenes no está disponible	A completar
Seguimiento	Dame el enlace de la segunda	Usa memoria reciente si aplica	A completar

Checklist de prueba rápida

• Google Chat recibe respuesta inmediata.
• Google Chat recibe respuesta final.
• El workflow lee Banco de Propuestas.
• El workflow lee CDC Briefs.
• El workflow lee Propuestas Ejecutadas / Externas.
• El Merge recibe 3 inputs.
• El contexto combinado separa fuentes correctamente.
• Gemini no inventa resultados cuando no hay candidatos.
• Los links se devuelven completos.
• La memoria funciona para preguntas de seguimiento.
• n8n Executions queda en verde.
• Workflow exportado y commiteado en Gitea.

---

ERRORES CONOCIDOS Y TROUBLESHOOTING

Error	Causa probable	Solución
Webhook no responde	URL de Google Chat mal configurada	Revisar Webhook /googlechat en n8n
Solo llega “procesando”	Falló el flujo después del Respond to Webhook	Revisar n8n Executions
Error 401/403 Google Sheets	Credencial sin permisos	Compartir Sheets con cuenta OAuth usada
Error 401/403 Google Chat	Credencial de Chat vencida o sin permiso	Renovar credencial en n8n
Gemini no responde	Credencial Gemini o cuota del modelo	Revisar credencial y ejecución
Fulgencio inventa o mezcla fuentes	Prompt o contexto mal construido	Revisar Code - Construir contexto Fulgencio
No encuentra propuestas ejecutadas	Sheet sin registros o filtros muy estrictos	Revisar propuestas_ejecutadas y filtros
No encuentra externas	No hay registros marcados como externa, sin match o revisión	Revisar columnas de tipo/match en el Sheet
No responde en el hilo correcto	space_name o thread_name vacío	Revisar Code - Preparar mensaje
Error con nodo Webhook	Código referencia un nombre de nodo incorrecto	Usar $json en vez de $('Webhook')
Respuesta muy larga	Muchos candidatos en contexto	Ajustar límites o pedir al usuario filtro más específico

---

MONITOREO

• Revisar n8n Executions después de pruebas o cambios.
• Verde = flujo correcto.
• Rojo = revisar error de nodo.
• Validar que las 3 fuentes sigan accesibles.
• Revisar que los encabezados de los Sheets no cambien.
• Revisar que Google Chat siga enviando respuestas.
• Confirmar que Gemini no consuma contexto innecesario.
• Mantener export actualizado en Gitea.
• Probar periódicamente preguntas de propuestas, briefs, ejecutadas y externas.

Output esperado normal

El flujo debe:

• Recibir pregunta desde Google Chat.
• Responder “procesando”.
• Leer las 3 fuentes.
• Filtrar candidatos.
• Construir contexto.
• Generar respuesta con Gemini.
• Enviar respuesta final.
• Terminar sin errores.

---

ESTRUCTURA DEL REPOSITORIO

/fulgenciochat-v3-glm
|-- README.md
|-- fulgenciochat-v3-glm.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 — v3.0

• Creación de FulgencioChat V3 - GLM.
• Integración con Google Chat.
• Lectura del Banco de Propuestas.
• Lectura de CDC Briefs.
• Integración de Propuestas Ejecutadas / Externas.
• Merge de 3 fuentes.
• Contexto combinado con fuentes separadas.
• Reglas de respuesta con Gemini.
• Memoria simple para seguimiento.
• Backup del workflow en Gitea.
• Documentación inicial del README.

---

DECISIONS LOG

DEC-001 — Usar Google Chat como canal principal

• Fecha: 2026-06
• Contexto: El equipo necesitaba consultar información interna sin abrir una app adicional.
• Opciones consideradas: App web, WhatsApp, Google Chat.
• Decisión: Usar Google Chat.
• Razón: Es canal interno, corporativo y adecuado para consultas rápidas.

DEC-002 — Responder inmediatamente antes del procesamiento

• Fecha: 2026-06
• Contexto: Algunas consultas pueden tardar por lectura de Sheets y generación de IA.
• Opciones consideradas: Esperar respuesta final vs responder “procesando”.
• Decisión: Enviar respuesta inmediata.
• Razón: Mejora experiencia del usuario y evita percepción de fallo.

DEC-003 — Mantener fuentes separadas en el contexto

• Fecha: 2026-06
• Contexto: Propuestas, briefs y ejecuciones representan objetos distintos.
• Opciones consideradas: Mezclar todo en una sola búsqueda vs separar por fuente.
• Decisión: Separar fuentes por source_type.
• Razón: Evita confundir una propuesta original con un brief o una ejecución.

DEC-004 — Usar Gemini con contexto filtrado

• Fecha: 2026-06
• Contexto: Enviar todo el banco completo a Gemini sería costoso, lento y menos preciso.
• Opciones consideradas: Enviar todos los datos vs filtrar candidatos antes.
• Decisión: Filtrar candidatos con código antes de llamar a Gemini.
• Razón: Mejora precisión, reduce latencia y controla el contexto.

DEC-005 — Agregar Propuestas Ejecutadas / Externas como tercera fuente

• Fecha: 2026-06
• Contexto: Fulgencio debía poder consultar presentaciones de ejecución y propuestas externas.
• Opciones consideradas: Mantener solo banco original vs agregar fuente de ejecuciones.
• Decisión: Agregar propuestas_ejecutadas.
• Razón: Permite consultar evidencias, presentaciones ejecutadas y externas desde el mismo chat.

DEC-006 — No permitir creación de imágenes desde Fulgencio

• Fecha: 2026-06
• Contexto: El usuario puede pedir imágenes, pero el flujo no está diseñado para generarlas.
• Decisión: Responder que la creación de imágenes no está disponible.
• Razón: Evita prometer capacidades que el sistema no ejecuta.

---

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 Google Chat validado.
• Respuesta inmediata validada.
• Respuesta final validada.
• Banco de Propuestas conectado.
• CDC Briefs conectado.
• Propuestas Ejecutadas / Externas conectado.
• Merge de 3 fuentes validado.
• Contexto combinado validado.
• Gemini responde sin inventar resultados.
• Memoria de seguimiento validada.
• Casos de prueba básicos ejecutados.
• 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, tokens ni secretos.
• Si cambia un encabezado de los Sheets, revisar los nodos de filtrado.
• Si cambia el Google Chat, revisar Webhook y credenciales.
• Si Fulgencio deja de encontrar datos, validar primero los Sheets fuente.
• Si se agregan nuevas fuentes, actualizar el Merge y Code - Construir contexto Fulgencio.
• Si se modifica el prompt del agente, actualizar este README y registrar la decisión.
• Si se cambia el modelo Gemini, documentarlo en CHANGELOG.

---