Actualizar README.md

README.md

@@ -1,3 +1,408 @@
-# calendario-glm-way
+# Automatizacion GLM Way
 
-Sistema que detecta nuevos ingresos en BambooHR, los inscribe automáticamente en la sesión del GLM Way segun su idioma, les envia el link del Meet el primer dia de trabajo, les recuerda 24 horas antes, avisa al coordinador de RRHH del país 48 horas antes con la lista de inscritos, y recolecta la evaluación post-sesión.
+> **Sistema que detecta nuevos ingresos en BambooHR, los inscribe automaticamente en la sesion del GLM Way segun su idioma, los notifica el primer dia de trabajo, avisa al coordinador de RRHH 48 horas antes con la lista de inscritos, envia recordatorio 24 horas antes, y recolecta la evaluacion post-sesion.**
+
+---
+
+## Informacion General
+
+| Campo | Detalle |
+|---|---|
+| Proyecto | Automatizacion GLM Way |
+| Area | RRHH |
+| Estado | En Progreso |
+| Developer Principal | Eidan Then |
+| IT Manager | Luis Matos |
+| Fecha de Inicio | 2026-06-09 |
+| Fecha de Cierre Estimada | 2026-07-21 |
+| Ciclo Shape Up | Ciclo #N — Semana 1 de 6 |
+| Board de Ejecucion | [Link a Kan.bn — completar al crear el board] |
+| PRD del Proyecto | [Link al PRD en Gitea — completar al subir el PRD] |
+
+---
+
+## Objetivo
+
+### Problema que resuelve
+
+El GLM Way es una induccion obligatoria para todos los nuevos ingresos de GLM a nivel regional. El proceso de inscripcion y notificacion es completamente manual: el coordinador de RRHH debe identificar a los nuevos ingresos en BambooHR, determinar a que sesion corresponde cada uno segun su idioma, enviarles el link del Google Meet, y luego recolectar las evaluaciones post-sesion. No existe ningun sistema de recordatorio ni seguimiento. Como resultado, nuevos ingresos no reciben la induccion porque el coordinador olvida notificarlos, y GLM no tiene visibilidad confiable de quien asistio y quien no.
+
+### Solucion implementada
+
+El sistema corre automaticamente en n8n sobre el servidor virtual GLM. Consulta BambooHR para detectar nuevos ingresos, determina su idioma por pais, identifica la proxima sesion en el calendario GLM Way (Google Sheets), y gestiona toda la cadena de comunicacion: notificacion el D1, aviso al coordinador 48hrs antes, recordatorio al empleado 24hrs antes, formulario de evaluacion post-sesion, y registro de asistencia en Supabase cruzando los attendees del Google Meet con los inscritos.
+
+### Usuarios / Beneficiarios
+
+- Nuevos ingresos de los 14 paises GLM — reciben notificaciones automaticas sin depender de un proceso manual.
+- Coordinadores de RRHH por pais — reciben un aviso proactivo 48hrs antes con la lista de quienes deben conectarse.
+- Luis Matos y Maximo Gomez — tienen visibilidad del programa en Supabase sin necesidad de seguimiento manual.
+
+---
+
+## Arquitectura
+
+### Diagrama de flujo
+
+```
+[BambooHR — nuevo ingreso detectado (hire_date = hoy)]
+        |
+        v
+[Identificar idioma por pais]
+        |
+        +---> [Espanol] ---> [Google Sheets: proxima sesion ES → fecha + link Meet]
+        |
+        +---> [Ingles]  ---> [Google Sheets: proxima sesion EN → fecha + link Meet]
+        |
+        v
+[D1: Email al nuevo ingreso con fecha, hora y link de su sesion]
+        |
+        v
+[48hrs antes: Email al Coordinador de RRHH del pais con lista de inscritos]
+        |
+        v
+[24hrs antes: Email de recordatorio al nuevo ingreso]
+        |
+        v
+[Post-sesion (dentro de 1hr): Email con link del formulario de evaluacion ES / EN]
+        |
+        v
+[Google Calendar API: extraer attendees del Meet → cruzar vs inscritos → registrar asistencia en Supabase]
+```
+
+### Stack tecnologico
+
+| Componente | Tecnologia | Proposito |
+|---|---|---|
+| Automatizacion | n8n | Orquestacion de todos los flujos y schedulers |
+| Base de datos | Supabase / Postgres | Registro de inscritos, asistencia y evaluaciones |
+| RRHH | BambooHR API | Fuente de nuevos ingresos y datos del empleado |
+| Calendario | Google Sheets API | Lectura del calendario de sesiones y links de Meet |
+| Notificaciones | Gmail OAuth | Envio de emails a empleados y coordinadores |
+| Asistencia | Google Calendar API | Extraccion de attendees post-sesion |
+| Infraestructura | Servidor Virtual GLM | Hosting de n8n |
+
+### Integraciones externas
+
+| Sistema | Tipo de integracion | Datos que fluyen |
+|---|---|---|
+| BambooHR | API REST | Nuevos ingresos: nombre, email, pais, cargo, hire_date. Coordinadores: nombre, email, pais, posicion |
+| Google Sheets | API | Calendario GLM Way: fecha, facilitador, link Meet por idioma (ES / EN) |
+| Gmail | OAuth | Emails salientes: notificacion D1, aviso coordinador, recordatorio 24hrs, formulario evaluacion |
+| Google Calendar | API | Attendees del evento Meet post-sesion |
+| Supabase | Postgres directo | Tablas: inscritos_glmway, sesiones_glmway, asistencia_glmway |
+
+---
+
+## Reglas de negocio
+
+### Logica de idioma por pais
+
+| Idioma | Paises |
+|---|---|
+| Ingles | Jamaica, Trinidad and Tobago, Guyana, St. Croix, Aruba, St. Thomas |
+| Espanol | Todos los demas paises GLM |
+
+### Logica de inscripcion
+
+- Rango de deteccion: empleados con hire_date entre la ultima sesion realizada y la proxima sesion programada.
+- Si hay multiples nuevos ingresos en la misma semana, todos van a la misma sesion proxima segun su idioma.
+- El sistema consulta el Google Sheet en tiempo real al momento del envio — nunca almacena el link con anticipacion.
+
+### Logica del coordinador de RRHH
+
+- El sistema busca en BambooHR empleados con Posicion = "Coordinador de RRHH" y Pais = pais del nuevo ingreso.
+- Si hay multiples coordinadores en un pais, el aviso se envia a todos.
+- Si no existe coordinador registrado para ese pais, se registra la excepcion en Supabase y se notifica a Luis Matos.
+
+### Timing de notificaciones
+
+| Notificacion | Destinatario | Cuando se envia |
+|---|---|---|
+| Notificacion inicial | Nuevo ingreso | hire_date = fecha actual (D1) |
+| Aviso con lista de inscritos | Coordinador de RRHH del pais | 48 horas antes de la sesion |
+| Recordatorio | Nuevo ingreso | 24 horas antes de la sesion |
+| Formulario de evaluacion | Nuevo ingreso | Dentro de la hora siguiente al fin de la sesion |
+
+---
+
+## Configuracion y Setup
+
+### Prerequisitos
+
+- [ ] Acceso a BambooHR API — API Key generada en BambooHR → Account → API Keys
+- [ ] Google Cloud project con Google Sheets API y Google Calendar API habilitadas
+- [ ] Gmail OAuth configurado en n8n con cuenta de envio GLM
+- [ ] Supabase project creado con las tres tablas del esquema (ver seccion de base de datos)
+- [ ] Google Sheet del calendario GLM Way accesible con la cuenta de servicio configurada
+- [ ] n8n corriendo en el servidor virtual GLM con conectividad a todos los servicios externos
+- [ ] Credenciales almacenadas en el vault de credenciales GLM — nunca en el repo
+
+### Variables de entorno
+
+| Variable | Descripcion | Donde se obtiene |
+|---|---|---|
+| `BAMBOOHR_API_KEY` | API Key de BambooHR | BambooHR → Account → API Keys |
+| `BAMBOOHR_SUBDOMAIN` | Subdominio de la cuenta GLM en BambooHR | URL de BambooHR: `subdomain.bamboohr.com` |
+| `GOOGLE_SERVICE_ACCOUNT_JSON` | Credenciales de la cuenta de servicio de Google Cloud | Google Cloud Console → IAM → Service Accounts |
+| `GOOGLE_CALENDAR_ID_ES` | ID del Google Calendar de la sesion GLM Way en espanol | Google Calendar → Configuracion del evento |
+| `GOOGLE_CALENDAR_ID_EN` | ID del Google Calendar de la sesion GLM Way en ingles | Google Calendar → Configuracion del evento |
+| `GLMWAY_SHEET_ID` | ID del Google Sheet del calendario de sesiones | URL del Sheet: `docs.google.com/spreadsheets/d/{ID}` |
+| `GMAIL_SENDER` | Cuenta de Gmail autorizada para envio | Definida en la configuracion OAuth de n8n |
+| `FORM_URL_ES` | Link del formulario de evaluacion en espanol | Google Forms — obtener link de respuesta |
+| `FORM_URL_EN` | Link del formulario de evaluacion en ingles | Google Forms — obtener link de respuesta |
+| `SUPABASE_URL` | URL del proyecto Supabase | Supabase → Settings → API |
+| `SUPABASE_KEY` | API Key de Supabase (service role) | Supabase → Settings → API |
+| `ALERT_EMAIL_LUIS` | Email de Luis Matos para alertas de sistema | — |
+
+> NUNCA commitear credenciales al repo. Todas las keys van en el vault de credenciales GLM.
+
+### Esquema de base de datos
+
+```sql
+-- Tabla de inscritos por sesion
+CREATE TABLE inscritos_glmway (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    empleado_id     TEXT NOT NULL,
+    nombre          TEXT NOT NULL,
+    email           TEXT NOT NULL,
+    pais            TEXT NOT NULL,
+    idioma          TEXT NOT NULL CHECK (idioma IN ('ES', 'EN')),
+    cargo           TEXT,
+    hire_date       DATE NOT NULL,
+    sesion_id       UUID REFERENCES sesiones_glmway(id),
+    sesion_fecha    DATE,
+    sesion_link     TEXT,
+    estado          TEXT DEFAULT 'notificado',
+    created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Tabla de sesiones GLM Way
+CREATE TABLE sesiones_glmway (
+    id              UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    fecha           DATE NOT NULL,
+    idioma          TEXT NOT NULL CHECK (idioma IN ('ES', 'EN')),
+    facilitador     TEXT,
+    meet_link       TEXT,
+    created_at      TIMESTAMPTZ DEFAULT NOW()
+);
+
+-- Tabla de asistencia
+CREATE TABLE asistencia_glmway (
+    id                      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    empleado_id             TEXT NOT NULL,
+    sesion_id               UUID REFERENCES sesiones_glmway(id),
+    asistio                 BOOLEAN DEFAULT FALSE,
+    evaluacion_completada   BOOLEAN DEFAULT FALSE,
+    registrado_at           TIMESTAMPTZ DEFAULT NOW()
+);
+```
+
+### Instalacion / Deploy
+
+```bash
+# Clonar el repo
+git clone https://gitea.glm.com/glm-it/automatizacion-glm-way
+
+# Configurar variables de entorno
+cp .env.example .env
+# Editar .env con las credenciales reales del vault GLM
+
+# Importar el workflow en n8n
+# n8n → Settings → Import workflow → seleccionar /n8n/workflow.json
+
+# Ejecutar el setup inicial de Supabase
+psql $SUPABASE_URL -f /src/db/schema.sql
+```
+
+---
+
+## Como funciona
+
+### Flujo paso a paso
+
+1. **Trigger deteccion de nuevos ingresos (diario, 7am):** n8n corre un scheduler diario que consulta BambooHR buscando empleados con hire_date = fecha actual. Por cada nuevo ingreso extrae: nombre, email, pais, cargo. Clasifica el idioma segun el pais y consulta Google Sheets para obtener la proxima sesion GLM Way correspondiente.
+
+2. **Notificacion D1:** El sistema envia un email al nuevo ingreso via Gmail con su nombre, la fecha y hora de su proxima sesion GLM Way, el nombre del facilitador y el link del Google Meet. Registra al empleado en la tabla inscritos_glmway con estado "notificado".
+
+3. **Aviso al coordinador de RRHH (48hrs antes, scheduler diario 8am):** n8n detecta sesiones que ocurren en 48 horas, consulta en Supabase los inscritos de esa sesion por pais, identifica al coordinador de RRHH de cada pais en BambooHR y envia un email con la lista de inscritos (nombre, cargo, fecha de inicio) y el link del Meet.
+
+4. **Recordatorio al nuevo ingreso (24hrs antes, scheduler diario 8am):** n8n detecta sesiones que ocurren en 24 horas y envia un email de recordatorio a cada inscrito con estado "notificado" o "recordado". Actualiza el estado a "recordado".
+
+5. **Envio de formulario post-sesion (scheduler cada hora):** n8n detecta sesiones que terminaron en la ultima hora y envia el formulario de evaluacion correspondiente (ES o EN) a cada inscrito. Actualiza el estado a "evaluacion_enviada".
+
+6. **Registro de asistencia:** n8n consulta Google Calendar API para obtener la lista de attendees del evento Meet de la sesion. Cruza esa lista contra los inscritos en Supabase y registra en asistencia_glmway: asistio = true/false por empleado.
+
+### Schedules / Triggers
+
+| Trigger | Frecuencia | Descripcion |
+|---|---|---|
+| Deteccion nuevos ingresos D1 | Cron diario 7am | Consulta BambooHR por hire_date = hoy y envia notificacion inicial |
+| Aviso coordinador RRHH | Cron diario 8am | Detecta sesiones en 48hrs y notifica al coordinador con lista de inscritos |
+| Recordatorio empleado | Cron diario 8am | Detecta sesiones en 24hrs y envia recordatorio a los inscritos |
+| Envio de evaluacion | Cron cada hora | Detecta sesiones terminadas en la ultima hora y envia formulario |
+| Registro de asistencia | Cron cada hora | Extrae attendees del Meet y cruza con inscritos en Supabase |
+
+---
+
+## Testing
+
+### Como probar el sistema
+
+```bash
+# Test manual en n8n — flujo completo
+# 1. Crear empleado de prueba en BambooHR con hire_date = manana
+# 2. Abrir n8n → workflow Deteccion D1 → Execute workflow
+# 3. Verificar que llega el email al empleado de prueba
+# 4. Verificar registro en Supabase: SELECT * FROM inscritos_glmway WHERE email = 'test@glm.com'
+
+# Test del aviso al coordinador
+# 1. Ajustar manualmente la fecha de una sesion en Supabase a 48hrs desde ahora
+# 2. Ejecutar manualmente el workflow de aviso coordinador en n8n
+# 3. Verificar que el coordinador del pais recibe el email con la lista correcta
+
+# Test del registro de asistencia
+# 1. Ejecutar manualmente el workflow post-sesion con el ID de una sesion real
+# 2. Verificar en Supabase: SELECT * FROM asistencia_glmway WHERE sesion_id = '{id}'
+```
+
+### Casos de prueba minimos
+
+| Caso | Input | Output esperado | Estado |
+|---|---|---|---|
+| Nuevo ingreso pais hispanohablante | hire_date = hoy, pais = Colombia | Email en espanol con proxima sesion ES | A completar por Eidan |
+| Nuevo ingreso pais anglohablante | hire_date = hoy, pais = Jamaica | Email en ingles con proxima sesion EN | A completar por Eidan |
+| Aviso coordinador — pais con inscritos | Sesion en 48hrs, 2 inscritos en Supabase | Email al coordinador con lista de 2 personas | A completar por Eidan |
+| Aviso coordinador — pais sin coordinador | Sesion en 48hrs, no hay coordinador en BambooHR | Excepcion registrada en Supabase + alerta a Luis Matos | A completar por Eidan |
+| Recordatorio 24hrs | Sesion en 24hrs, inscrito con estado "notificado" | Email de recordatorio + estado actualizado a "recordado" | A completar por Eidan |
+| Formulario post-sesion | Sesion terminada hace 30 min | Email con formulario correcto segun idioma | A completar por Eidan |
+| BambooHR sin nuevos ingresos del dia | hire_date = hoy, 0 resultados | Flujo termina sin error, sin emails enviados | A completar por Eidan |
+| Google Meet sin attendees | API retorna lista vacia | Excepcion registrada, alerta a Luis Matos | A completar por Eidan |
+
+---
+
+## Errores conocidos y troubleshooting
+
+| Error | Causa probable | Solucion |
+|---|---|---|
+| `401 Unauthorized` en BambooHR | API Key vencida o incorrecta | Renovar key en BambooHR → Account → API Keys y actualizar `.env` |
+| `403 Forbidden` en Google Sheets | Cuenta de servicio sin permisos sobre el Sheet | Compartir el Google Sheet con el email de la cuenta de servicio |
+| Email no llega al empleado | Gmail OAuth expirado o cuenta bloqueada | Reautenticar Gmail en n8n → Credentials |
+| Lista de attendees vacia | Google Calendar API no retorna participantes del Meet | Verificar que el evento tiene el Meet integrado y que la cuenta de servicio tiene acceso al calendario |
+| Coordinador no encontrado para un pais | El campo Posicion en BambooHR no coincide exactamente con "Coordinador de RRHH" | Revisar el valor exacto del campo en BambooHR y ajustar el filtro en n8n |
+| Timeout en n8n | Servicio externo lento (BambooHR o Google) | Aumentar el timeout del nodo en n8n → Settings → Timeout |
+
+> Seccion a completar por Eidan con errores adicionales encontrados durante el desarrollo.
+
+---
+
+## Monitoreo
+
+### Como saber si el sistema esta funcionando
+
+- **n8n Executions:** Revisar n8n → Executions diariamente. Todos los workflows deben aparecer en verde. Un workflow en rojo indica fallo.
+- **Alertas automaticas:** El sistema envia un email a Luis Matos cuando un flujo falla sin recuperarse o cuando detecta una excepcion critica (coordinador no encontrado, Meet sin attendees).
+- **Output esperado en condiciones normales:** Cada semana deben aparecer registros nuevos en inscritos_glmway y asistencia_glmway en Supabase correspondientes a la sesion de esa semana.
+- **Verificacion rapida en Supabase:**
+
+```sql
+-- Ver inscritos de la semana actual
+SELECT * FROM inscritos_glmway
+WHERE created_at >= date_trunc('week', NOW());
+
+-- Ver asistencia de la ultima sesion
+SELECT i.nombre, i.idioma, a.asistio, a.evaluacion_completada
+FROM asistencia_glmway a
+JOIN inscritos_glmway i ON a.empleado_id = i.empleado_id
+ORDER BY a.registrado_at DESC
+LIMIT 20;
+```
+
+---
+
+## Estructura del repositorio
+
+```
+/automatizacion-glm-way
+├── README.md                   <- Este archivo
+├── .env.example                <- Variables de entorno de ejemplo (sin valores reales)
+├── /n8n
+│   └── workflow.json           <- Export del workflow completo de n8n
+├── /src
+│   └── /db
+│       └── schema.sql          <- Script de creacion de tablas en Supabase
+├── /docs
+│   └── architecture.png        <- Diagrama de arquitectura (agregar al cerrar el ciclo)
+├── CHANGELOG.md                <- Historial de cambios (completar durante el ciclo)
+└── DECISIONS.md                <- Log de decisiones tecnicas (completar durante el ciclo)
+```
+
+---
+
+## CHANGELOG
+
+Formato: [YYYY-MM-DD] vX.X — Descripcion del cambio
+
+```
+[2026-06-09] v0.1 — Inicio del ciclo. Setup del repo y esquema de base de datos.
+```
+
+> Completar durante el ciclo con cada version funcional.
+
+---
+
+## DECISIONS LOG
+
+### DEC-001 — Clasificacion de idioma por pais y no por campo de empleado
+
+- Fecha: 2026-06-04
+- Contexto: Necesitabamos determinar si un empleado va a la sesion en espanol o en ingles para inscribirlo correctamente.
+- Opciones consideradas: (A) Usar un campo de idioma en el perfil de BambooHR. (B) Inferir el idioma a partir del pais del empleado.
+- Decision: Opcion B — inferir por pais.
+- Razon: BambooHR no tiene un campo de idioma estandarizado en los perfiles GLM. El pais es un campo confiable y ya disponible. Paises en ingles definidos: Jamaica, Trinidad and Tobago, Guyana, St. Croix, Aruba, St. Thomas.
+
+### DEC-002 — Lectura del link de Meet desde Google Sheets en tiempo real
+
+- Fecha: 2026-06-04
+- Contexto: Necesitabamos decidir si almacenar el link del Google Meet en Supabase con anticipacion o consultarlo en el momento del envio.
+- Opciones consideradas: (A) Pre-cargar el link en Supabase al crear el inscrito. (B) Consultar el Google Sheet en tiempo real al momento de cada envio.
+- Decision: Opcion B — consulta en tiempo real.
+- Razon: Los links de Google Meet pueden cambiar o actualizarse en el Sheet. Consultar en tiempo real garantiza que siempre se envia el link correcto y evita datos desactualizados en Supabase.
+
+> Agregar nuevas decisiones durante el ciclo con el formato DEC-00N.
+
+---
+
+## Contactos del proyecto
+
+| Rol | Nombre | Contacto |
+|---|---|---|
+| Product Owner | Maximo Gomez | [completar] |
+| IT Manager | Luis Matos | [completar] |
+| Developer | Eidan Then | [completar] |
+
+---
+
+## Definition of Done
+
+Checklist antes de mover a Completado en Kan.bn:
+
+- [ ] Todos los criterios de exito del PRD cumplidos y verificados
+- [ ] 100% de nuevos ingresos de prueba notificados sin intervencion manual
+- [ ] Coordinadores de RRHH notificados 48hrs antes con lista de inscritos correcta
+- [ ] Recordatorios enviados correctamente en pruebas de los dos idiomas
+- [ ] Registro de asistencia generado en Supabase para al menos una sesion real
+- [ ] Formularios de evaluacion enviados automaticamente post-sesion
+- [ ] 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`
+- [ ] Schema SQL en `/src/db/schema.sql`
+- [ ] CHANGELOG actualizado con la version final
+- [ ] Probado en ambiente real (no solo local)
+- [ ] Luis Matos valido el output
+- [ ] Maximo aprobo el resultado final
+
+---
+
+_Documento mantenido por el equipo GLM IT · Ultima actualizacion: 2026-06-04_