From 7e796b9dd590c5e0610b9a22f24f8a74a53f8c84 Mon Sep 17 00:00:00 2001 From: mgomez Date: Thu, 4 Jun 2026 19:45:34 +0000 Subject: [PATCH] Actualizar README.md --- README.md | 293 +++++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 291 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 320519f..3dcdca1 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,292 @@ -# bamboohr-agent +# BambooHR Agent -Agente conversacional que permite al equipo de RRHH consultar, modificar y reportar data de empleados en BambooHR mediante lenguaje natural, eliminando errores de nómina y reduciendo tiempo operativo \ No newline at end of file +> Agente conversacional que permite al equipo de RRHH consultar, modificar y reportar data de empleados en BambooHR mediante lenguaje natural, eliminando errores de nomina y reduciendo tiempo operativo. + +--- + +## Informacion General + +| Campo | Detalle | +|---|---| +| Proyecto | BambooHR Agent | +| Area | RRHH | +| Estado | En Progreso | +| Developer Principal | Isaac Aracena | +| IT Manager | Luis Matos | +| Fecha de Inicio | Junio 8, 2026 | +| Fecha de Cierre Estimada | Julio 19, 2026 | +| Ciclo Shape Up | Ciclo #1 — Semana 1 de 6 | +| Board de Ejecucion | [Link a Kan.bn — completar al crear el board] | +| PRD del Proyecto | [Link al PRD — completar al subir a Google Drive] | + +--- + +## Objetivo + +### Problema que resuelve +El equipo de RRHH (13-20 personas) gestiona toda la data de empleados entrando manualmente a BambooHR. Editar salarios, agregar empleados, desvincular, subir archivos, consultar informacion y generar reportes toma entre 5-15 minutos por operacion. Cuando hay multiples cambios pendientes, el equipo los pospone. Esos cambios olvidados llegan a nomina con datos incorrectos, generando errores que afectan al empleado, a RRHH y al area administrativa y de nomina. + +### Solucion implementada +Agente conversacional conectado a BambooHR via API que recibe instrucciones en lenguaje natural por chat y las ejecuta directamente. Opera en tres modos: accion (edita, agrega, desvincula, sube archivos), consulta (responde preguntas sobre data de empleados) y reporte (genera reportes estandar y personalizados). Cada operacion queda registrada en un log de auditoria. + +### Usuarios / Beneficiarios +- Operan el agente: Equipo de RRHH (13-20 personas) y equipo IT +- Acceso admin (settings de BambooHR): Solo Maximo Gomez +- Se benefician del output: Equipo administrativo, nomina y empleados GLM en 14 paises + +--- + +## Arquitectura + +### Diagrama de flujo + +``` +Usuario envia instruccion por chat + | + v +Agente valida identidad y permisos del usuario + | + v +Agente interpreta instruccion en lenguaje natural + | + +---> Modo accion --> Ejecuta cambio en BambooHR API + | + +---> Modo consulta --> Extrae data de BambooHR API --> Responde en chat + | + +---> Modo reporte --> Genera reporte estandar o personalizado --> Entrega en chat + | + v +Registro en log de auditoria (quien, que, cuando) + | + v +Confirmacion al usuario +``` + +### Stack tecnologico + +| Componente | Tecnologia | Proposito | +|---|---|---| +| Agente IA | Claude / Gemini | Interpretacion de lenguaje natural y ejecucion | +| Automatizacion | n8n / Python | Orquestacion del flujo | +| Interfaz de chat | A definir por Luis Matos (WhatsApp / Google Chat) | Canal de comunicacion con el agente | +| Autenticacion | A definir por IT | Validar identidad y permisos del usuario | +| Log de auditoria | A definir por IT (Supabase / Google Sheets) | Registro de cambios | +| Infraestructura | Google Cloud / Servidor Virtual | Hosting y ejecucion | + +### Integraciones externas + +| Sistema | Tipo de integracion | Datos que fluyen | +|---|---|---| +| BambooHR | API REST (full access) | Lectura, escritura y reportes de data de empleados | +| Google Workspace | OAuth | Autenticacion de usuarios GLM | +| WhatsApp / Google Chat | API | Instrucciones entrantes y respuestas salientes | +| Supabase / Google Sheets | API | Log de auditoria de cambios | + +--- + +## Configuracion y Setup + +### Prerequisitos + +- [ ] API key de BambooHR configurada (plan con full access confirmado) +- [ ] Canal de chat definido y configurado (WhatsApp o Google Chat — pendiente decision de Luis Matos) +- [ ] Sistema de autenticacion configurado (pendiente definicion de IT) +- [ ] Variable de entorno BAMBOOHR_API_KEY configurada +- [ ] Variable de entorno BAMBOOHR_SUBDOMAIN configurada +- [ ] Almacenamiento del log de auditoria configurado (pendiente Supabase o Google Sheets) + +### Variables de entorno + +| Variable | Descripcion | Donde se obtiene | +|---|---|---| +| BAMBOOHR_API_KEY | API Key de BambooHR | BambooHR -> Admin -> API Keys | +| BAMBOOHR_SUBDOMAIN | Subdominio de la cuenta GLM en BambooHR | URL de BambooHR (ej. glm.bamboohr.com) | +| CHAT_CHANNEL | Canal de chat activo (whatsapp / google_chat) | A definir por Luis Matos | +| AUTH_SECRET | Secret del sistema de autenticacion | A definir por IT | +| LOG_STORAGE_URL | URL del almacenamiento del log | Supabase o Google Sheets — a definir | +| ADMIN_USER_ID | ID del usuario con acceso a settings (Maximo Gomez) | A definir al configurar autenticacion | + +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/bamboohr-agent + +# Instalar dependencias +pip install -r requirements.txt + +# Configurar variables de entorno +cp .env.example .env +# Editar .env con las credenciales reales + +# Correr en local +python main.py +``` + +--- + +## Como funciona + +### Flujo paso a paso + +1. Trigger: El usuario envia un mensaje de texto al canal de chat definido (WhatsApp o Google Chat) +2. Autenticacion: El sistema valida la identidad del usuario y sus permisos antes de procesar la instruccion +3. Interpretacion: El agente (Claude o Gemini) analiza el mensaje y determina el modo de operacion — accion, consulta o reporte +4. Ejecucion: + - Modo accion: Llama a los endpoints correspondientes de BambooHR API para ejecutar el cambio. Si la accion es destructiva (ej. desvincular empleado), el agente pide confirmacion antes de ejecutar + - Modo consulta: Consulta BambooHR API, extrae la data solicitada y la formatea en lenguaje natural + - Modo reporte: Genera el reporte solicitado (estandar o personalizado) a partir de la data de BambooHR +5. Log: Cada operacion se registra automaticamente en el log de auditoria con usuario, accion, empleado afectado y timestamp +6. Confirmacion: El agente responde al usuario en el chat con el resultado de la operacion + +### Triggers + +| Trigger | Frecuencia | Descripcion | +|---|---|---| +| Mensaje entrante en canal de chat | On demand | Usuario envia instruccion o consulta en lenguaje natural | + +--- + +## Testing + +### Como probar el sistema + +```bash +# Test unitario +python -m pytest tests/ + +# Test de integracion con BambooHR API +python tests/integration_test.py + +# Test manual del agente +# Enviar mensaje de prueba al canal de chat configurado +``` + +### Casos de prueba minimos + +| Caso | Input | Output esperado | Estado | +|---|---|---|---| +| Editar salario | "Actualiza el salario de [empleado] a $X" | Confirmacion + cambio ejecutado en BambooHR | Pendiente | +| Agregar empleado | "Agrega nuevo empleado [datos]" | Confirmacion + empleado creado en BambooHR | Pendiente | +| Desvincular empleado | "Desvincula a [empleado] desde hoy" | Solicitud de confirmacion + ejecucion tras confirmar | Pendiente | +| Subir archivo | "Sube este contrato al perfil de [empleado]" | Archivo subido al perfil en BambooHR | Pendiente | +| Consulta de data | "Cuantos dias de vacaciones tiene [empleado]?" | Respuesta con dato correcto extraido de BambooHR | Pendiente | +| Reporte estandar | "Dame el headcount por pais" | Reporte generado y entregado en el chat | Pendiente | +| Reporte personalizado | "Lista empleados con salario no actualizado en 6 meses" | Reporte personalizado generado | Pendiente | +| Acceso a settings sin permiso | Usuario no-admin intenta modificar configuracion | Acceso denegado, sin ejecucion | Pendiente | +| Acceso a settings con permiso | Maximo Gomez modifica configuracion | Cambio ejecutado correctamente | Pendiente | +| Log de auditoria | Cualquier accion ejecutada | Entrada registrada en log con todos los campos | Pendiente | + +--- + +## Errores conocidos y troubleshooting + +| Error | Causa probable | Solucion | +|---|---|---| +| 401 Unauthorized en BambooHR | API Key vencida o incorrecta | Renovar key en BambooHR -> Admin -> API Keys y actualizar .env | +| Acceso denegado a settings | Usuario no tiene permisos de admin | Verificar ADMIN_USER_ID en variables de entorno | +| Agente no interpreta la instruccion | Instruccion muy ambigua o incompleta | El agente debe solicitar aclaracion al usuario antes de ejecutar | +| Log no registra la accion | Conexion con almacenamiento del log fallida | Verificar LOG_STORAGE_URL y credenciales de acceso | +| Canal de chat no recibe mensajes | Webhook no configurado correctamente | Revisar configuracion del canal en la plataforma correspondiente | + +--- + +## Monitoreo + +### Como saber si el sistema esta funcionando + +- Log de auditoria: Revisar que las acciones ejecutadas esten siendo registradas correctamente +- Canal de chat: Enviar un mensaje de prueba y verificar que el agente responda +- BambooHR: Verificar aleatoriamente que los cambios ejecutados por el agente se reflejen correctamente +- Alertas: A definir por IT — el sistema debe enviar alerta a Luis Matos si falla una ejecucion critica + +--- + +## Estructura del repositorio + +``` +/bamboohr-agent +├── README.md <- Este archivo +├── .env.example <- Variables de entorno de ejemplo (sin valores reales) +├── main.py <- Punto de entrada principal +├── /src +│ ├── agent.py <- Logica del agente — interpretacion de instrucciones +│ ├── bamboohr_client.py <- Integracion con BambooHR API +│ ├── auth.py <- Sistema de autenticacion y permisos +│ ├── audit_log.py <- Registro de auditoria +│ └── chat_interface.py <- Integracion con canal de chat +├── /tests +│ ├── test_agent.py <- Tests del agente +│ ├── test_bamboohr.py <- Tests de integracion con BambooHR API +│ └── integration_test.py <- Tests de integracion completos +├── /docs +│ └── architecture.png <- Diagrama de arquitectura (pendiente) +├── CHANGELOG.md <- Historial de cambios +└── DECISIONS.md <- Log de decisiones tecnicas +``` + +--- + +## CHANGELOG + +``` +[Junio 8, 2026] v0.1 — Inicio del ciclo. Repo creado. +``` + +--- + +## DECISIONS LOG + +### DEC-001 — Canal de chat (WhatsApp vs Google Chat) +- Fecha: Pendiente — Semana 1 +- Contexto: El agente necesita un canal de comunicacion. GLM opera en Google Workspace pero Maximo usa WhatsApp para operaciones similares +- Opciones consideradas: WhatsApp API vs Google Chat API +- Decision: A definir por Luis Matos en Semana 1 +- Razon: Pendiente + +### DEC-002 — Sistema de autenticacion +- Fecha: Pendiente — Semana 1 +- Contexto: Se necesita validar la identidad de cada usuario para aplicar permisos correctamente +- Opciones consideradas: Google OAuth vs sistema propio vs otro +- Decision: A definir por IT en Semana 1 +- Razon: Pendiente + +### DEC-003 — Almacenamiento del log de auditoria +- Fecha: Pendiente — Semana 1 +- Contexto: Cada accion ejecutada debe quedar registrada con usuario, accion, timestamp y resultado +- Opciones consideradas: Supabase / Postgres vs Google Sheets +- Decision: A definir por IT en Semana 1 +- Razon: Pendiente + +--- + +## Contactos del proyecto + +| Rol | Nombre | Contacto | +|---|---|---| +| Product Owner | Maximo Gomez | [completar] | +| IT Manager | Luis Matos | [completar] | +| Developer | Isaac Aracena | [completar] | + +--- + +## Definition of Done + +- [ ] Agente ejecuta los 3 modos: accion, consulta y reporte +- [ ] 95% de acciones ejecutadas correctamente en pruebas reales +- [ ] Tiempo por operacion menor a 30 segundos +- [ ] Sistema de permisos funcionando — settings bloqueados para no-admins +- [ ] Log de auditoria registrando todas las operaciones +- [ ] Todos los casos de prueba en estado OK +- [ ] Codigo commiteado y pusheado a Gitea +- [ ] README completo y actualizado +- [ ] Variables de entorno documentadas en .env.example +- [ ] Probado en ambiente real con equipo de RRHH +- [ ] Luis Matos valido el output +- [ ] Maximo aprobo el resultado final + +--- + +Documento mantenido por el equipo GLM IT - Ultima actualizacion: Junio 8, 2026 \ No newline at end of file