diff --git a/README_cruce-cuentas-glm-centralizado.md b/README_cruce-cuentas-glm-centralizado.md new file mode 100644 index 0000000..0eb24dd --- /dev/null +++ b/README_cruce-cuentas-glm-centralizado.md @@ -0,0 +1,583 @@ +# Cruce de Cuentas GLM - Centralizado + +> Aplicación centralizada para automatizar y gestionar el cruce de cuentas de nómina contra archivos bancarios, validando empleados con BambooHR, generando reportes en Google Sheets y dejando una arquitectura preparada para incorporar progresivamente los demás países de GomezLee Marketing. + +--- + +## INFORMACIÓN GENERAL + +| Campo | Detalle | +|---|---| +| Proyecto | Cruce de Cuentas GLM - Centralizado | +| Área | Administración / Recursos Humanos | +| Estado | En progreso - Guatemala y Trinidad y Tobago completados | +| Developer Principal | Isaac Aracena | +| IT Manager | Luis Matos | +| Fecha de Inicio | Pendiente de documentar | +| Fecha de Cierre Estimada | Proyecto evolutivo / expansión por países | +| Ciclo Shape Up | Pendiente de documentar | +| Board de Ejecución | Pendiente de documentar | +| PRD del Proyecto | Pendiente de documentar | +| Producción | `https://digitalcompass.agency/cruce-cuentas/` | +| Repositorio | `https://git.digitalcompass.agency/Isaac_Aracena/cruce-cuentas-glm-centralizado` | + +--- + +## OBJETIVO + +### Problema que resuelve + +El proceso de validar que los pagos enviados al banco coincidan correctamente con la nómina requiere comparar archivos con estructuras diferentes, revisar cuentas bancarias, nombres, montos y empleados, y confirmar manualmente si una persona existe o no en BambooHR. + +Este trabajo manual consume tiempo, aumenta el riesgo de errores y hace más difícil identificar rápidamente diferencias reales de pago, cuentas mal digitadas, empleados pagados que no aparecen en la nómina o registros bancarios que no corresponden a empleados válidos. + +### Solución implementada + +Cruce de Cuentas GLM centraliza este proceso en una aplicación web. + +El usuario selecciona el país y período, carga la nómina y los archivos bancarios correspondientes, y el sistema procesa la información automáticamente mediante workflows de n8n. + +El resultado incluye: + +- Comparación de cuentas bancarias. +- Comparación de montos pagados contra nómina. +- Identificación de coincidencias. +- Identificación de discrepancias reales. +- Detección de posibles cuentas bancarias mal digitadas. +- Validación de empleados contra BambooHR. +- Identificación de pagos bancarios que no corresponden a empleados localizados en BambooHR. +- Detección de diferencias de nombres en los archivos bancarios. +- Generación automática de un Google Sheet estructurado. +- Historial de reportes y seguimiento de resolución desde la aplicación. +- Formato automático del reporte para evitar ajustes manuales de columnas y filas. + +La solución comenzó con Guatemala y Trinidad y Tobago y está diseñada para agregar progresivamente los demás países de GomezLee Marketing sin crear aplicaciones independientes. + +### Usuarios / Beneficiarios + +- Equipos administrativos responsables de validar pagos y nóminas. +- Recursos Humanos. +- Personal autorizado para consultar históricos y dar seguimiento a discrepancias. +- IT, para soporte, mantenimiento y expansión del sistema a nuevos países. + +--- + +## ARQUITECTURA + +### Diagrama de flujo + +```text +[Usuario] + | + v +[App Web React / Vite] + | + +----> [Supabase Auth + Control de acceso] + | + v +[Selección de país + período + archivos] + | + v +[Webhook n8n del país] + | + +----> [Parseo de nómina] + | + +----> [Parseo de archivos bancarios] + | + +----> [BambooHR Custom Report - onlyCurrent=false] + | + v +[Normalización + Conciliación + Validaciones] + | + v +[Clasificación de resultados] + | + +----> Coincidencias + +----> Discrepancias + +----> Banco sin Bamboo + +----> Diferencias de Nombre + +----> Posibles cuentas mal digitadas + +----> Resumen + | + v +[Google Sheets] + | + +----> [Histórico / seguimiento en Supabase] + | + v +[Resultado mostrado en la aplicación] +``` + +### Stack tecnológico + +| Componente | Tecnología | Propósito | +|---|---|---| +| Frontend | React + TypeScript + Vite | Aplicación web centralizada | +| Automatización | n8n | Orquestación de cruces y generación de reportes | +| Base de datos / Auth | Supabase / PostgreSQL | Autenticación, permisos e información persistente | +| RRHH | BambooHR API | Validación de empleados activos e inactivos | +| Reportes | Google Sheets API | Generación y formato de reportes | +| Repositorio | Gitea | Control de versiones | +| Hosting frontend | Servidor DigitalCompass | Publicación de la aplicación | +| Hosting automatizaciones | Infraestructura n8n GLM | Ejecución de workflows | + +### Integraciones externas + +| Sistema | Tipo de integración | Datos que fluyen | +|---|---|---| +| Supabase | Auth + REST / RPC | Sesión, autorización, histórico y seguimiento | +| n8n | Webhook HTTP | Archivos de nómina, archivos bancarios y metadata del período | +| BambooHR | API REST | Empleados, estado, ubicación, fecha de ingreso y Employee Number | +| Google Sheets | Google API | Creación y formato del reporte final | +| Gitea | Git | Código fuente y control de versiones | + +--- + +## PAÍSES IMPLEMENTADOS + +### Guatemala - COMPLETADO + +El flujo de Guatemala procesa una nómina Excel con múltiples hojas y uno o varios archivos bancarios. + +Estado actual: + +- Cruce de nómina vs banco operativo. +- Validación BambooHR operativa. +- Se consultan empleados activos e inactivos mediante `onlyCurrent=false`. +- Matching de nombres optimizado para evitar bloqueos del task runner de n8n. +- Matching por Employee Number cuando existe evidencia disponible. +- Matching por nombres normalizados, alias y variantes controladas. +- No se fuerzan coincidencias ambiguas. +- Banco sin Bamboo validado con el dataset de regresión de junio 2026. +- Baseline validado del caso de prueba: **34 casos reales de Banco sin Bamboo**. +- Diferencias de nombre bancario incluidas en el reporte. +- Posibles cuentas mal digitadas incluidas. +- Columna de resolución incluida donde corresponde. +- Formato del Google Sheet automatizado. +- Altura de filas y ajuste de texto automático. +- Reporte final validado visualmente. + +### Trinidad y Tobago - COMPLETADO + +El flujo de Trinidad y Tobago procesa la estructura de nómina utilizada por el país y los archivos bancarios ACH correspondientes. + +Estado actual: + +- Cruce de nómina vs banco operativo. +- Validación BambooHR operativa. +- Empleados activos e inactivos incluidos. +- Normalización de nombres adaptada a nombres con apóstrofes, guiones y variantes. +- Matching BambooHR optimizado. +- Banco sin Bamboo validado con el dataset de regresión de junio 2026. +- Baseline validado del caso de prueba: **0 casos reales de Banco sin Bamboo**. +- Casos anteriormente problemáticos fueron reconocidos correctamente por BambooHR. +- Columna de resolución incluida donde corresponde. +- Formato automático del Google Sheet habilitado. +- Reporte final validado visualmente. + +### Próximos países + +La arquitectura no está limitada a GT y TT. + +Los siguientes países se incorporarán progresivamente reutilizando: + +1. El mismo frontend. +2. La misma autenticación. +3. El mismo control centralizado de acceso. +4. La misma estructura de histórico. +5. El mismo modelo de generación de reportes. +6. Un workflow específico por país cuando la estructura de nómina o banco lo requiera. + +--- + +## REGLAS DE NEGOCIO + +1. El país seleccionado determina qué workflow de conciliación debe ejecutarse. +2. El período debe contener año, mes y tipo de período antes de ejecutar el cruce. +3. La nómina y los archivos bancarios deben analizarse manteniendo sus datos originales para trazabilidad. +4. Las cuentas bancarias se normalizan antes de compararse. +5. Los montos se comparan con precisión monetaria y tolerancias controladas. +6. Una coincidencia por nombre nunca debe forzarse si existen candidatos ambiguos. +7. BambooHR debe consultar empleados activos e inactivos mediante `onlyCurrent=false`. +8. Employee Number tiene prioridad cuando existe una referencia confiable que permita utilizarlo. +9. Las variaciones de nombre pueden resolverse mediante nombres completos, alias, normalización y reglas de similitud controladas. +10. Los casos ambiguos deben permanecer como pendientes de revisión en lugar de convertirse en falsos positivos. +11. Un registro de Banco sin Bamboo solo debe permanecer en esa categoría cuando no existe evidencia suficiente para asociarlo con una persona de BambooHR. +12. El reporte debe ser legible al generarse; el usuario no debe tener que expandir manualmente filas o columnas para visualizar información. +13. Los reportes históricos deben conservar su estado de resolución. +14. La incorporación de un nuevo país no debe requerir crear otra aplicación independiente. + +--- + +## CONFIGURACIÓN Y SETUP + +### Prerrequisitos + +- Node.js compatible con el proyecto. +- npm. +- Acceso al repositorio Gitea. +- Acceso al proyecto Supabase. +- Acceso a n8n. +- Credenciales BambooHR configuradas en n8n. +- Credenciales Google configuradas en n8n. +- Acceso al servidor donde se publica el frontend. +- Workflows de los países habilitados en n8n. + +### Variables de entorno + +Las variables reales deben permanecer fuera del repositorio y documentarse mediante `.env.example`. + +Entre las configuraciones necesarias se encuentran: + +| Variable / configuración | Descripción | Dónde se obtiene | +|---|---|---| +| Supabase URL | URL del proyecto Supabase | Supabase | +| Supabase public/anon key | Clave pública utilizada por el frontend | Supabase | +| URLs de webhook n8n | Endpoints para ejecutar cada país | n8n | +| Redirect URLs de autenticación | URLs válidas de login/callback | Supabase Auth | + +> **Nunca commitear credenciales, service-role keys, contraseñas, API keys privadas ni secretos de BambooHR al repositorio.** + +### Control de acceso en Supabase + +El acceso centralizado de la aplicación utiliza la tabla: + +```text +public.cruce_cuentas_usuarios_autorizados +``` + +y las funciones/RPC implementadas para validar acceso: + +```text +cruce_cuentas_mi_acceso() +cruce_cuentas_tiene_acceso_app() +``` + +El frontend consulta Supabase para determinar si el usuario autenticado tiene acceso a la aplicación. + +--- + +## INSTALACIÓN / DESARROLLO LOCAL + +```bash +git clone https://git.digitalcompass.agency/Isaac_Aracena/cruce-cuentas-glm-centralizado +cd cruce-cuentas-glm-centralizado + +npm install +``` + +Crear el archivo de entorno local a partir del ejemplo disponible en el repositorio: + +```bash +cp .env.example .env +``` + +Configurar las variables necesarias y ejecutar: + +```bash +npm run dev +``` + +Para generar el build de producción: + +```bash +npm run build +``` + +El resultado se genera en: + +```text +/dist +``` + +--- + +## DEPLOY + +La aplicación se publica bajo: + +```text +https://digitalcompass.agency/cruce-cuentas/ +``` + +Antes de publicar una nueva versión: + +```bash +npm install +npm run build +``` + +Luego debe desplegarse el contenido actualizado de `dist` en la ubicación correspondiente del servidor. + +### Importante + +El `base` de Vite debe mantenerse compatible con: + +```text +/cruce-cuentas/ +``` + +Después del deploy se debe comprobar: + +- Login. +- Recuperación de sesión. +- Acceso autorizado/no autorizado. +- Carga de archivos. +- Ejecución de GT. +- Ejecución de TT. +- Apertura del Google Sheet generado. +- Histórico de reportes. +- Persistencia de resoluciones. + +--- + +## CÓMO FUNCIONA + +### Flujo paso a paso + +1. El usuario inicia sesión. +2. Supabase valida la sesión. +3. La aplicación consulta si el usuario está autorizado. +4. El usuario selecciona el país. +5. Selecciona año, mes y período. +6. Adjunta la nómina. +7. Adjunta los archivos bancarios requeridos. +8. La aplicación envía los datos al webhook de n8n correspondiente al país. +9. n8n extrae y normaliza las diferentes hojas de nómina. +10. n8n procesa los archivos bancarios. +11. BambooHR devuelve la base de empleados utilizando un reporte custom con empleados actuales e históricos. +12. Se ejecutan las reglas de matching y conciliación. +13. Se clasifican las coincidencias, discrepancias y casos de revisión. +14. Se genera el Google Sheet. +15. Se aplican automáticamente anchos, ajuste de texto y alturas de filas. +16. El enlace del reporte vuelve a la aplicación. +17. El usuario puede abrir el Google Sheet y consultar posteriormente el histórico. + +### Triggers + +| Trigger | Frecuencia | Descripción | +|---|---|---| +| Webhook GT | On demand | Ejecutado al procesar un cruce de Guatemala | +| Webhook TT | On demand | Ejecutado al procesar un cruce de Trinidad y Tobago | +| Futuros webhooks | On demand | Se agregarán al incorporar nuevos países | + +--- + +## TESTING + +### Casos de prueba mínimos + +| Caso | Input | Output esperado | Estado | +|---|---|---|---| +| Guatemala - junio 2026 Q30 | Nómina + archivos bancarios reales de prueba | 34 casos reales de Banco sin Bamboo | ✅ Validado | +| Trinidad y Tobago - junio 2026 Q30 | Nómina + archivo bancario real de prueba | 0 casos reales de Banco sin Bamboo | ✅ Validado | +| Empleado inactivo en BambooHR | Pago de persona histórica | Debe poder localizarse con `onlyCurrent=false` | ✅ Validado | +| Variación de nombre | Tildes, segundo nombre, apóstrofes o guiones | Match cuando existe evidencia suficiente | ✅ Validado | +| Nombre ambiguo | Dos candidatos posibles | No forzar match | ✅ Validado | +| Cuenta diferente con nombre y monto correctos | Nómina y banco con cuentas distintas | Clasificar como posible cuenta mal digitada | ✅ Validado | +| Diferencia de monto | Misma persona/cuenta con monto diferente | Crear discrepancia | ✅ Validado | +| Banco sin nómina | Pago bancario sin registro equivalente | Mostrar para revisión | ✅ Validado | +| Formato del reporte | Observaciones/nombres largos | Contenido visible sin expansión manual | ✅ Implementado | +| Rendimiento BambooHR | Miles de empleados | No bloquear el task runner de n8n | ✅ Optimizado | + +### Regresión obligatoria antes de cambios en BambooHR + +Cualquier modificación al matching de BambooHR debe volver a probar como mínimo: + +- Dataset GT de junio 2026. +- Dataset TT de junio 2026. +- Casos de nombres cortos. +- Casos de nombres completos. +- Empleados inactivos. +- Empleados con ubicación inconsistente. +- Nombres con tildes. +- Nombres con apóstrofes o guiones. +- Ambigüedades. +- Tiempo de ejecución del nodo Code. + +No se debe reducir globalmente el nivel de confianza únicamente para hacer desaparecer filas de Banco sin Bamboo. + +--- + +## ERRORES CONOCIDOS Y TROUBLESHOOTING + +| Error | Causa probable | Solución | +|---|---|---| +| `Task execution aborted because runner became unresponsive` | Código de matching recorriendo demasiados empleados/repeticiones | Mantener matching indexado y reutilizar resultados precalculados; no volver a búsquedas O(N×M) sobre toda la base | +| Banco sin Bamboo aumenta repentinamente | Reporte BambooHR incompleto o regresión del matching | Revisar `onlyCurrent=false`, normalizador y dataset de regresión | +| Falso positivo de BambooHR | Umbral demasiado permisivo o nombre ambiguo | Mantener reglas conservadoras y no aceptar candidatos sin evidencia suficiente | +| No abre el reporte | URL del Sheet no llegó correctamente al frontend | Revisar respuesta final del workflow y ejecución de n8n | +| Login vuelve a una ruta incorrecta | Redirect URL de Supabase no configurada | Revisar URLs permitidas para `/cruce-cuentas/` y callbacks | +| Contenido cortado en Google Sheets | Formato final no aplicado | Revisar las requests de wrap, ancho de columnas y auto-resize de filas | +| Workflow rojo en n8n | Error de input, credencial o nodo Code | Revisar `Executions` y el primer nodo que falla | + +--- + +## MONITOREO + +### n8n + +Revisar `Executions` ante cualquier reporte de error. + +- Verde = ejecución terminada correctamente. +- Rojo = identificar el primer nodo fallido. +- En problemas de BambooHR, revisar especialmente: + - HTTP BambooHR. + - Normalizar BambooHR. + - Cruzar Nómina vs Banco. + +### Supabase + +Revisar: + +- Sesiones. +- Usuarios autorizados. +- Histórico. +- Errores de RLS/RPC cuando corresponda. + +### Output esperado + +Una ejecución correcta debe: + +1. Terminar sin errores. +2. Generar un Google Sheet. +3. Devolver la URL del reporte a la aplicación. +4. Mostrar un reporte legible y completamente formateado. +5. Mantener únicamente diferencias reales o casos que requieren revisión humana. + +--- + +## ESTRUCTURA DEL REPOSITORIO + +Estructura principal esperada/actual del frontend: + +```text +/cruce-cuentas-glm-centralizado +|-- README.md +|-- package.json +|-- vite.config.ts +|-- .env.example +|-- /src +| |-- componentes y lógica de la aplicación +| └-- integraciones del frontend +|-- /public +|-- /dist +| └-- build utilizado para producción +└-- ... +``` + +Los workflows de n8n deben mantenerse exportados y versionados de forma controlada durante la evolución del proyecto. + +--- + +## CHANGELOG + +### 2026-08-08 - Estado actual + +- Guatemala completado funcionalmente. +- Trinidad y Tobago completado funcionalmente. +- Frontend centralizado para múltiples países. +- Autenticación y control de acceso mediante Supabase. +- Histórico y seguimiento integrados. +- Validación BambooHR con empleados activos e inactivos. +- Matching BambooHR optimizado para rendimiento y precisión. +- Baseline GT: 34 casos reales de Banco sin Bamboo. +- Baseline TT: 0 casos reales de Banco sin Bamboo. +- Formato automático de Google Sheets implementado. +- Arquitectura preparada para incorporar países adicionales. + +--- + +## DECISIONS LOG + +### DEC-001 - Una sola aplicación para todos los países + +- **Contexto:** El proceso de cruce se repetirá en diferentes países. +- **Opciones consideradas:** Una aplicación por país vs una aplicación centralizada. +- **Decisión:** Mantener una única aplicación y agregar lógica/workflows por país. +- **Razón:** Facilita mantenimiento, acceso, histórico, despliegue y crecimiento. + +### DEC-002 - Supabase como control centralizado de acceso + +- **Contexto:** El acceso no debe depender de listas hardcodeadas en el frontend. +- **Decisión:** Mantener usuarios autorizados en Supabase. +- **Razón:** Permite agregar o retirar acceso sin recompilar la aplicación. + +### DEC-003 - Consultar históricos de BambooHR + +- **Contexto:** Un pago puede corresponder a una persona actualmente inactiva. +- **Decisión:** Utilizar el reporte custom de BambooHR con `onlyCurrent=false`. +- **Razón:** Banco sin Bamboo debe significar realmente que no existe evidencia suficiente en BambooHR, no simplemente que el empleado está inactivo. + +### DEC-004 - Matching BambooHR conservador + +- **Contexto:** Nombres pueden variar entre nómina, banco y BambooHR. +- **Decisión:** Combinar Employee Number, nombres normalizados, aliases y matching indexado, manteniendo reglas estrictas para ambigüedades. +- **Razón:** Reducir falsos negativos sin generar falsos positivos. + +### DEC-005 - Precalcular e indexar búsquedas de BambooHR + +- **Contexto:** Comparar cada fila contra miles de empleados provocó bloqueos del task runner. +- **Decisión:** Indexar candidatos y reutilizar resoluciones precalculadas. +- **Razón:** Mantener tiempos de ejecución estables. + +### DEC-006 - Formato del reporte completamente automático + +- **Contexto:** Algunas celdas quedaban cortadas y requerían ajustes manuales. +- **Decisión:** Aplicar wrap, anchos definidos y auto-resize de filas durante la creación del Google Sheet. +- **Razón:** El reporte debe quedar listo para uso inmediatamente después de generarse. + +### DEC-007 - Expansión progresiva a los demás países + +- **Fecha:** 2026-08-08 +- **Contexto:** GT y TT son únicamente la primera etapa. +- **Decisión:** Continuar incorporando países dentro de la misma plataforma. +- **Razón:** Mantener una solución GLM centralizada y escalable. + +--- + +## CONTACTOS DEL PROYECTO + +| Rol | Nombre | Contacto | +|---|---|---| +| IT Manager | Luis Matos | Canal interno GLM | +| Developer Principal | Isaac Aracena | Canal interno GLM | +| Usuarios de negocio | Equipos autorizados de Administración / RRHH | Canal interno GLM | + +--- + +## DEFINITION OF DONE + +### Alcance actual - Guatemala y Trinidad y Tobago + +- [x] Frontend centralizado operativo. +- [x] Login mediante Supabase. +- [x] Acceso centralizado mediante base de datos. +- [x] Workflow Guatemala operativo. +- [x] Workflow Trinidad y Tobago operativo. +- [x] Cruce de cuentas y montos. +- [x] Validación BambooHR. +- [x] Empleados activos e inactivos incluidos. +- [x] Matching optimizado para no bloquear n8n. +- [x] Reporte Google Sheets generado automáticamente. +- [x] Banco sin Bamboo validado contra datasets de regresión. +- [x] Formato automático de filas y columnas. +- [x] Histórico disponible. +- [x] Código frontend versionado en Gitea. +- [x] Pruebas con datos reales de referencia para GT y TT. +- [ ] Documentar Board de ejecución definitivo. +- [ ] Documentar PRD definitivo en el repositorio. +- [ ] Mantener `.env.example` sincronizado con las variables utilizadas. +- [ ] Versionar los exports finales de n8n en la estructura definitiva del repositorio. +- [ ] Registrar validación/cierre formal del negocio cuando corresponda. + +### Próxima etapa + +- [ ] Incorporar nuevos países. +- [ ] Documentar reglas particulares de cada país. +- [ ] Crear datasets de regresión por país. +- [ ] Mantener una única experiencia de usuario desde el portal centralizado. + +--- + +**Documento mantenido por el equipo GLM IT.**