From 0179d5dade5f798dc7098e7e8a2ebb2301dedc47 Mon Sep 17 00:00:00 2001 From: mgomez Date: Sat, 6 Jun 2026 13:24:15 +0000 Subject: [PATCH] Actualizar README.md --- README.md | 343 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 341 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7422872..d5b2a67 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,342 @@ -# glm-doc-assist +# glm-docassist -Sistema conversacional que genera documentos laborales automáticamente a partir de una solicitud en lenguaje natural, extrayendo los datos del empleado desde BambooHR y aplicando el template correspondiente al país. \ No newline at end of file +> 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. + +--- + +## Informacion General + +| Campo | Detalle | +|---|---| +| **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] | + +--- + +## 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 | +|---|---| +| `{{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) | + +### Nombre de archivos de templates + +Convencion: `[Tipo_Documento]_[CODIGO_PAIS].docx` + +Ejemplos: +- `Carta_Constancia_Laboral_SV.docx` +- `Carta_Recomendacion_SV.docx` +- `Carta_Apertura_Banco_SV.docx` +- `Contrato_Trabajo_SV.docx` +- `Carta_Autorizacion_PDV_SV.docx` + +Los templates se almacenan en `/templates/{CODIGO_PAIS}/`. + +--- + +## Testing + +### Como probar el sistema + +```bash +# Tests unitarios +python -m pytest tests/ + +# Test de integracion completo (requiere credenciales reales) +python tests/integration_test.py + +# 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 +``` + +### 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