Actualizar README.md

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.
+> 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_