Isaac_Aracena/cruce-cuentas-glm-centralizado

Files

T

Isaac_Aracena d96ba50dac Actualizar README.md

2026-08-08 13:36:29 +00:00

20 KiB

Raw Blame History

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
Estado	En progreso - Guatemala y Trinidad y Tobago completados
Developer Principal	Isaac Aracena
IT Manager	Luis Matos

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

[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

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:

El mismo frontend.
La misma autenticación.
El mismo control centralizado de acceso.
La misma estructura de histórico.
El mismo modelo de generación de reportes.
Un workflow específico por país cuando la estructura de nómina o banco lo requiera.

REGLAS DE NEGOCIO

El país seleccionado determina qué workflow de conciliación debe ejecutarse.
El período debe contener año, mes y tipo de período antes de ejecutar el cruce.
La nómina y los archivos bancarios deben analizarse manteniendo sus datos originales para trazabilidad.
Las cuentas bancarias se normalizan antes de compararse.
Los montos se comparan con precisión monetaria y tolerancias controladas.
Una coincidencia por nombre nunca debe forzarse si existen candidatos ambiguos.
BambooHR debe consultar empleados activos e inactivos mediante onlyCurrent=false.
Employee Number tiene prioridad cuando existe una referencia confiable que permita utilizarlo.
Las variaciones de nombre pueden resolverse mediante nombres completos, alias, normalización y reglas de similitud controladas.
Los casos ambiguos deben permanecer como pendientes de revisión en lugar de convertirse en falsos positivos.
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.
El reporte debe ser legible al generarse; el usuario no debe tener que expandir manualmente filas o columnas para visualizar información.
Los reportes históricos deben conservar su estado de resolución.
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:

public.cruce_cuentas_usuarios_autorizados

y las funciones/RPC implementadas para validar acceso:

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

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:

cp .env.example .env

Configurar las variables necesarias y ejecutar:

npm run dev

Para generar el build de producción:

npm run build

El resultado se genera en:

/dist

DEPLOY

La aplicación se publica bajo:

https://digitalcompass.agency/cruce-cuentas/

Antes de publicar una nueva versión:

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:

/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

El usuario inicia sesión.
Supabase valida la sesión.
La aplicación consulta si el usuario está autorizado.
El usuario selecciona el país.
Selecciona año, mes y período.
Adjunta la nómina.
Adjunta los archivos bancarios requeridos.
La aplicación envía los datos al webhook de n8n correspondiente al país.
n8n extrae y normaliza las diferentes hojas de nómina.
n8n procesa los archivos bancarios.
BambooHR devuelve la base de empleados utilizando un reporte custom con empleados actuales e históricos.
Se ejecutan las reglas de matching y conciliación.
Se clasifican las coincidencias, discrepancias y casos de revisión.
Se genera el Google Sheet.
Se aplican automáticamente anchos, ajuste de texto y alturas de filas.
El enlace del reporte vuelve a la aplicación.
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:

Terminar sin errores.
Generar un Google Sheet.
Devolver la URL del reporte a la aplicación.
Mostrar un reporte legible y completamente formateado.
Mantener únicamente diferencias reales o casos que requieren revisión humana.

ESTRUCTURA DEL REPOSITORIO

Estructura principal esperada/actual del frontend:

/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	lmatos@gomezleemarketing.com
Developer Principal	Isaac Aracena	iaracena@gomezleemarketing.com

DEFINITION OF DONE

Alcance actual - Guatemala y Trinidad y Tobago

Frontend centralizado operativo.
Login mediante Supabase.
Acceso centralizado mediante base de datos.
Workflow Guatemala operativo.
Workflow Trinidad y Tobago operativo.
Cruce de cuentas y montos.
Validación BambooHR.
Empleados activos e inactivos incluidos.
Matching optimizado para no bloquear n8n.
Reporte Google Sheets generado automáticamente.
Banco sin Bamboo validado contra datasets de regresión.
Formato automático de filas y columnas.
Histórico disponible.
Código frontend versionado en Gitea.
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.

Documento mantenido por el equipo GLM IT.

20 KiB Raw Blame History Unescape Escape