Actualizar README.md

2026-06-04 19:45:34 +00:00
parent abe60a37cc
commit 7e796b9dd5
1 changed files with 291 additions and 2 deletions
@@ -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
+> 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