Files

T

mgomez 0179d5dade Actualizar README.md

2026-06-06 13:24:15 +00:00

15 KiB

Raw Permalink Blame History

glm-docassist

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

# 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

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".
Recepcion en n8n: El webhook de n8n captura el mensaje entrante e inicia el flujo.
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.
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.
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.
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.
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

# 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

15 KiB Raw Permalink Blame History