Isaac_Aracena/fulgencio-procesar-propuestas-en-bruto-glm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e5adeb292d42ee94966d25c077b8030e366cf19c
fulgencio-procesar-propuest…/README.md
T
Isaac_Aracena e5adeb292d Actualizar README.md
2026-06-25 01:57:28 +00:00

602 lines
24 KiB
Markdown
Raw Blame History

# Fulgencio Procesar Propuestas en Bruto - GLM
> Workflow n8n que procesa automáticamente propuestas cargadas en bruto, extrae metadata con Gemini, normaliza los datos según las listas del Banco de Propuestas de Fulgencio, agrega la propuesta al Google Sheet oficial y mueve el archivo a la carpeta de propuestas procesadas.
---
## INFORMACIÓN GENERAL
| Campo | Detalle |
| ------------------------ | -------------------------------------------- |
| Proyecto | Fulgencio Procesar Propuestas en Bruto - GLM |
| Área | CDC / Proyectos IT / Creatividad y Diseño |
| Estado | Producción |
| Developer Principal | Isaac Aracena |
| IT Manager | Luis Matos |
| Product Owner | Máximo Gómez |
| Ciclo Shape Up | CDC Fulgencio V2.0 |
| Repositorio Gitea | `fulgencio-procesar-propuestas-en-bruto-glm` |
| Workflow n8n | Fulgencio Procesar Propuestas en Bruto - GLM |
| Estado del workflow | Activo |
---
## OBJETIVO
### Problema que resuelve
El Banco de Propuestas de Fulgencio necesita mantenerse actualizado con nuevas propuestas para que el asistente pueda consultarlas posteriormente por cliente, marca, país, año, canal, tipo de acción, etiquetas y descripción.
Antes de este flujo, alimentar el banco dependía de digitación manual. Ese proceso podía ser lento, propenso a errores y difícil de escalar cuando se recibían muchas propuestas nuevas.
También existía el riesgo de que archivos cargados en bruto quedaran sin procesar, con nombres inconsistentes o sin metadata suficiente para ser encontrados luego por Fulgencio.
### Solución implementada
Este workflow automatiza el procesamiento inicial de propuestas cargadas en la carpeta de Drive **BANCO DE PROPUESTAS EN BRUTO**.
El flujo:
* Detecta archivos nuevos o actualizados en la carpeta de propuestas en bruto.
* Lee el nombre del archivo y metadata disponible.
* Extrae el país desde el estándar `[PAIS=PAIS] Nombre de la propuesta AÑO`.
* Usa Gemini para inferir metadata como cliente, marca, año, tipo de acción, canal, etiquetas, descripción y táctica promocional.
* Normaliza los valores contra listas permitidas.
* Marca campos dudosos como `PENDIENTE`, `OTRO` o `requiere_revision`.
* Agrega la propuesta al Google Sheet del Banco de Propuestas de Fulgencio.
* Mueve el archivo a la carpeta **PROPUESTAS PROCESADAS**.
### Usuarios / Beneficiarios
| Usuario | Beneficio |
| ---------------------- | ------------------------------------------------------------ |
| Equipo CDC | Reduce digitación manual y organiza nuevas propuestas. |
| Equipo IT | Mantiene una carga automatizada y controlada hacia el banco. |
| Fulgencio V2.0 | Recibe propuestas nuevas para futuras consultas. |
| Usuarios internos GLM | Pueden consultar propuestas recientes desde Google Chat. |
| Responsables del banco | Detectan propuestas que requieren revisión manual. |
---
## ARQUITECTURA
### Diagrama de flujo
```txt
[Google Drive Trigger - fileCreated / fileUpdated]
↓
[Loop - Archivos]
↓
[Code - Preparar archivo]
↓
[Gemini - Extraer metadata]
↓
[Code - Normalizar respuesta]
↓
[Sheets - Agregar propuesta]
↓
[Drive - Mover a procesadas]
↓
[Loop - Archivos]
```
### Stack tecnológico
| Componente | Tecnología | Propósito |
| -------------------- | ------------------------ | ---------------------------------------- |
| Automatización | n8n | Orquestación del flujo |
| Entrada de archivos | Google Drive Trigger | Detecta propuestas nuevas o actualizadas |
| IA | Gemini | Extrae metadata estructurada |
| Normalización | Code node JavaScript | Limpia, normaliza y valida valores |
| Base de conocimiento | Google Sheets | Banco de Propuestas de Fulgencio |
| Gestión documental | Google Drive | Mueve archivos procesados |
| Versionado | Gitea | Backup del workflow y documentación |
### Integraciones externas
| Sistema | Tipo de integración | Datos que fluyen |
| ------------- | ------------------------ | ---------------------------------------------------------------- |
| Google Drive | OAuth / Trigger | Archivos nuevos o actualizados en carpeta de propuestas en bruto |
| Gemini | API | Extracción de metadata desde nombre y contexto del archivo |
| Google Sheets | OAuth | Inserción de propuesta procesada en el banco |
| Google Drive | OAuth | Movimiento del archivo a carpeta de procesadas |
| n8n | Workflow automation | Ejecución, logs y control del proceso |
| Gitea | Git / backup | Export del workflow y README |
---
## FUENTES Y DESTINOS
### Carpeta de entrada
| Campo | Detalle |
| ------- | ------------------------------------------------------------- |
| Carpeta | BANCO DE PROPUESTAS EN BRUTO |
| Uso | Carpeta donde se cargan las propuestas pendientes de procesar |
| Trigger | Archivo creado o archivo actualizado |
### Google Sheet destino
| Campo | Detalle |
| --------- | ------------------------------------------------ |
| Documento | BANCO DE PROPUESTAS DE CDC PARA FULGENCIO FUMADO |
| Hoja | propuestas |
| Uso | Banco principal que consulta Fulgencio |
### Carpeta de salida
| Campo | Detalle |
| ------- | ------------------------------------------------------------------------- |
| Carpeta | PROPUESTAS PROCESADAS |
| Uso | Carpeta donde se mueven los archivos después de registrarse correctamente |
---
## REGLAS DE NEGOCIO
### Estándar de nombre de archivo
El archivo debe usar preferiblemente este formato:
```txt
[PAIS=PAIS] Nombre de la propuesta AÑO
```
Ejemplos:
```txt
[PAIS=GUATEMALA] Pollo Campero RTM WMC 2026.pptx
[PAIS=REPUBLICA DOMINICANA] Motorola Activación PDV 2026.pdf
[PAIS=COSTA RICA] Kit Kat Sampling Supermercado 2025.pptx
```
### Reglas de país
* El país se toma del nombre del archivo, específicamente del patrón `[PAIS=...]`.
* Gemini no debe inventar ni cambiar el país.
* Si no se detecta país, se guarda como `SIN PAIS DEFINIDO`.
* Si el país no coincide con la lista permitida, se marca como `SIN PAIS DEFINIDO`.
* Los registros sin país definido quedan marcados para revisión.
### Países permitidos
* EL SALVADOR
* PANAMA
* REPUBLICA DOMINICANA
* COLOMBIA
* PUERTO RICO
* HONDURAS
* MEXICO
* VENEZUELA
* JAMAICA
* TRINIDAD Y TOBAGO
* COSTA RICA
* NICARAGUA
* GUATEMALA
* SIN PAIS DEFINIDO
### Campos extraídos por Gemini
Gemini intenta extraer:
* Nombre de propuesta
* Cliente
* Marca
* Cliente normalizado
* Marca normalizada
* Año
* Tipo de acción
* Canal
* Tags
* Descripción
* Táctica promocional
### Campos no determinados por Gemini
Por regla de negocio:
* `APROBADA` no la decide Gemini.
* `AMBIENTE DE COMPRA (RE)` no la decide Gemini.
Estos campos se guardan como pendientes o valores por revisar según corresponda.
### Reglas de normalización
El flujo normaliza valores para que coincidan con las listas del Google Sheet.
Ejemplos:
| Entrada posible | Salida normalizada |
| --------------- | ----------------------------------- |
| Nestlé | NESTLE |
| Nescafé | NESCAFE |
| KitKat | KIT KAT |
| Sampling | SAMPLING - MUESTREO |
| Punto de venta | PDV / ACTIVACION EN PDV según campo |
| Canal moderno | MODERNO |
| Whirpool | WHIRLPOOL |
### Reglas de revisión
Una propuesta queda marcada con `requiere_revision = true` si:
* El país no se detecta.
* El país no es válido.
* El tipo de acción queda como `OTRO` o `PENDIENTE`.
* El cliente queda como `OTRO` o `PENDIENTE`.
* La marca queda como `OTRO` o `PENDIENTE`.
* El canal queda como `PENDIENTE`.
* La táctica promocional queda como `OTRO` o `PENDIENTE`.
* Las etiquetas quedan como `OTRO` o `PENDIENTE`.
* El año queda como `PENDIENTE`.
Los motivos se guardan en la columna:
```txt
motivos_revision
```
### Reglas de cierre
* La propuesta solo se mueve a **PROPUESTAS PROCESADAS** después de agregarse correctamente al Sheet.
* Si falla la escritura en Sheets, el archivo no debería considerarse procesado.
* Si falla Gemini o la normalización, revisar n8n Executions.
* Si una propuesta queda con campos dudosos, se registra igual, pero marcada para revisión.
---
## CONFIGURACIÓN Y SETUP
### Prerrequisitos
* Acceso a n8n en el entorno GLM.
* Acceso a Google Drive con permisos sobre:
* `BANCO DE PROPUESTAS EN BRUTO`
* `PROPUESTAS PROCESADAS`
* Acceso al Google Sheet:
* `BANCO DE PROPUESTAS DE CDC PARA FULGENCIO FUMADO`
* Credencial de Google Drive configurada en n8n.
* Credencial de Google Sheets configurada en n8n.
* Credencial de Gemini configurada en n8n.
* Acceso al repositorio Gitea `fulgencio-procesar-propuestas-en-bruto-glm`.
### Credenciales / variables
| Credencial / Variable | Descripción | Dónde se obtiene |
| ------------------------- | -------------------------------------------- | ---------------- |
| Google Drive OAuth | Permite detectar y mover archivos en Drive | n8n Credentials |
| Google Sheets OAuth | Permite agregar filas al banco de propuestas | n8n Credentials |
| Gemini API | Permite extraer metadata con IA | n8n Credentials |
| RAW_FOLDER_ID | ID de carpeta BANCO DE PROPUESTAS EN BRUTO | Google Drive |
| PROCESSED_FOLDER_ID | ID de carpeta PROPUESTAS PROCESADAS | Google Drive |
| BANCO_PROPUESTAS_SHEET_ID | ID del Google Sheet del banco | Google Sheets |
| ERROR_WORKFLOW_ID | Workflow de error configurado para fallos | n8n |
> Nunca commitear credenciales al repo. Todas las keys, tokens y accesos deben mantenerse en n8n Credentials, variables seguras o vault interno GLM.
### Esquema de base de datos
No aplica.
Este flujo no usa Supabase/Postgres. La fuente principal y destino son Google Drive y Google Sheets.
### Instalación / Deploy
```bash
git clone https://git.digitalcompass.agency/Isaac_Aracena/fulgencio-procesar-propuestas-en-bruto-glm.git
# En n8n:
# 1. Abrir n8n.
# 2. Importar el JSON del workflow.
# 3. Revisar credenciales de Google Drive.
# 4. Revisar credenciales de Google Sheets.
# 5. Revisar credencial de Gemini.
# 6. Validar carpeta de entrada BANCO DE PROPUESTAS EN BRUTO.
# 7. Validar carpeta de salida PROPUESTAS PROCESADAS.
# 8. Validar Google Sheet destino.
# 9. Ejecutar prueba con archivo controlado.
# 10. Activar el workflow.
```
---
## CÓMO FUNCIONA
### Flujo paso a paso
1. **Trigger - Nueva propuesta en bruto**
* Se activa cuando se crea un archivo nuevo en la carpeta de propuestas en bruto.
2. **Trigger - Nueva propuesta en bruto1**
* Se activa cuando se actualiza un archivo en la misma carpeta.
3. **Loop - Archivos**
* Procesa archivos por lote para evitar errores cuando entran varios archivos.
4. **Code - Preparar archivo**
* Obtiene:
* ID del archivo.
* Nombre del archivo.
* Link de Drive.
* Tipo MIME.
* Nombre limpio.
* País detectado desde `[PAIS=...]`.
* Confianza del país.
* Revisión inicial si el país falta o es inválido.
5. **Gemini - Extraer metadata**
* Usa el nombre del archivo, país, tipo de archivo y link para inferir metadata.
* Devuelve campos estructurados.
6. **Code - Normalizar respuesta**
* Limpia y normaliza la salida de Gemini.
* Convierte valores a los estándares del banco.
* Aplica listas permitidas.
* Marca `requiere_revision` y `motivos_revision`.
7. **Sheets - Agregar propuesta**
* Agrega la propuesta procesada al Google Sheet del banco.
8. **Drive - Mover a procesadas**
* Mueve el archivo desde la carpeta en bruto hacia la carpeta de procesadas.
9. **Loop - Archivos**
* Continúa con el siguiente archivo si hay más pendientes.
### Triggers
| Trigger | Frecuencia | Descripción |
| ------------------------ | ------------ | --------------------------------------------------------- |
| Google Drive fileCreated | Cada minuto | Detecta archivos nuevos en carpeta de propuestas en bruto |
| Google Drive fileUpdated | Cada minuto | Detecta archivos actualizados en la misma carpeta |
| Ejecución manual | Bajo demanda | Permite pruebas desde n8n |
---
## OUTPUTS
### Registro en Banco de Propuestas
El flujo agrega una fila con campos como:
| Campo | Descripción |
| ----------------------- | --------------------------------------- |
| NOMBRE | Nombre limpio de la propuesta |
| TIPO DE ACCION | Tipo de acción normalizado |
| CLIENTE | Cliente normalizado |
| MARCA | Marca normalizada |
| PAIS | País detectado desde el nombre |
| CANAL | Canal normalizado |
| AMBIENTE DE COMPRA (RE) | Pendiente por regla actual |
| TÁCTICA PROMOCIONAL | Táctica inferida y normalizada |
| APROBADA | Pendiente de aprobación |
| ETIQUETAS | Tags normalizados |
| AÑO | Año detectado o pendiente |
| Enlace a la propuesta | Link del archivo en Drive |
| Descripcion | Descripción profesional generada por IA |
| file_id | ID del archivo en Drive |
| nombre_archivo | Nombre original del archivo |
| mime_type | Tipo MIME |
| fuente_pais | Fuente de detección del país |
| confianza_pais | Nivel de confianza |
| requiere_revision | Indica si requiere revisión manual |
| motivos_revision | Motivos por los que requiere revisión |
| procesado_ia | Indica que fue procesado por IA |
| ultima_actualizacion | Timestamp del procesamiento |
### Movimiento de archivo
Al finalizar correctamente:
```txt
BANCO DE PROPUESTAS EN BRUTO
↓
PROPUESTAS PROCESADAS
```
---
## TESTING
### Casos de prueba mínimos
| Caso | Input | Output esperado | Estado |
| ------------------- | ----------------------------------------------- | ----------------------------------------------------- | ----------- |
| Caso feliz | Archivo con `[PAIS=GUATEMALA] Nombre 2026.pptx` | Fila agregada y archivo movido | A completar |
| País faltante | Archivo sin `[PAIS=...]` | PAIS = SIN PAIS DEFINIDO y requiere revisión | A completar |
| País inválido | Archivo con país no permitido | PAIS = SIN PAIS DEFINIDO | A completar |
| Cliente claro | Nombre con cliente/marca reconocible | CLIENTE y MARCA normalizados | A completar |
| Año faltante | Archivo sin año | AÑO = PENDIENTE | A completar |
| Táctica dudosa | No se puede inferir mecánica | TÁCTICA PROMOCIONAL = PENDIENTE u OTRO | A completar |
| Gemini falla | Error en API Gemini | Error visible en n8n Executions | A completar |
| Sheet sin permiso | Credencial sin acceso | Error 403/401 visible | A completar |
| Drive move falla | No puede mover archivo | Fila puede quedar agregada, revisar Drive manualmente | A completar |
| Archivo actualizado | Modificación en carpeta en bruto | Trigger fileUpdated ejecuta flujo | A completar |
### Checklist de prueba rápida
* [ ] Subir archivo de prueba a `BANCO DE PROPUESTAS EN BRUTO`.
* [ ] Confirmar que el workflow se dispara.
* [ ] Confirmar que detecta el país desde `[PAIS=...]`.
* [ ] Confirmar que Gemini devuelve metadata.
* [ ] Confirmar que se normalizan cliente, marca, canal y táctica.
* [ ] Confirmar que se agrega fila al Banco de Propuestas.
* [ ] Confirmar que el archivo se mueve a `PROPUESTAS PROCESADAS`.
* [ ] Confirmar que `requiere_revision` se marca correctamente.
* [ ] Revisar n8n Executions.
* [ ] Exportar JSON actualizado.
* [ ] Commit en Gitea.
---
## ERRORES CONOCIDOS Y TROUBLESHOOTING
| Error | Causa probable | Solución |
| ---------------------------- | ----------------------------------------------------------- | ------------------------------------------------ |
| No se dispara el workflow | Trigger desactivado o carpeta incorrecta | Validar trigger y folder ID |
| País queda SIN PAIS DEFINIDO | Archivo no usa `[PAIS=...]` o país no permitido | Renombrar archivo con estándar correcto |
| Gemini devuelve PENDIENTE | Nombre del archivo no contiene suficiente contexto | Revisar archivo manualmente o mejorar nombre |
| Cliente queda OTRO | Cliente no está en lista permitida | Agregar cliente a lista o corregir manualmente |
| Marca queda OTRO | Marca no está en lista permitida | Agregar marca a lista o corregir manualmente |
| Error 401/403 Google Drive | Credencial sin permisos | Renovar credencial o compartir carpeta |
| Error 401/403 Google Sheets | Cuenta sin acceso al Sheet | Compartir Sheet con cuenta usada en n8n |
| No se mueve archivo | Permiso insuficiente en carpeta destino | Revisar acceso a `PROPUESTAS PROCESADAS` |
| Duplicados en banco | Trigger fileCreated y fileUpdated procesan el mismo archivo | Revisar si se requiere control por file_id |
| Columnas no coinciden | Encabezado del Sheet cambió | Actualizar mapeo en `Sheets - Agregar propuesta` |
| Modelo Gemini lento o falla | Servicio externo o cuota | Revisar credencial, modelo y ejecución |
---
## MONITOREO
* Revisar n8n Executions regularmente.
* Verde = flujo completado.
* Rojo = fallo que requiere revisión.
* Revisar periódicamente filas con `requiere_revision = true`.
* Confirmar que los archivos no se acumulen en `BANCO DE PROPUESTAS EN BRUTO`.
* Confirmar que los archivos procesados estén en `PROPUESTAS PROCESADAS`.
* Revisar que el Banco de Propuestas no tenga duplicados por `file_id`.
* Mantener el backup del workflow actualizado en Gitea.
### Output esperado normal
El flujo debe:
* Detectar archivo nuevo o actualizado.
* Preparar metadata base.
* Extraer metadata con Gemini.
* Normalizar valores.
* Agregar fila al banco.
* Mover archivo a procesadas.
* Terminar sin errores.
---
## ESTRUCTURA DEL REPOSITORIO
```txt
/fulgencio-procesar-propuestas-en-bruto-glm
|-- README.md
|-- fulgencio-procesar-propuestas-en-bruto-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 — v1.0
* Creación del workflow `Fulgencio Procesar Propuestas en Bruto - GLM`.
* Detección automática de archivos en carpeta en bruto.
* Extracción de metadata con Gemini.
* Normalización de cliente, marca, país, canal, etiquetas y táctica promocional.
* Registro automático en Banco de Propuestas.
* Movimiento automático a carpeta de procesadas.
* Backup del workflow en Gitea.
* Documentación inicial del README.
---
## DECISIONS LOG
### DEC-001 — Usar Google Drive como entrada operativa
* **Fecha:** 2026-06
* **Contexto:** Las propuestas nuevas llegan como archivos en una carpeta compartida.
* **Opciones consideradas:** Carga manual en Sheet vs carpeta de entrada.
* **Decisión:** Usar carpeta `BANCO DE PROPUESTAS EN BRUTO`.
* **Razón:** Permite que el equipo cargue archivos sin tocar directamente el banco.
### DEC-002 — Usar estándar `[PAIS=...]` en el nombre del archivo
* **Fecha:** 2026-06
* **Contexto:** El país es crítico para buscar propuestas correctamente.
* **Opciones consideradas:** Inferir país con IA vs tomarlo del nombre/carpeta.
* **Decisión:** Tomar país desde el nombre del archivo.
* **Razón:** Evita que Gemini invente el país.
### DEC-003 — Usar Gemini solo para metadata inferible
* **Fecha:** 2026-06
* **Contexto:** Algunas columnas pueden inferirse del nombre y contexto del archivo.
* **Decisión:** Gemini extrae cliente, marca, año, tipo de acción, canal, tags, descripción y táctica.
* **Razón:** Reduce digitación manual sin eliminar revisión humana.
### DEC-004 — No determinar APROBADA con IA
* **Fecha:** 2026-06
* **Contexto:** La aprobación requiere criterio del equipo.
* **Decisión:** Guardar `APROBADA` como `PENDIENTE DE APROBACION`.
* **Razón:** Evita que IA tome decisiones operativas que deben ser manuales.
### DEC-005 — Mover archivo solo después de registrar en Sheet
* **Fecha:** 2026-06
* **Contexto:** El archivo no debe salir de la carpeta en bruto si no se registró correctamente.
* **Decisión:** Primero agregar al Sheet y luego mover a procesadas.
* **Razón:** Reduce pérdida de trazabilidad.
---
## CONTACTOS DEL PROYECTO
| Rol | Nombre |
| ------------- | ------------- |
| Product Owner | Máximo Gómez |
| IT Manager | Luis Matos |
| Developer | Isaac Aracena |
| Soporte IT | Equipo GLM IT |
---
## DEFINITION OF DONE
* [ ] Workflow activo en n8n.
* [ ] Trigger de archivo creado validado.
* [ ] Trigger de archivo actualizado validado.
* [ ] Carpeta `BANCO DE PROPUESTAS EN BRUTO` validada.
* [ ] Carpeta `PROPUESTAS PROCESADAS` validada.
* [ ] Extracción con Gemini probada.
* [ ] Normalización de campos validada.
* [ ] Inserción en Banco de Propuestas validada.
* [ ] Movimiento de archivo validado.
* [ ] Casos de revisión manual validados.
* [ ] 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 ni tokens.
* El archivo debe seguir el estándar `[PAIS=PAIS] Nombre de la propuesta AÑO`.
* Si una propuesta no tiene país, quedará como `SIN PAIS DEFINIDO`.
* Si una propuesta tiene datos dudosos, quedará con `requiere_revision = true`.
* Si se agregan nuevos clientes, marcas, países, canales o tácticas, actualizar las listas permitidas en `Code - Normalizar respuesta`.
* Si cambia la estructura del Banco de Propuestas, actualizar el mapeo del nodo `Sheets - Agregar propuesta`.
* Si se cambia la carpeta de entrada o salida, actualizar los IDs en los nodos de Google Drive.
---
Reference in New Issue View Git Blame Copy Permalink