# 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.**