From ed1d34e52ca9e7d176a8f5ff813050d87f18c0d9 Mon Sep 17 00:00:00 2001 From: EidanThen Date: Fri, 11 Sep 2026 19:39:51 +0000 Subject: [PATCH] Actualizar README.md --- README.md | 396 ++++++++++-------------------------------------------- 1 file changed, 72 insertions(+), 324 deletions(-) diff --git a/README.md b/README.md index d5b2a67..e2b908e 100644 --- a/README.md +++ b/README.md @@ -1,342 +1,90 @@ -# glm-docassist +# DocAssist — Bot de generación de documentos de RRHH (n8n) -> Sistema conversacional que genera documentos laborales automaticamente a partir de una solicitud en lenguaje natural, extrayendo los datos del empleado desde BambooHR y aplicando el template correspondiente al pais. +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 -## Informacion General +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. -| Campo | Detalle | +## Arquitectura / Nodos principales + +### Entrada y preparación de contexto +| Nodo | Función | |---|---| -| **Proyecto** | GLM DocAssist — Asistente de Documentos RRHH | -| **Area** | RRHH | -| **Estado** | `En Progreso` | -| **Developer Principal** | Isaac Aracena | -| **IT Manager** | Luis Matos | -| **Fecha de Inicio** | 2026-07-01 | -| **Fecha de Cierre Estimada** | 2026-08-11 | -| **Ciclo Shape Up** | Ciclo 3 — Semana 1 de 6 | -| **Pais Piloto** | El Salvador | -| **Board de Ejecucion** | [Link a Kan.bn — completar al crear el board] | -| **PRD** | [Link al PRD en Gitea — completar] | +| `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. | ---- - -## Objetivo - -### Problema que resuelve - -El equipo de RRHH recibe solicitudes frecuentes de documentos laborales por parte de los empleados: cartas de constancia laboral, cartas de recomendacion, contratos de trabajo, cartas de apertura de cuenta bancaria, cartas de autorizacion para acceso a puntos de venta, ofertas de empleo, entre otros. Hoy cada documento se elabora de forma completamente manual: el coordinador busca el template, lo abre, completa los datos uno a uno y entrega el documento. Este proceso toma entre 20 y 60 minutos por documento, genera backlog en RRHH y deja al empleado sin respuesta a tiempo. - -### Solucion implementada - -El coordinador de RRHH envia una solicitud por WhatsApp o Gmail en lenguaje natural. El sistema interpreta la solicitud, identifica el tipo de documento y el empleado, consulta los datos del empleado en BambooHR, aplica el template correspondiente al pais y genera el documento `.docx` listo para entregar. El coordinador recibe el archivo en el mismo canal donde hizo la solicitud en menos de 2 minutos. - -### Usuarios / Beneficiarios - -- **Opera el sistema:** Coordinador de RRHH de El Salvador (piloto — 1 usuario). -- **Se beneficia del output:** Empleados de GLM en El Salvador que solicitan documentos laborales. - ---- - -## Arquitectura - -### Diagrama de flujo - -``` -[WhatsApp / Gmail] - | - v -[n8n: recepcion del mensaje entrante] - | - v -[IA — Claude / Gemini: interpretacion de solicitud] -[Extrae: tipo de documento + nombre del empleado] - | - v -[BambooHR API: consulta de datos del empleado] -[nombre, cargo, departamento, fecha ingreso, salario, jefe directo] - | - v -[Python: carga del template .docx del pais correspondiente] -[Sustitucion de variables {{campo}} con los datos del empleado] - | - v -[n8n: entrega del documento .docx generado al coordinador] -[via WhatsApp / Gmail — canal de origen de la solicitud] -``` - -### Stack tecnologico - -| Componente | Tecnologia | Proposito | -|---|---|---| -| Automatizacion | n8n | Orquestacion del flujo de solicitud y entrega | -| IA | Claude / Gemini | Interpretacion del mensaje, extraccion de intencion y datos | -| Generacion de documentos | Python (python-docx) | Llenado de templates y generacion del .docx final | -| Base de datos | Supabase / Postgres | Almacenamiento de templates por pais y log de documentos generados | -| Infraestructura | Google Cloud / Servidor Virtual | Hosting y ejecucion del sistema | - -### Integraciones externas - -| Sistema | Tipo de integracion | Datos que fluyen | -|---|---|---| -| BambooHR | API REST | Datos del empleado: nombre, cargo, fecha de ingreso, salario, jefe directo, departamento | -| WhatsApp | API / n8n | Canal de entrada para solicitudes del coordinador; canal de entrega del documento generado | -| Gmail | OAuth / MCP | Canal alternativo de entrada y entrega del documento generado | - ---- - -## Configuracion y Setup - -### Prerequisitos - -- [ ] Credenciales de BambooHR API configuradas (API Key + subdominio de la empresa) -- [ ] Webhook de n8n activo para recepcion de mensajes de WhatsApp -- [ ] Credenciales de Gmail OAuth configuradas en n8n -- [ ] Templates de documentos de El Salvador cargados en `/templates/SV/` -- [ ] Variables de entorno configuradas en `.env` (ver seccion siguiente) -- [ ] Conexion a Supabase configurada con tabla `document_log` y tabla `templates` - -### Variables de entorno - -| Variable | Descripcion | Donde se obtiene | -|---|---|---| -| `BAMBOOHR_API_KEY` | API Key de BambooHR | BambooHR → Perfil → API Keys | -| `BAMBOOHR_SUBDOMAIN` | Subdominio de la empresa en BambooHR | URL de BambooHR: `{subdomain}.bamboohr.com` | -| `N8N_WEBHOOK_URL` | URL del webhook de n8n para recepcion de solicitudes | n8n → Workflow → Webhook node | -| `SUPABASE_URL` | URL de conexion a Supabase | Supabase → Settings → API | -| `SUPABASE_KEY` | API Key de Supabase | Supabase → Settings → API | -| `CLAUDE_API_KEY` | API Key de Claude (Anthropic) | console.anthropic.com | -| `TEMPLATES_PATH` | Ruta local a la carpeta de templates | `/templates` (relativa al root del proyecto) | - -> NUNCA commitear credenciales al repo. Todas las keys van en el vault de credenciales GLM. - -### Instalacion / Deploy - -```bash -# Clonar el repo -git clone https://gitea.glm.com/glm-it/glm-docassist - -# Instalar dependencias -pip install -r requirements.txt - -# Configurar variables de entorno -cp .env.example .env -# Editar .env con las credenciales reales - -# Cargar templates de El Salvador en la carpeta correspondiente -# /templates/SV/Carta_Constancia_Laboral_SV.docx -# /templates/SV/Carta_Recomendacion_SV.docx -# (ver convencion de nombres en /docs/templates_guide.md) - -# Correr en local -python main.py -``` - ---- - -## Como funciona - -### Flujo paso a paso - -1. **Trigger:** El coordinador de RRHH envia un mensaje por WhatsApp o Gmail con la solicitud en lenguaje natural. Ejemplo: "necesito una carta de constancia laboral para Juan Perez". - -2. **Recepcion en n8n:** El webhook de n8n captura el mensaje entrante e inicia el flujo. - -3. **Interpretacion por IA:** Claude o Gemini analiza el mensaje y extrae dos datos clave: el tipo de documento solicitado y el nombre del empleado. Si el mensaje es ambiguo, el sistema responde con opciones para que el coordinador confirme. - -4. **Consulta a BambooHR:** El sistema llama a la API de BambooHR con el nombre del empleado, obtiene su ficha completa y mapea los campos necesarios para el template seleccionado. - -5. **Generacion del documento:** Python carga el template `.docx` correspondiente al tipo de documento y al pais (El Salvador en el piloto), sustituye las variables `{{campo}}` con los datos reales del empleado y genera el archivo final. - -6. **Entrega al coordinador:** n8n envia el archivo `.docx` generado al coordinador de RRHH por el mismo canal donde hizo la solicitud (WhatsApp o Gmail). El coordinador lo revisa y lo entrega al empleado. - -7. **Log:** El sistema registra cada documento generado en Supabase con fecha, tipo de documento, empleado y coordinador que lo solicito. - -### Triggers - -| Trigger | Frecuencia | Descripcion | -|---|---|---| -| Webhook POST WhatsApp | On demand | Solicitud entrante del coordinador via WhatsApp | -| Webhook POST Gmail | On demand | Solicitud entrante del coordinador via Gmail | - ---- - -## Convencion de templates - -Los templates son archivos `.docx` con variables marcadas con doble llave. El sistema sustituye cada variable con el dato correspondiente del empleado en BambooHR. - -### Variables estandar disponibles - -| Variable | Dato que inserta | +### Selección de plantillas por país +| Nodo | Función | |---|---| -| `{{nombre_empleado}}` | Nombre completo del empleado | -| `{{cargo}}` | Titulo del puesto | -| `{{departamento}}` | Departamento o area | -| `{{fecha_ingreso}}` | Fecha de inicio de la relacion laboral | -| `{{salario}}` | Salario actual | -| `{{jefe_directo}}` | Nombre del supervisor inmediato | -| `{{nombre_empresa}}` | Nombre legal de la empresa en ese pais | -| `{{fecha_documento}}` | Fecha de generacion del documento (automatica) | +| `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}`. | -### Nombre de archivos de templates +### 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. | -Convencion: `[Tipo_Documento]_[CODIGO_PAIS].docx` +### 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`). | -Ejemplos: -- `Carta_Constancia_Laboral_SV.docx` -- `Carta_Recomendacion_SV.docx` -- `Carta_Apertura_Banco_SV.docx` -- `Contrato_Trabajo_SV.docx` -- `Carta_Autorizacion_PDV_SV.docx` +### 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. | -Los templates se almacenan en `/templates/{CODIGO_PAIS}/`. +### 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) -## Testing +El agente sigue estrictamente estos pasos: -### Como probar el sistema +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. -```bash -# Tests unitarios -python -m pytest tests/ +### 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. -# Test de integracion completo (requiere credenciales reales) -python tests/integration_test.py +## 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. -# Test manual del flujo en n8n -# Abrir workflow en n8n → Click "Execute workflow" -# Usar el payload de prueba en /tests/payloads/test_constancia_laboral.json -``` +## 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. -### Casos de prueba minimos - -| Caso | Input | Output esperado | -|---|---|---| -| Solicitud clara, empleado existe | "carta de constancia laboral para Juan Perez" | Documento .docx generado y entregado sin errores | -| Solicitud ambigua | "necesito un documento para Maria Lopez" | Sistema responde con lista de tipos de documento disponibles | -| Empleado no encontrado en BambooHR | Nombre incorrecto o inexistente | Mensaje de error al coordinador: "No encontre empleado con ese nombre" | -| Campo faltante en BambooHR | Empleado sin salario registrado | Documento generado con campo vacio y alerta al coordinador | -| Tipo de documento no soportado | "necesito una carta de recomendacion personal" | Mensaje al coordinador indicando que ese tipo no esta disponible | -| Timeout de BambooHR | API no responde en 10s | Retry automatico x1; si falla, alerta al coordinador | - ---- - -## Errores conocidos y troubleshooting - -| Error | Causa probable | Solucion | -|---|---|---| -| `401 Unauthorized` en BambooHR | API Key vencida o incorrecta | Renovar key en BambooHR → Perfil → API Keys y actualizar `.env` | -| `Empleado no encontrado` | Nombre enviado no coincide exactamente con BambooHR | Verificar ortografia y nombre legal en BambooHR; considerar busqueda por ID | -| `Template no encontrado` | Archivo de template no esta en la ruta esperada | Verificar que el archivo existe en `/templates/SV/` con la convencion de nombre correcta | -| `Timeout en n8n` | BambooHR o Claude API lentos | Aumentar timeout en el node correspondiente → Settings → Timeout | -| Documento generado con campos vacios | Campo no disponible en BambooHR para ese empleado | Revisar ficha del empleado en BambooHR y completar los datos faltantes | -| Webhook no recibe mensajes | URL de webhook incorrecta o n8n caido | Verificar que n8n esta corriendo y que la URL del webhook en WhatsApp / Gmail esta actualizada | - ---- - -## Monitoreo - -### Como saber si el sistema esta funcionando - -- **n8n Executions:** Revisar logs en n8n → Executions diariamente. Cada solicitud debe aparecer como ejecucion exitosa. -- **Log en Supabase:** La tabla `document_log` debe registrar cada documento generado con `status = success`. -- **Output esperado:** Por cada solicitud valida del coordinador, debe generarse un archivo `.docx` y entregarse en menos de 2 minutos. -- **Alertas:** El sistema envia un mensaje al coordinador si ocurre un error durante la generacion. Errores criticos deben escalarse a Luis Matos. - ---- - -## Estructura del repositorio - -``` -/glm-docassist -├── README.md <- Este archivo -├── .env.example <- Variables de entorno de ejemplo (sin valores reales) -├── requirements.txt <- Dependencias Python -├── main.py <- Punto de entrada principal -├── /src -│ ├── bamboohr_client.py <- Cliente para la API de BambooHR -│ ├── document_generator.py <- Motor de llenado de templates .docx -│ ├── intent_parser.py <- Modulo de interpretacion de solicitudes via IA -│ └── document_log.py <- Registro de documentos generados en Supabase -├── /templates -│ └── /SV <- Templates de El Salvador -│ ├── Carta_Constancia_Laboral_SV.docx -│ ├── Carta_Recomendacion_SV.docx -│ └── [otros templates SV] -├── /n8n -│ └── workflow.json <- Export del workflow de n8n -├── /tests -│ ├── test_bamboohr.py <- Tests del cliente BambooHR -│ ├── test_document_generator.py <- Tests del motor de templates -│ ├── test_intent_parser.py <- Tests del modulo de IA -│ └── /payloads -│ └── test_constancia_laboral.json <- Payload de prueba -├── /docs -│ ├── architecture.png <- Diagrama de arquitectura -│ └── templates_guide.md <- Guia de convencion y entrega de templates -├── CHANGELOG.md <- Historial de cambios -└── DECISIONS.md <- Log de decisiones tecnicas -``` - ---- - -## CHANGELOG - -``` -[2026-07-01] v0.1 — Inicio del ciclo. Setup inicial del repositorio. -``` - ---- - -## DECISIONS LOG - -### DEC-001 — Convencion de variables en templates con doble llave - -- **Fecha:** 2026-07-01 -- **Contexto:** Se necesitaba una convencion estandar para marcar campos variables en los templates .docx que RRHH entrega y que el sistema debe sustituir. -- **Opciones consideradas:** Llaves simples `{campo}` vs doble llave `{{campo}}` vs marcadores especiales `[CAMPO]`. -- **Decision:** Doble llave `{{campo}}`. -- **Razon:** Es el estandar de python-docx y la mayoria de motores de templates. Reduce la probabilidad de colisiones con texto normal del documento y es familiar para el equipo tecnico. - -### DEC-002 — Piloto en El Salvador antes de expansion a otros paises - -- **Fecha:** 2026-07-01 -- **Contexto:** El sistema debe eventualmente soportar los 14 paises de GLM, pero cada pais tiene templates y datos diferentes. -- **Opciones consideradas:** Desarrollar soporte multi-pais desde el inicio vs piloto en un pais y expansion incremental. -- **Decision:** Piloto en El Salvador, expansion en ciclos futuros. -- **Razon:** Reduce el riesgo del primer ciclo, permite validar el motor de templates y la integracion con BambooHR con un scope controlado antes de escalar. - ---- - -## Contactos del proyecto - -| Rol | Nombre | Contacto | -|---|---|---| -| Product Owner | Maximo Gomez | [email/WhatsApp] | -| IT Manager | Luis Matos | [email/WhatsApp] | -| Developer Principal | Isaac Aracena | [email/WhatsApp] | - ---- - -## Definition of Done - -Checklist antes de mover a **Completado** en Kan.bn: - -- [ ] Los 3 tipos de documentos del piloto generados sin errores en ambiente real -- [ ] Tiempo de entrega del documento menor a 2 minutos desde la solicitud -- [ ] Codigo commiteado y pusheado a Gitea -- [ ] README completo y actualizado -- [ ] Variables de entorno documentadas en `.env.example` -- [ ] Tests basicos pasando -- [ ] Workflow de n8n exportado en `/n8n/workflow.json` -- [ ] CHANGELOG actualizado con la version -- [ ] Probado en ambiente real (no solo local) -- [ ] Coordinador de RRHH El Salvador valido el output -- [ ] Luis Matos valido el output tecnico -- [ ] Maximo aprobo el resultado final - ---- - -_Documento mantenido por el equipo GLM IT · Ultima actualizacion: 2026-07-01_ \ No newline at end of file +## 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). \ No newline at end of file