Isaac_Aracena/fulgencio-alertas-sheets-glm
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
fulgencio-alertas-sheets-glm/README.md
T
Isaac_Aracena 0199fe0852 Actualizar README.md
2026-06-25 01:59:49 +00:00

480 lines
20 KiB
Markdown
Raw Permalink Blame History

# Fulgencio Alertas Sheets - GLM
> Workflow n8n que revisa semanalmente el Banco de Propuestas de Fulgencio, detecta campos vacíos, pendientes o inconsistentes, envía una alerta resumida a Google Chat y guarda el detalle en un Sheet de reporte para revisión operativa.
---
## INFORMACIÓN GENERAL
| Campo | Detalle |
| ------------------------ | ----------------------------------------- |
| Proyecto | Fulgencio Alertas Sheets - GLM |
| Área | CDC |
| 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-alertas-sheets-glm` |
| Workflow n8n | Fulgencio Alertas Sheets - GLM |
| Estado del workflow | Activo |
| Zona horaria | America/Santo_Domingo |
---
## OBJETIVO
### Problema que resuelve
El Banco de Propuestas de Fulgencio depende de información estructurada para que el asistente pueda responder correctamente sobre propuestas, clientes, marcas, países, canales, enlaces y descripciones.
Cuando una propuesta queda con campos vacíos, valores `PENDIENTE`, `SIN PAIS DEFINIDO`, `OTRO`, `N/A`, `NULL`, `UNDEFINED` o datos ubicados en columnas incorrectas, Fulgencio puede perder precisión en sus respuestas o dejar de encontrar propuestas relevantes.
Antes de este flujo, la revisión de esos pendientes dependía de inspección manual del Google Sheet, lo que podía provocar retrasos, errores no detectados y acumulación de datos incompletos.
### Solución implementada
Este workflow automatiza la revisión semanal del Banco de Propuestas de Fulgencio.
El flujo:
* Lee el Google Sheet del Banco de Propuestas.
* Revisa columnas clave de negocio.
* Detecta campos vacíos, pendientes o inválidos.
* Agrupa los pendientes por fila y por columna.
* Envía una alerta resumida al Google Chat de alertas.
* Guarda el detalle completo en un Sheet de reporte.
* Permite al equipo CDC / IT revisar y corregir los datos pendientes.
### Usuarios / Beneficiarios
| Usuario | Beneficio |
| --------------------------------------- | ---------------------------------------------------------- |
| Equipo CDC | Identifica propuestas con datos incompletos o pendientes. |
| Equipo IT | Monitorea la calidad de datos que alimenta Fulgencio. |
| Usuarios de Fulgencio | Obtienen mejores respuestas gracias a datos más completos. |
---
## ARQUITECTURA
### Diagrama de flujo
```txt
[Schedule Trigger semanal]
↓
[Sheets - Leer propuestas]
↓
[Code - Detectar pendientes]
↓
[IF - Hay pendientes]
├── true → [HTTP Request - Enviar alerta]
│
└── true → [Code - Expandir reporte pendientes]
↓
[Sheets - Guardar detalle pendientes]
```
### Stack tecnológico
| Componente | Tecnología | Propósito |
| ----------------- | ------------------------ | ------------------------------------------- |
| Automatización | n8n | Orquestación del flujo |
| Fuente principal | Google Sheets | Banco de Propuestas de Fulgencio |
| Reporte operativo | Google Sheets | Registro detallado de pendientes |
| Alertas | Google Chat Webhook | Envío de tarjeta/resumen al chat de alertas |
| Versionado | Gitea | Backup del workflow y documentación |
### Integraciones externas
| Sistema | Tipo de integración | Datos que fluyen |
| --------------------------------- | ---------------------- | -------------------------------------- |
| Banco de Propuestas de Fulgencio | Google Sheets OAuth | Lectura de propuestas y metadata |
| Fulgencio - Reporte de Pendientes | Google Sheets OAuth | Escritura del detalle de pendientes |
| Google Chat | Webhook / HTTP Request | Envío de alerta resumida |
| n8n Executions | Interno n8n | Logs, errores y auditoría de ejecución |
| Gitea | Git / backup | Export del workflow y README |
---
## FUENTES DE DATOS
### Google Sheet leído
| Campo | Detalle |
| --------- | -------------------------------------------------------------- |
| Documento | BANCO DE PROPUESTAS DE CDC PARA FULGENCIO FUMADO |
| Hoja | propuestas |
| Uso | Fuente principal que se revisa para detectar campos pendientes |
### Google Sheet de reporte
| Campo | Detalle |
| --------- | ------------------------------------------------------------------------------- |
| Documento | Fulgencio - Reporte de Pendientes |
| Hoja | pendientes_revision |
| Uso | Guarda el detalle fila por fila y campo por campo de los pendientes encontrados |
---
## REGLAS DE NEGOCIO
### Columnas validadas
El flujo valida las siguientes columnas del Banco de Propuestas:
* `NOMBRE`
* `TIPO DE ACCION`
* `CLIENTE`
* `MARCA`
* `PAIS`
* `CANAL`
* `ETIQUETAS`
* `AÑO`
* `Enlace a la propuesta`
* `Descripcion`
### Columnas no validadas
La columna `APROBADA` no se valida en este flujo porque el equipo puede completarla manualmente más adelante.
### Valores considerados pendientes o inválidos
Un campo se considera pendiente cuando:
* Está vacío.
* Tiene valor `PENDIENTE`.
* Tiene valor `UNDEFINED`.
* Tiene valor `NULL`.
* Tiene valor `N/A`.
* Tiene valor `SIN PAIS DEFINIDO`.
* Contiene `OTRO`.
* Tiene un valor de aprobación en una columna incorrecta, por ejemplo:
* `APROBADA`
* `NO APROBADA`
* `PENDIENTE DE APROBACION`
### Reglas de alerta
* Si no hay pendientes, el flujo devuelve un mensaje interno de éxito y no envía alerta de revisión.
* Si hay pendientes, envía una tarjeta resumida al Google Chat configurado.
* Si hay más de 40 filas pendientes, la alerta muestra solo las primeras 40 filas prioritarias.
* El detalle completo se guarda en el Sheet de reporte.
* Las filas prioritarias se ordenan por cantidad de campos pendientes.
* El resumen de columnas muestra las columnas con más pendientes.
### Reglas de seguridad
* No commitear credenciales, tokens ni URLs privadas de webhooks en documentación pública.
* El webhook de Google Chat debe gestionarse desde n8n o desde el vault interno.
* Si se rota el webhook, actualizar el nodo en n8n y exportar nuevamente el workflow.
* No exponer tokens de Google Chat en README, tickets públicos ni capturas compartidas.
---
## CONFIGURACIÓN Y SETUP
### Prerrequisitos
* Acceso a n8n en el entorno GLM.
* Acceso al Google Sheet `BANCO DE PROPUESTAS DE CDC PARA FULGENCIO FUMADO`.
* Acceso al Google Sheet `Fulgencio - Reporte de Pendientes`.
* Credencial `Google Sheets account 2` configurada en n8n.
* Webhook de Google Chat configurado en el nodo `HTTP Request - Enviar alerta`.
* Permisos para importar/exportar workflows en n8n.
* Acceso al repositorio Gitea `fulgencio-alertas-sheets-glm`.
### Credenciales / variables
| Credencial / Variable | Descripción | Dónde se obtiene |
| --------------------- | ----------------------------------------------------------- | ----------------- |
| Google Sheets OAuth | Permite leer y escribir en los Sheets del flujo | n8n Credentials |
| Google Chat Webhook | Permite enviar alertas al espacio de Google Chat | Google Chat / n8n |
| SHEET_URL | Link del Banco de Propuestas usado en el botón de la alerta | Google Sheets |
| N8N_WORKFLOW_ID | ID interno del workflow en n8n | n8n |
| ERROR_WORKFLOW_ID | Workflow de error configurado para fallos | n8n |
> Nunca commitear credenciales al repo. Todas las keys, tokens 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. El almacenamiento del detalle de pendientes se realiza en Google Sheets.
### Instalación / Deploy
```bash
git clone https://git.digitalcompass.agency/Isaac_Aracena/fulgencio-alertas-sheets-glm.git
# En n8n:
# 1. Abrir n8n.
# 2. Importar el JSON del workflow.
# 3. Revisar credencial de Google Sheets.
# 4. Revisar webhook de Google Chat.
# 5. Ejecutar prueba manual.
# 6. Validar que lea el Banco de Propuestas.
# 7. Validar que escriba en Fulgencio - Reporte de Pendientes.
# 8. Activar el workflow.
```
---
## CÓMO FUNCIONA
### Flujo paso a paso
1. **Schedule Trigger**
* Ejecuta el flujo automáticamente cada viernes a las 9:30 AM, hora de República Dominicana.
2. **Sheets - Leer propuestas**
* Lee todas las filas de la hoja `propuestas` del Banco de Propuestas de Fulgencio.
3. **Code - Detectar pendientes**
* Revisa las columnas clave.
* Detecta valores vacíos, pendientes o inválidos.
* Agrupa pendientes por fila y por columna.
* Construye el payload para Google Chat.
* Prepara las filas que se guardarán en el reporte de pendientes.
4. **IF - Hay pendientes**
* Si `hay_pendientes = true`, continúa con alerta y guardado de detalle.
* Si `hay_pendientes = false`, el flujo termina sin enviar alerta.
5. **HTTP Request - Enviar alerta**
* Envía una tarjeta al Google Chat de alertas con:
* Fecha de revisión.
* Total de campos pendientes.
* Columnas con más pendientes.
* Primeras filas prioritarias.
* Botón para abrir el Banco de Propuestas.
6. **Code - Expandir reporte pendientes**
* Convierte el arreglo de pendientes en items individuales para poder guardarlos en Google Sheets.
7. **Sheets - Guardar detalle pendientes**
* Guarda cada pendiente en la hoja `pendientes_revision`.
### Schedule / Trigger
| Trigger | Frecuencia | Descripción |
| ---------------- | ------------------------ | -------------------------------------------------------------- |
| Schedule Trigger | Semanal, viernes 9:30 AM | Revisa el Banco de Propuestas y alerta si hay datos pendientes |
| Ejecución manual | Bajo demanda | Permite probar el flujo desde n8n |
---
## OUTPUTS
### Alerta en Google Chat
Cuando hay pendientes, el flujo envía una tarjeta con:
* Título: `Datos Pendientes - Fulgencio`
* Fecha de revisión.
* Cantidad de campos pendientes.
* Columnas con más pendientes.
* Filas prioritarias.
* Botón para abrir el Banco de Propuestas.
### Reporte en Google Sheets
Cada pendiente se guarda con estos campos:
| Campo | Descripción |
| ------------------ | ---------------------------------------- |
| fecha_revision | Fecha visible de revisión |
| fecha_revision_iso | Fecha ISO de revisión |
| fila_origen | Fila original en el Banco de Propuestas |
| propuesta | Nombre de la propuesta o archivo |
| campo | Campo pendiente |
| valor_actual | Valor encontrado |
| motivo | Motivo por el que se considera pendiente |
| enlace_propuesta | Link de la propuesta si existe |
---
## TESTING
### Casos de prueba mínimos
| Caso | Input | Output esperado | Estado |
| -------------------------------------- | ----------------------------------------------- | ------------------------------------- | ----------- |
| Sin pendientes | Banco completo y limpio | No envía alerta de revisión | A completar |
| Campos vacíos | Fila con `MARCA`, `PAIS` o `Descripcion` vacíos | Envía alerta y guarda detalle | A completar |
| Valor `PENDIENTE` | Campo con texto `PENDIENTE` | Detecta pendiente | A completar |
| Valor `SIN PAIS DEFINIDO` | Campo `PAIS` con ese valor | Detecta pendiente | A completar |
| Valor `OTRO` | Campo con opción `OTRO` | Detecta revisión necesaria | A completar |
| Valor aprobación en columna incorrecta | Campo distinto de APROBADA con `APROBADA` | Detecta inconsistencia | A completar |
| Reporte Sheets | Hay pendientes válidos | Agrega filas en `pendientes_revision` | A completar |
| Chat alerta | Hay pendientes válidos | Envía tarjeta a Google Chat | A completar |
| Error de permisos | Sheet sin acceso | Error visible en n8n Executions | A completar |
### Checklist de prueba rápida
* [ ] Ejecutar workflow manualmente.
* [ ] Confirmar lectura del Banco de Propuestas.
* [ ] Confirmar detección correcta de pendientes.
* [ ] Confirmar que `APROBADA` no se valide.
* [ ] Confirmar envío de tarjeta a Google Chat.
* [ ] Confirmar escritura en `pendientes_revision`.
* [ ] Revisar n8n Executions.
* [ ] Exportar JSON actualizado.
* [ ] Commit en Gitea.
---
## ERRORES CONOCIDOS Y TROUBLESHOOTING
| Error | Causa probable | Solución |
| ---------------------------- | ---------------------------------------------------- | --------------------------------------------------------------- |
| 401 Unauthorized | Credencial de Google Sheets vencida | Renovar credencial en n8n |
| 403 Forbidden | La cuenta de n8n no tiene acceso al Sheet | Compartir el Sheet con la cuenta correcta |
| Error en Google Chat | Webhook inválido o rotado | Actualizar webhook en el nodo HTTP |
| No se guarda detalle | Permisos insuficientes en Sheet de reporte | Validar acceso al documento `Fulgencio - Reporte de Pendientes` |
| Alerta no llega | URL de webhook incorrecta o espacio eliminado | Revisar configuración del Google Chat Webhook |
| Demasiadas alertas | Muchos campos pendientes o data sin limpiar | Revisar Banco de Propuestas y corregir datos |
| Output vacío | No hay pendientes o no hay filas válidas | Revisar que el banco tenga datos en columnas clave |
| Error por columna renombrada | Cambió el encabezado del Sheet | Actualizar `columnasAValidar` en el Code node |
| Duplicados en reporte | El flujo se ejecutó varias veces sin limpieza previa | Filtrar por fecha o limpiar duplicados manualmente si aplica |
---
## MONITOREO
* Revisar n8n Executions después de cada ejecución programada.
* Verde = flujo correcto.
* Rojo = fallo que requiere revisión.
* Revisar el Google Chat de alertas cada viernes.
* Revisar el Sheet `Fulgencio - Reporte de Pendientes`.
* Validar si el número de pendientes baja luego de correcciones.
* Si el flujo falla, revisar el workflow de error configurado en n8n.
* Mantener el export actualizado en Gitea.
### Output esperado normal
El flujo debe:
* Ejecutarse semanalmente.
* Leer correctamente el Banco de Propuestas.
* Enviar alerta solo si existen pendientes.
* Guardar detalle de pendientes cuando existan.
* Terminar sin errores.
* Mantener registro en n8n Executions.
---
## ESTRUCTURA DEL REPOSITORIO
```txt
/fulgencio-alertas-sheets-glm
|-- README.md
|-- fulgencio-alertas-sheets-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 Alertas Sheets - GLM`.
* Lectura del Banco de Propuestas.
* Detección de campos pendientes.
* Envío de alerta a Google Chat.
* Registro del detalle en `Fulgencio - Reporte de Pendientes`.
* Backup del workflow en Gitea.
* Documentación inicial del README.
---
## DECISIONS LOG
### DEC-001 — Usar revisión programada semanal
* **Fecha:** 2026-06
* **Contexto:** El Banco de Propuestas requiere revisión periódica de calidad de datos.
* **Opciones consideradas:** Revisión manual vs revisión automatizada.
* **Decisión:** Ejecutar revisión semanal automatizada.
* **Razón:** Reduce trabajo manual y mantiene visibilidad constante sobre pendientes.
### DEC-002 — No validar la columna APROBADA
* **Fecha:** 2026-06
* **Contexto:** La aprobación puede completarse manualmente después del registro inicial.
* **Opciones consideradas:** Validar `APROBADA` como obligatoria vs excluirla.
* **Decisión:** Excluir `APROBADA` de la validación.
* **Razón:** Evita alertas innecesarias sobre un campo que el equipo completa posteriormente.
### DEC-003 — Guardar detalle completo en Sheet separado
* **Fecha:** 2026-06
* **Contexto:** Una alerta de chat puede saturarse si contiene demasiados pendientes.
* **Opciones consideradas:** Enviar todo por chat vs guardar detalle en Sheet.
* **Decisión:** Enviar resumen por Chat y guardar detalle completo en Google Sheets.
* **Razón:** Mantiene el mensaje limpio y permite análisis posterior.
### DEC-004 — Mostrar solo filas prioritarias en el chat
* **Fecha:** 2026-06
* **Contexto:** Puede haber muchas filas con pendientes.
* **Decisión:** Mostrar hasta 40 filas prioritarias.
* **Razón:** Evita mensajes excesivamente largos y facilita revisión inicial.
---
## 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.
* [ ] Schedule semanal validado.
* [ ] Lectura del Banco de Propuestas validada.
* [ ] Validación de columnas correcta.
* [ ] Columna `APROBADA` excluida de la validación.
* [ ] Alerta de Google Chat probada.
* [ ] Registro en `Fulgencio - Reporte de Pendientes` probado.
* [ ] Casos de prueba básicos ejecutados.
* [ ] Errores visibles en n8n Executions.
* [ ] 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.
* Si se cambia el Google Sheet principal, actualizar el nodo `Sheets - Leer propuestas`.
* Si se cambia el Sheet de reporte, actualizar el nodo `Sheets - Guardar detalle pendientes`.
* Si se cambia el espacio de Google Chat, actualizar el nodo `HTTP Request - Enviar alerta`.
* Si se agregan nuevas columnas obligatorias al Banco de Propuestas, actualizar `columnasAValidar`.
* Si un encabezado del Sheet cambia, el flujo puede dejar de detectar correctamente ese campo.
---
Reference in New Issue View Git Blame Copy Permalink