From 998bb6a1af000950511b4ef3e6649676914d40f9 Mon Sep 17 00:00:00 2001 From: Isaac_Aracena Date: Thu, 25 Jun 2026 01:47:32 +0000 Subject: [PATCH] Actualizar README.md --- README.md | 482 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 480 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6b5090f..7459c5a 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,481 @@ -# fulgencio-alertas-sheets-glm +# Fulgencio Alertas Sheets - GLM -Backup público automático del workflow n8n: Fulgencio Alertas Sheets - GLM \ No newline at end of file +> 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 | +| Infraestructura | EasyPanel / Servidor GLM | Hosting de n8n | +| 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. + +--- \ No newline at end of file