# 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.

---