Agregar Bono 14 Guatemala y actualizar dist
This commit is contained in:
@@ -1,566 +1,409 @@
|
||||
# Cruce de Cuentas GLM - Centralizado
|
||||
# Cruce de Cuentas GLM
|
||||
|
||||
> 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.
|
||||
> Portal centralizado para acceder a los módulos de Cruce de Cuentas por país, permitiendo tener un único punto de entrada seguro para los portales regionales de conciliación.
|
||||
|
||||
---
|
||||
|
||||
## INFORMACIÓN GENERAL
|
||||
## Información General
|
||||
|
||||
| Campo | Detalle |
|
||||
| ------------------------ | ------------------------------------ |
|
||||
| Proyecto | Cruce de Cuentas GLM |
|
||||
| Área | Nómina |
|
||||
| Estado | Prototipo funcional / Portal central |
|
||||
| Developer Principal | Isaac Aracena |
|
||||
| IT Manager | Luis Matos |
|
||||
| Product Owner | Máximo Gómez |
|
||||
|
||||
| Campo | Detalle |
|
||||
|---|---|
|
||||
| Proyecto | Cruce de Cuentas GLM - Centralizado |
|
||||
| Área | Administración |
|
||||
| Estado | Guatemala y Trinidad y Tobago completados |
|
||||
| Developer Principal | Isaac Aracena |
|
||||
| IT Manager | Luis Matos |
|
||||
|
||||
---
|
||||
|
||||
## OBJETIVO
|
||||
## 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.
|
||||
Actualmente, los procesos de cruce de cuentas por país pueden quedar dispersos en diferentes aplicaciones, enlaces, flujos o repositorios. Esto dificulta el acceso ordenado, el control de permisos y la visibilidad de cuáles países tienen un portal activo, pendiente o en desarrollo.
|
||||
|
||||
### Solución implementada
|
||||
|
||||
Cruce de Cuentas GLM centraliza este proceso en una aplicación web.
|
||||
Cruce de Cuentas GLM funciona como un portal central de acceso. Desde esta aplicación, los usuarios autorizados pueden iniciar sesión con Google, visualizar los países disponibles y acceder al portal correspondiente de cada país.
|
||||
|
||||
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.
|
||||
Este repositorio no ejecuta el cruce de nómina ni procesa archivos bancarios. Su responsabilidad principal es centralizar el acceso y redireccionar a los portales operativos de cada país.
|
||||
|
||||
### 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.
|
||||
* Equipo de Nómina.
|
||||
* IT.
|
||||
* Gerencia regional.
|
||||
* Usuarios autorizados que necesiten acceder a los portales de cruce por país.
|
||||
|
||||
---
|
||||
|
||||
## ARQUITECTURA
|
||||
## Estado Actual del Proyecto
|
||||
|
||||
### Diagrama de flujo
|
||||
Este repositorio contiene un **portal frontend centralizado** desarrollado con React, Vite, TypeScript y Supabase Auth.
|
||||
|
||||
```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]
|
||||
La aplicación permite:
|
||||
|
||||
* Iniciar sesión con Google mediante Supabase Auth.
|
||||
* Validar correos autorizados.
|
||||
* Mostrar una pantalla central con países disponibles.
|
||||
* Visualizar tarjetas por país.
|
||||
* Identificar el portal de Guatemala como módulo iniciado.
|
||||
* Mostrar los demás países como módulos pendientes o no iniciados.
|
||||
* Preparar la navegación hacia los portales independientes de cada país.
|
||||
|
||||
---
|
||||
|
||||
|
||||
## Arquitectura
|
||||
|
||||
### Arquitectura actual
|
||||
|
||||
```txt
|
||||
Usuario autorizado
|
||||
↓
|
||||
Google Login
|
||||
↓
|
||||
Supabase Auth
|
||||
↓
|
||||
Portal Central Cruce de Cuentas GLM
|
||||
↓
|
||||
Tarjetas por país
|
||||
↓
|
||||
Modal informativo / redirección futura
|
||||
```
|
||||
|
||||
### Stack tecnológico
|
||||
### Arquitectura objetivo
|
||||
|
||||
| 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 |
|
||||
```txt
|
||||
Usuario autorizado
|
||||
↓
|
||||
Portal Central Cruce de Cuentas GLM
|
||||
↓
|
||||
Selección de país
|
||||
↓
|
||||
Redirección al portal del país
|
||||
↓
|
||||
Portal específico ejecuta su propio flujo
|
||||
↓
|
||||
n8n / BambooHR / Banco / Nómina / Reportes
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## PAÍSES IMPLEMENTADOS
|
||||
## Stack Tecnológico
|
||||
|
||||
### 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.
|
||||
| Componente | Tecnología | Propósito |
|
||||
| --------------- | ----------------------------- | -------------------------------------- |
|
||||
| Frontend | React 19 | Interfaz del portal central |
|
||||
| Build Tool | Vite | Desarrollo local y build de producción |
|
||||
| Lenguaje | TypeScript | Tipado del frontend |
|
||||
| Estilos | Tailwind CSS 4 | Diseño visual |
|
||||
| Animaciones | Motion | Transiciones y animaciones |
|
||||
| Iconos | Lucide React | Iconografía |
|
||||
| Autenticación | Supabase Auth | Login con Google |
|
||||
| Package Manager | npm | Gestión de dependencias |
|
||||
| Infraestructura | Servidor GLM | Hosting del portal |
|
||||
|
||||
---
|
||||
|
||||
## REGLAS DE NEGOCIO
|
||||
## Integraciones
|
||||
|
||||
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.
|
||||
### Integraciones actuales
|
||||
|
||||
| Sistema | Tipo de integración | Uso |
|
||||
| -------------- | -------------------- | ---------------------------- |
|
||||
| Supabase Auth | OAuth con Google | Autenticación de usuarios |
|
||||
| Google Login | Provider de Supabase | Inicio de sesión corporativo |
|
||||
| Frontend React | SPA | Portal visual centralizado |
|
||||
|
||||
### Integraciones futuras
|
||||
|
||||
| Sistema | Tipo de integración | Uso |
|
||||
| ----------------- | ------------------- | -------------------------------------------------------------- |
|
||||
| Portales por país | Redirección por URL | Enviar al usuario al portal correspondiente |
|
||||
| Supabase Database | Opcional | Configurar países, URLs, estado y permisos desde base de datos |
|
||||
| n8n | Indirecta | Cada portal país podrá disparar su propio flujo de cruce |
|
||||
| BambooHR | Indirecta | Será usado por el flujo del país, no por este portal central |
|
||||
|
||||
---
|
||||
|
||||
## CONFIGURACIÓN Y SETUP
|
||||
## Regla Principal del Sistema
|
||||
|
||||
Este portal solo centraliza accesos.
|
||||
|
||||
```txt
|
||||
Portal Central ≠ Motor de Cruce
|
||||
Portal Central = Login + Selección de país + Redirección
|
||||
```
|
||||
|
||||
La lógica operativa debe mantenerse separada por país para evitar mezclar reglas, formatos de nómina, monedas, bancos, excepciones y reportes.
|
||||
|
||||
---
|
||||
|
||||
## Reglas de Negocio
|
||||
|
||||
1. Solo usuarios autorizados pueden acceder al portal.
|
||||
|
||||
2. El usuario debe iniciar sesión mediante Google.
|
||||
|
||||
3. La autenticación se gestiona con Supabase Auth.
|
||||
|
||||
4. Los correos autorizados se validan actualmente desde el frontend.
|
||||
|
||||
5. El portal debe mostrar todos los países disponibles.
|
||||
|
||||
6. Guatemala debe mostrarse como el primer módulo iniciado.
|
||||
|
||||
7. Los países no implementados deben mostrarse como pendientes, no iniciados o deshabilitados.
|
||||
|
||||
8. Al seleccionar un país activo, el sistema debe redireccionar al portal correspondiente.
|
||||
|
||||
9. Al seleccionar un país no activo, el sistema debe informar que el módulo aún no está disponible.
|
||||
|
||||
10. Este portal no debe procesar archivos de nómina ni banco.
|
||||
|
||||
11. Este portal no debe ejecutar conciliaciones.
|
||||
|
||||
12. Este portal no debe almacenar archivos sensibles.
|
||||
|
||||
13. Cada portal país debe manejar su propia lógica, flujo de n8n y reglas de cruce.
|
||||
|
||||
14. Las URLs de redirección deben mantenerse documentadas y controladas.
|
||||
|
||||
15. Cualquier cambio de permisos debe ser validado por IT.
|
||||
|
||||
---
|
||||
|
||||
Cualquier otro correo que inicie sesión con Google debe ser rechazado y cerrado automáticamente.
|
||||
|
||||
> Nota: En una versión futura, esta validación debería moverse a una tabla de permisos en Supabase o a una política controlada por IT, para evitar mantener correos hardcodeados en el frontend.
|
||||
|
||||
---
|
||||
|
||||
### Estado actual
|
||||
|
||||
El portal usa Supabase Auth para autenticación, pero no requiere una base de datos compleja para operar como portal central.
|
||||
|
||||
### Uso opcional de Supabase Database
|
||||
|
||||
Si se desea evitar URLs hardcodeadas en el frontend, Supabase puede usarse para guardar configuración dinámica de portales.
|
||||
|
||||
Tabla sugerida:
|
||||
|
||||
```sql
|
||||
create table country_portals (
|
||||
id uuid primary key default gen_random_uuid(),
|
||||
country_name text not null,
|
||||
country_code text not null unique,
|
||||
portal_url text,
|
||||
status text not null default 'pending',
|
||||
is_visible boolean not null default true,
|
||||
display_order int not null default 0,
|
||||
created_at timestamptz default now(),
|
||||
updated_at timestamptz default now()
|
||||
);
|
||||
```
|
||||
|
||||
Campos sugeridos:
|
||||
|
||||
| Campo | Descripción |
|
||||
| ------------- | ------------------------------------- |
|
||||
| country_name | Nombre del país |
|
||||
| country_code | Código del país |
|
||||
| portal_url | URL del portal específico |
|
||||
| status | Estado del portal |
|
||||
| is_visible | Define si se muestra o no en pantalla |
|
||||
| display_order | Orden visual |
|
||||
| created_at | Fecha de creación |
|
||||
| updated_at | Fecha de actualización |
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
* Node.js v18 o superior.
|
||||
* npm.
|
||||
* Acceso al repositorio.
|
||||
* Proyecto Supabase configurado.
|
||||
* Supabase Auth con Google habilitado.
|
||||
* Variables de entorno configuradas.
|
||||
* URLs de redirección configuradas en Supabase.
|
||||
|
||||
---
|
||||
|
||||
## INSTALACIÓN / DESARROLLO LOCAL
|
||||
## Variables de Entorno
|
||||
|
||||
Crear un archivo `.env.local` en la raíz del proyecto basado en `.env.example`.
|
||||
|
||||
```env
|
||||
VITE_SUPABASE_URL="https://TU-PROYECTO.supabase.co"
|
||||
VITE_SUPABASE_ANON_KEY="TU_SUPABASE_ANON_KEY"
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Instalación / Ejecución Local
|
||||
|
||||
### Instalar dependencias
|
||||
|
||||
```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:
|
||||
### Ejecutar en desarrollo
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Para generar el build de producción:
|
||||
La aplicación estará disponible en:
|
||||
|
||||
```txt
|
||||
http://localhost:3000
|
||||
```
|
||||
|
||||
### Generar build de producción
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
El resultado se genera en:
|
||||
### Preview del build
|
||||
|
||||
```text
|
||||
/dist
|
||||
```bash
|
||||
npm run preview
|
||||
```
|
||||
|
||||
### Validar TypeScript
|
||||
|
||||
```bash
|
||||
npm run lint
|
||||
```
|
||||
|
||||
### Limpiar build
|
||||
|
||||
```bash
|
||||
npm run clean
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## DEPLOY
|
||||
## Configuración de Vite
|
||||
|
||||
La aplicación se publica bajo:
|
||||
El proyecto está configurado para desplegarse bajo la ruta:
|
||||
|
||||
```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
|
||||
```txt
|
||||
/cruce-cuentas/
|
||||
```
|
||||
|
||||
Después del deploy se debe comprobar:
|
||||
En `vite.config.ts`:
|
||||
|
||||
- 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
|
||||
└-- ...
|
||||
```ts
|
||||
base: "/cruce-cuentas/"
|
||||
```
|
||||
|
||||
Los workflows de n8n deben mantenerse exportados y versionados de forma controlada durante la evolución del proyecto.
|
||||
URL de producción esperada:
|
||||
|
||||
```txt
|
||||
https://digitalcompass.agency/cruce-cuentas/
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## CHANGELOG
|
||||
## Supabase Auth
|
||||
|
||||
### 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.
|
||||
En Supabase Auth se debe configurar Google como proveedor de autenticación.
|
||||
|
||||
---
|
||||
|
||||
## DECISIONS LOG
|
||||
## Decisions Log
|
||||
|
||||
### DEC-001 - Una sola aplicación para todos los países
|
||||
### DEC-001 — Crear un portal central en lugar de mezclar todos los cruces
|
||||
|
||||
- **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.
|
||||
* Fecha: Junio 2026.
|
||||
* Contexto: Cada país puede tener reglas, bancos, formatos y flujos distintos.
|
||||
* Opciones consideradas: Un único sistema para todos los países vs portal central con módulos separados.
|
||||
* Decisión: Crear un portal central que redireccione a los portales por país.
|
||||
* Razón: Permite centralizar el acceso sin mezclar la lógica operativa de cada país.
|
||||
|
||||
### DEC-002 - Supabase como control centralizado de acceso
|
||||
### DEC-002 — Usar Supabase Auth para el 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.
|
||||
* Fecha: Junio 2026.
|
||||
* Contexto: El portal necesita login seguro con usuarios autorizados.
|
||||
* Opciones consideradas: Login manual vs Google SSO vía Supabase.
|
||||
* Decisión: Usar Supabase Auth con Google.
|
||||
* Razón: Aprovecha autenticación existente, reduce complejidad y permite controlar acceso.
|
||||
|
||||
### DEC-003 - Consultar históricos de BambooHR
|
||||
### DEC-003 — Guatemala como primer país iniciado
|
||||
|
||||
- **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.
|
||||
* Fecha: Junio 2026.
|
||||
* Contexto: El primer flujo operativo de cruce se está trabajando para Guatemala.
|
||||
* Opciones consideradas: Activar todos los países vs iniciar con Guatemala.
|
||||
* Decisión: Marcar Guatemala como primer módulo iniciado.
|
||||
* Razón: Permite validar la arquitectura antes de escalar a otros países.
|
||||
|
||||
### DEC-004 - Matching BambooHR conservador
|
||||
### DEC-004 — Separar portal central del motor de cruce
|
||||
|
||||
- **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.
|
||||
* Fecha: Junio 2026.
|
||||
* Contexto: El portal central no debe cargar lógica pesada ni procesar datos sensibles.
|
||||
* Opciones consideradas: Procesar cruces desde este portal vs redireccionar a portales especializados.
|
||||
* Decisión: Este repositorio solo centraliza y redirecciona.
|
||||
* Razón: Mejora seguridad, mantenimiento y escalabilidad.
|
||||
|
||||
### DEC-005 - Precalcular e indexar búsquedas de BambooHR
|
||||
### DEC-005 — Mantener países pendientes visibles
|
||||
|
||||
- **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.
|
||||
* Fecha: Junio 2026.
|
||||
* Contexto: Se quiere mostrar la visión regional completa aunque solo algunos módulos estén activos.
|
||||
* Opciones consideradas: Ocultar países no activos vs mostrarlos como pendientes.
|
||||
* Decisión: Mostrar países pendientes con aviso de no iniciado.
|
||||
* Razón: Comunica el roadmap regional sin habilitar funciones incompletas.
|
||||
|
||||
---
|
||||
|
||||
## CONTACTOS DEL PROYECTO
|
||||
## Contactos del Proyecto
|
||||
|
||||
| Rol | Nombre | Contacto |
|
||||
|---|---|---|
|
||||
| IT Manager | Luis Matos | lmatos@gomezleemarketing.com |
|
||||
| Developer Principal | Isaac Aracena | iaracena@gomezleemarketing.com |
|
||||
| Rol | Nombre |
|
||||
| -------------------- | ------------- |
|
||||
| Product Owner | Máximo Gomez |
|
||||
| IT Manager | Luis Matos |
|
||||
| Developer | Isaac Aracena |
|
||||
| Usuarios autorizados | A completar |
|
||||
|
||||
---
|
||||
|
||||
## DEFINITION OF DONE
|
||||
## 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.
|
||||
- [x] Documentar Board de ejecución definitivo.
|
||||
- [x] Documentar PRD definitivo en el repositorio.
|
||||
- [x] Mantener `.env.example` sincronizado con las variables utilizadas.
|
||||
- [x] Versionar los exports finales de n8n en la estructura definitiva del repositorio.
|
||||
- [x] Registrar validación/cierre formal del negocio cuando corresponda.
|
||||
* README completo y actualizado.
|
||||
* Portal carga correctamente en local.
|
||||
* Portal carga correctamente en `/cruce-cuentas/`.
|
||||
* Supabase Auth configurado.
|
||||
* Google Login funcionando.
|
||||
* Correos autorizados validados.
|
||||
* Usuario no autorizado bloqueado.
|
||||
* Tarjetas de países visibles.
|
||||
* Guatemala configurado como módulo iniciado.
|
||||
* Países pendientes muestran aviso correcto.
|
||||
* Países activos redireccionan a su portal correspondiente.
|
||||
* Variables de entorno documentadas en `.env.example`.
|
||||
* Código commiteado y pusheado al repositorio.
|
||||
* Probado en ambiente real, no solo local.
|
||||
* Luis Matos validó el acceso.
|
||||
* Product Owner aprobó el resultado final.
|
||||
|
||||
---
|
||||
|
||||
**Documento mantenido por el equipo GLM IT.**
|
||||
---
|
||||
|
||||
## Bono 14 — Guatemala
|
||||
|
||||
El módulo de Guatemala incluye un cruce anual independiente de **Bono 14**
|
||||
visible únicamente para **Julio · Quincena 15**. Utiliza un Excel anual y CSV
|
||||
bancarios propios, genera un Google Sheet/histórico separado y reutiliza la
|
||||
identidad `GT-AAAA-07-bono14` cuando el mismo año se vuelve a procesar.
|
||||
|
||||
Ver `IMPLEMENTACION_BONO14_GUATEMALA.md`.
|
||||
|
||||
Reference in New Issue
Block a user