glm-doc-assist/README.md

# DocAssist — Bot de generación de documentos de RRHH (n8n)

Bot de **Google Chat** que automatiza la generación, llenado y distribución de documentos de RRHH (visados, cartas de responsabilidad, constancias laborales, etc.) a partir de plantillas en **Google Drive**, usando datos de empleados almacenados en **Supabase** y **BambooHR**. Actualmente soporta **Guatemala, El Salvador y República Dominicana**.

## Resumen del flujo

1. Un usuario menciona al bot en un espacio de Google Chat (o le escribe en DM) pidiendo un documento.
2. El sistema identifica el país del solicitante y carga las plantillas correspondientes desde Drive.
3. Un agente de IA (Gemini 3.1 Pro) sigue un procedimiento de 9 pasos para: buscar la plantilla, obtener los datos del empleado, validar información faltante, reemplazar los datos en el documento, organizar los archivos en una carpeta nueva, pedir confirmación, convertir a PDF, compartir con RRHH y, opcionalmente, subir el resultado al perfil del empleado en BambooHR.

## Arquitectura / Nodos principales

### Entrada y preparación de contexto
| Nodo | Función |
|---|---|
| `Webhook` | Recibe el evento del bot de Google Chat (mención o DM). |
| `Obtener pais` | Busca en Supabase (`empleados_glm`) el país del empleado que envía el mensaje, por email. |
| `Limpiar` | Normaliza el payload del webhook en: usuario, mensaje, espacio, si fue DM, email y país. |

### Selección de plantillas por país
| Nodo | Función |
|---|---|
| `Switch` | Enruta según el país (Guatemala / El Salvador / República Dominicana). |
| `Archivos Guatemala` / `Archivos El Salvador` / `Archivos Republica Dominicana` | Listan los archivos de la carpeta de plantillas de Drive correspondiente a cada país. |
| `Limpiar lista archivos` | Normaliza la lista de archivos a `{id, name}`. |

### Validaciones previas
| Nodo | Función |
|---|---|
| `Mensaje en un espacio?` | Si el mensaje viene de un room (no DM), pasa a la siguiente validación; si es DM, va directo al agente. |
| `Mencion al bot?` | Verifica que exista mención al bot y texto en el mensaje antes de activar al agente. |

### Agente de IA
| Nodo | Función |
|---|---|
| `AI Agent` | Agente LangChain sobre **Gemini 3.1 Pro**, con memoria por usuario (`Simple Memory`). Ejecuta el procedimiento completo de generación de documentos (ver abajo). |
| `Google Gemini Chat Model` | Modelo de lenguaje usado por el agente. |
| `Simple Memory` | Memoria de conversación, indexada por usuario (`sessionKey`). |

### Herramientas del agente
| Nodo | Función |
|---|---|
| `Copiar archivo` | Duplica la plantilla de Drive en una carpeta temporal. |
| `Get many rows in Supabase` | Busca los datos del empleado por nombre. |
| `Extraer texto1` | Extrae el texto de un documento para identificar placeholders. |
| `Update a document in Google Docs` | Reemplaza los placeholders (`<<...>>`) por los datos reales. |
| `Buscar salario y salario variable del empleado` | Consulta la API de BambooHR (campos `4045`, `4626`, `payRate`) para obtener salario base y variable. |
| `Compartir archivos con RRHH` | Sub-workflow: crea la carpeta final, mueve los archivos, comparte con RRHH y (en la llamada final) convierte a PDF. |
| `Descargar archivo` | Sub-workflow: descarga el archivo editado y lo sube al perfil del empleado en BambooHR. |
| `Contestar1` | Envía mensajes al usuario en Google Chat durante la ejecución del agente. |

### Manejo de errores
| Nodo | Función |
|---|---|
| `Contestar` | Si el `AI Agent` falla, envía un mensaje genérico pidiendo reintentar o contactar a IT. |

## Procedimiento del agente (system prompt)

El agente sigue estrictamente estos pasos:

1. **Búsqueda y preparación de plantilla** — localiza la plantilla y extrae los placeholders.
2. **Obtención de datos** — busca al empleado en Supabase y su salario en BambooHR.
3. **Validación de información faltante** — si faltan datos, se detiene y los pide al usuario.
4. **Reemplazo y finalización** — llena los placeholders con formato correcto (números en letras/dígitos según el campo, fechas según tipo de documento).
5. **Creación de carpeta y notificación a RRHH** — organiza los archivos en una carpeta nueva y nombrada (máx. 4 palabras), y notifica a RRHH.
6. **Confirmación del usuario** — comparte los links de los archivos editados y espera aprobación o correcciones.
7. **Conversión a PDF y notificación final** — convierte los documentos y comparte la carpeta final con RRHH.
8. **Respuesta final** — confirma en Google Chat con el link de la carpeta, evitando términos técnicos, y pregunta si se debe subir a BambooHR.
9. **Subida a BambooHR** — si el usuario confirma, descarga y sube el archivo al perfil del empleado.

### Reglas especiales — Guatemala (visados)
- Si el usuario pide un visado, debe especificar si es **temporal** o **anual**, y a qué proyecto aplica (Walmart Connect u otro). Si no lo indica, el bot debe preguntarlo antes de continuar.
- **Visado temporal (Anexo 2 temporal):** se edita junto con la carta de responsabilidad y la declaración.
- **Visado anual (Anexo 2 anual):** se edita únicamente el Anexo 2 anual; no requiere carta de responsabilidad, declaración, ni fechas.

## Integraciones utilizadas
- **Google Chat** — interfaz conversacional (webhook + API de mensajes).
- **Google Drive** — almacenamiento y copia de plantillas.
- **Google Docs API** — extracción y reemplazo de texto en documentos.
- **Supabase** — base de datos de empleados (`empleados_glm`).
- **BambooHR API** — consulta de salarios y subida de documentos al perfil del empleado.
- **Google Gemini (3.1 Pro)** — modelo de lenguaje del agente.

## Notas de seguridad
> ⚠️ El export original de este workflow incluye un bloque `pinData` en el nodo `Webhook` con un JWT (`authorization` / `systemIdToken`) y datos personales reales (nombre, email) usados como ejemplo de payload de prueba. **Antes de compartir o versionar este JSON**, se recomienda eliminar o redactar ese `pinData`, ya que contiene credenciales y datos sensibles reutilizables.

## Alcance actual
- Países soportados: Guatemala, El Salvador, República Dominicana.
- Plataforma de destino final de los documentos: **BambooHR**.
- Canal de interacción: **Google Chat** (mención en un espacio o mensaje directo).