Actualizar README.md

2026-08-08 13:34:10 +00:00
parent 89448c7a8a
commit e94d6c6879
1 changed files with 0 additions and 0 deletions
@@ -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.**