969 lines
26 KiB
Markdown
969 lines
26 KiB
Markdown
# Cruce de Cuentas GLM - Guatemala
|
|
|
|
> Prototipo web interno para ejecutar cruces de nómina de Guatemala mediante n8n, comparando datos de BambooHR, nómina y banco para detectar diferencias, pagos no conciliados e irregularidades antes del cierre de nómina.
|
|
|
|
---
|
|
|
|
## Información General
|
|
|
|
| Campo | Detalle |
|
|
| ------------------------ | ------------------------------------------- |
|
|
| Proyecto | Cruce de Cuentas GLM - Guatemala |
|
|
| Área | RRHH / Nómina / Administración |
|
|
| Estado | Prototipo Frontend / En integración con n8n |
|
|
| Developer Principal | Isaac Aracena |
|
|
| IT Manager | Luis Matos |
|
|
| Máximo Gómez | Product Owner |
|
|
|
|
|
|
---
|
|
|
|
## Objetivo
|
|
|
|
### Problema que resuelve
|
|
|
|
Actualmente, el cruce entre empleados registrados en BambooHR, archivo de nómina y pagos bancarios de Guatemala requiere revisión manual en hojas de cálculo. Esto aumenta el riesgo de errores operativos, pagos duplicados, pagos a cuentas incorrectas, pagos a empleados inactivos o pagos a personas que no corresponden a la nómina oficial.
|
|
|
|
### Solución propuesta
|
|
|
|
Cruce de Cuentas GLM - Guatemala centraliza el flujo en una aplicación web donde el usuario selecciona el período, carga los archivos requeridos y ejecuta un flujo de n8n encargado de consultar BambooHR, procesar la nómina, cruzar contra el banco, generar el reporte final y guardar el historial de ejecución.
|
|
|
|
### Usuarios / Beneficiarios
|
|
|
|
* Equipo de RRHH Guatemala.
|
|
* Equipo de Nómina.
|
|
* Administración / Finanzas.
|
|
* IT.
|
|
* Gerencia responsable de control interno.
|
|
|
|
---
|
|
|
|
## Estado Actual del Proyecto
|
|
|
|
Este repositorio contiene actualmente un **prototipo frontend** generado inicialmente desde Antigravity / AI Studio.
|
|
|
|
El prototipo permite validar la experiencia visual y el flujo principal del usuario, pero la lógica real de cruce será implementada en **n8n**.
|
|
|
|
### Implementado actualmente
|
|
|
|
* Pantalla de login visual con botón “Continuar con Google”.
|
|
* Layout corporativo con logo de GomezLee Marketing.
|
|
* Módulo principal de “Cruce de Cuentas”.
|
|
* Módulo de “Reportes Históricos”.
|
|
* Carga visual de archivo de nómina.
|
|
* Carga visual de archivo bancario.
|
|
* Validación básica de formatos:
|
|
|
|
* Nómina: `.xlsx` / `.xls`.
|
|
* Banco: `.csv`.
|
|
* Ejecución simulada del cruce.
|
|
* Resultados demo con coincidencias y discrepancias.
|
|
* Toasts de éxito, error e información.
|
|
* Diseño responsive con sidebar móvil.
|
|
|
|
|
|
---
|
|
|
|
## Características Principales
|
|
|
|
### Funcionalidades del prototipo
|
|
|
|
* Interfaz moderna y responsive.
|
|
* Login visual simulado.
|
|
* Carga de archivo de nómina.
|
|
* Carga de archivo bancario.
|
|
* Ejecución simulada del cruce.
|
|
* Visualización de resultados.
|
|
* Filtros visuales por:
|
|
|
|
* Todos.
|
|
* Discrepancias.
|
|
* Coincidencias.
|
|
* Vista de reportes históricos simulados.
|
|
* Branding visual de GomezLee Marketing y Guatemala.
|
|
|
|
### Funcionalidades objetivo
|
|
|
|
* Portal centralizado para el cruce de cuentas de Guatemala.
|
|
* Selección de mes, año y tipo de cruce.
|
|
* Cruce mensual o quincena.
|
|
* Carga de archivo de nómina.
|
|
* Carga de uno o varios archivos bancarios.
|
|
* Envío de archivos y parámetros a un webhook de n8n.
|
|
* Consulta de empleados desde BambooHR API dentro de n8n.
|
|
* Validación por Employee Number.
|
|
* Validación por cuenta bancaria.
|
|
* Validación por nombre normalizado.
|
|
* Validación por monto y moneda.
|
|
* Manejo de excepciones de moneda.
|
|
* Generación de reporte final en Excel o Google Sheets.
|
|
* Registro de reportes históricos en Supabase.
|
|
* Audit log básico de ejecuciones.
|
|
* Alertas de irregularidades críticas.
|
|
|
|
---
|
|
|
|
## Alcance del MVP
|
|
|
|
El MVP debe enfocarse únicamente en Guatemala.
|
|
|
|
### Incluido en MVP
|
|
|
|
* Portal Guatemala activo.
|
|
* Selección de período.
|
|
* Selección de tipo de cruce:
|
|
|
|
* Mensual.
|
|
* Quincena.
|
|
* Carga de archivo de nómina.
|
|
* Carga de uno o varios archivos bancarios.
|
|
* Envío de archivos a n8n.
|
|
* Consulta de BambooHR desde n8n.
|
|
* Ejecución del cruce dentro de n8n.
|
|
* Visualización de resumen del resultado.
|
|
* Descarga del reporte final.
|
|
* Registro del cruce en Reportes Históricos.
|
|
* Guardado de metadatos en Supabase.
|
|
|
|
### Fuera de alcance para MVP
|
|
|
|
* Activación de otros países.
|
|
* Conexión directa con bancos.
|
|
* Aprobaciones formales de nómina.
|
|
* Edición manual de empleados desde la app.
|
|
* Sustitución del proceso contable sin validación humana.
|
|
* Automatización completa sin revisión del responsable.
|
|
* Procesamiento del cruce dentro de Supabase.
|
|
|
|
---
|
|
|
|
## Arquitectura
|
|
|
|
### Arquitectura actual del prototipo
|
|
|
|
```txt
|
|
Usuario
|
|
↓
|
|
React + Vite Frontend
|
|
↓
|
|
Carga visual de archivos
|
|
↓
|
|
Cruce simulado con data demo
|
|
↓
|
|
Tabla visual de resultados
|
|
```
|
|
|
|
### Arquitectura objetivo
|
|
|
|
```txt
|
|
Usuario autorizado
|
|
↓
|
|
App Web Cruce de Cuentas GT
|
|
↓
|
|
Webhook n8n
|
|
↓
|
|
n8n consulta BambooHR API
|
|
↓
|
|
n8n procesa Nómina + Banco + BambooHR
|
|
↓
|
|
n8n genera reporte final
|
|
↓
|
|
n8n guarda metadata en Supabase
|
|
↓
|
|
App muestra resultado + Reportes Históricos
|
|
```
|
|
|
|
### Rol de cada componente
|
|
|
|
| Componente | Responsabilidad |
|
|
| --------------------- | ---------------------------------------------------------------------------------------- |
|
|
| Frontend | Interfaz para cargar archivos, seleccionar período y consultar reportes |
|
|
| n8n | Orquestación completa del cruce, lógica de negocio, BambooHR API y generación de reporte |
|
|
| BambooHR API | Fuente oficial de empleados |
|
|
| Supabase | Historial de reportes, logs, metadatos y auditoría básica |
|
|
| Google Drive / Sheets | Almacenamiento o salida del reporte final, si aplica |
|
|
| Gmail / Google Chat | Notificaciones futuras del resultado del cruce |
|
|
|
|
---
|
|
|
|
## Stack Tecnológico Actual
|
|
|
|
| Componente | Tecnología | Propósito |
|
|
| -------------------- | ----------------------- | -------------------------- |
|
|
| Frontend | React 19 | Interfaz web |
|
|
| Build Tool | Vite | Servidor local y build |
|
|
| Lenguaje | TypeScript | Tipado del frontend |
|
|
| Estilos | Tailwind CSS 4 | Diseño visual |
|
|
| Animaciones | Motion | Transiciones y animaciones |
|
|
| Iconos | Lucide React | Iconografía |
|
|
| Package Manager | npm | Gestión de dependencias |
|
|
| Variables de entorno | dotenv / `.env.example` | Configuración inicial |
|
|
|
|
---
|
|
|
|
## Stack Tecnológico Objetivo
|
|
|
|
| Componente | Tecnología | Propósito |
|
|
| -------------------------------- | ------------------------ | ------------------------------------- |
|
|
| Frontend | React + Vite | Interfaz web del portal |
|
|
| Orquestación / Backend operativo | n8n | Ejecutar el cruce completo |
|
|
| RRHH | BambooHR API | Fuente oficial de empleados |
|
|
| Base de datos liviana | Supabase / PostgreSQL | Reportes históricos, logs y auditoría |
|
|
| Reportes | Excel / Google Sheets | Salida final del cruce |
|
|
| Notificaciones | Gmail / Google Chat | Alertas y avisos |
|
|
| Infraestructura | Servidor GLM | Hosting interno |
|
|
|
|
---
|
|
|
|
## Integraciones
|
|
|
|
### Integraciones actuales
|
|
|
|
Actualmente no hay integraciones reales activas. El prototipo funciona de forma local y simulada.
|
|
|
|
| Sistema | Estado | Comentario |
|
|
| --------------------- | --------- | ---------------------------------------------------------------- |
|
|
| Google SSO | Simulado | El login visual existe, pero no autentica realmente |
|
|
| BambooHR | Pendiente | La API ya está disponible, pero falta conectarla al flujo de n8n |
|
|
| n8n | Pendiente | Será el motor principal del cruce |
|
|
| Supabase | Pendiente | Se usará principalmente para Reportes Históricos |
|
|
| Google Sheets / Drive | Pendiente | Se puede usar como salida o almacenamiento del reporte |
|
|
| Base de datos local | No aplica | No se requiere backend tradicional en el MVP |
|
|
|
|
### Integraciones futuras
|
|
|
|
| Sistema | Tipo de integración | Datos que fluyen |
|
|
| --------------------- | ------------------------------- | ------------------------------------------------------------ |
|
|
| BambooHR | API REST desde n8n | Employee Number, nombre, estado, país, puesto, fecha de baja |
|
|
| Archivo de nómina | Upload desde frontend hacia n8n | Empleado, cuenta, moneda, período, neto a pagar |
|
|
| Banco | Upload desde frontend hacia n8n | Cuenta destino, beneficiario, monto, moneda, referencia |
|
|
| n8n | Webhook | Procesamiento completo del cruce y generación de reporte |
|
|
| Supabase | API REST / Postgres | Historial, estado de ejecución, resumen y enlaces |
|
|
| Google Drive / Sheets | API desde n8n | Archivo final o reporte consultable |
|
|
| Gmail / Google Chat | OAuth / Webhook desde n8n | Notificaciones de cruce terminado o irregularidades |
|
|
|
|
---
|
|
|
|
## Flujo n8n Objetivo
|
|
|
|
El flujo de n8n será el centro del procesamiento.
|
|
|
|
```txt
|
|
Webhook recibe solicitud
|
|
↓
|
|
Validar usuario / parámetros
|
|
↓
|
|
Recibir archivo de nómina
|
|
↓
|
|
Recibir archivo(s) de banco
|
|
↓
|
|
Consultar BambooHR API
|
|
↓
|
|
Normalizar BambooHR
|
|
↓
|
|
Normalizar nómina
|
|
↓
|
|
Normalizar banco
|
|
↓
|
|
Cruzar BambooHR vs Nómina
|
|
↓
|
|
Cruzar Nómina vs Banco
|
|
↓
|
|
Clasificar hallazgos
|
|
↓
|
|
Generar resumen ejecutivo
|
|
↓
|
|
Generar reporte Excel / Google Sheets
|
|
↓
|
|
Guardar metadata en Supabase
|
|
↓
|
|
Responder a la app con resultado y enlace
|
|
```
|
|
|
|
---
|
|
|
|
## Uso de Supabase
|
|
|
|
Supabase no será el motor principal del cruce. Su uso recomendado es para persistencia liviana y trazabilidad.
|
|
|
|
### Tablas sugeridas
|
|
|
|
```txt
|
|
users
|
|
reconciliation_runs
|
|
reconciliation_files
|
|
reconciliation_summary
|
|
reconciliation_findings
|
|
report_links
|
|
audit_logs
|
|
```
|
|
|
|
### Qué guardar en Supabase
|
|
|
|
* ID de ejecución.
|
|
* Usuario que ejecutó el cruce.
|
|
* País.
|
|
* Mes.
|
|
* Año.
|
|
* Tipo de cruce.
|
|
* Estado de ejecución.
|
|
* Fecha de inicio.
|
|
* Fecha de finalización.
|
|
* Cantidad de registros procesados.
|
|
* Cantidad de coincidencias.
|
|
* Cantidad de discrepancias.
|
|
* Cantidad de hallazgos críticos.
|
|
* Enlace al reporte generado.
|
|
* Errores ocurridos.
|
|
* Logs de auditoría.
|
|
|
|
### Qué no guardar en Supabase inicialmente
|
|
|
|
* Archivos completos de nómina.
|
|
* Archivos bancarios completos.
|
|
* Credenciales.
|
|
* Información sensible innecesaria.
|
|
* Datos duplicados que ya estén en el reporte final.
|
|
|
|
---
|
|
|
|
## Reglas de Negocio
|
|
|
|
1. El identificador principal del empleado debe ser `Employee Number` de BambooHR.
|
|
|
|
2. El sistema debe comparar empleados entre BambooHR, nómina y banco.
|
|
|
|
3. Un empleado activo en BambooHR con monto en nómina debe tener un pago bancario correspondiente.
|
|
|
|
4. Un pago bancario sin relación confiable con nómina debe marcarse como pago no conciliado.
|
|
|
|
5. Un empleado inactivo en BambooHR con pago debe marcarse como hallazgo crítico.
|
|
|
|
6. Las variaciones de nombre no deben considerarse irregularidad automáticamente.
|
|
|
|
7. El sistema debe normalizar nombres para reducir falsos positivos.
|
|
|
|
8. Las cuentas bancarias deben procesarse como texto para evitar pérdida de ceros iniciales.
|
|
|
|
9. La moneda debe validarse contra la nómina, el banco y las excepciones configuradas.
|
|
|
|
10. El reporte final debe priorizar hallazgos relevantes, diferencias e irregularidades.
|
|
|
|
11. Los casos correctos pueden incluirse en una hoja de detalle, pero no deben saturar la vista principal.
|
|
|
|
12. Todo cruce ejecutado debe registrar usuario, fecha, archivos utilizados y resultado.
|
|
|
|
13. No se debe permitir la ejecución si falta una fuente crítica de datos.
|
|
|
|
14. No se debe generar reporte final si BambooHR no responde correctamente.
|
|
|
|
15. Todo error debe devolver un mensaje claro al frontend y quedar registrado en Supabase.
|
|
|
|
---
|
|
|
|
## Tipos de Cruce
|
|
|
|
| Tipo de cruce | Descripción |
|
|
| ------------- | ----------------------------------------------------- |
|
|
| Mensual | Cruce completo del mes seleccionado |
|
|
| Quincena | Cruce de la quincena |
|
|
| Especial | Cruce puntual para reprocesos o casos extraordinarios |
|
|
|
|
---
|
|
|
|
## Fuentes de Datos
|
|
|
|
### BambooHR
|
|
|
|
Fuente oficial para validar:
|
|
|
|
* Employee Number.
|
|
* Nombre del empleado.
|
|
* Estado del empleado.
|
|
* Fecha de baja.
|
|
* País.
|
|
* Departamento.
|
|
* Posición.
|
|
* Email.
|
|
* Información laboral relevante.
|
|
|
|
### Nómina
|
|
|
|
Fuente para validar lo que debe pagarse:
|
|
|
|
* Employee Number.
|
|
* Nombre completo.
|
|
* Cuenta bancaria.
|
|
* Período.
|
|
* Moneda.
|
|
* Salario.
|
|
* Bonificaciones.
|
|
* Deducciones.
|
|
* Neto a pagar.
|
|
* Estado.
|
|
* Comentarios.
|
|
|
|
### Banco
|
|
|
|
Fuente para validar lo que realmente se pagó:
|
|
|
|
* Fecha de pago.
|
|
* Cuenta destino.
|
|
* Nombre del beneficiario.
|
|
* Monto pagado.
|
|
* Moneda.
|
|
* Referencia bancaria.
|
|
* Descripción o concepto.
|
|
|
|
---
|
|
|
|
## Normalización de Datos
|
|
|
|
Antes de cruzar información, n8n debe limpiar y estandarizar los datos.
|
|
|
|
### Normalización de nombres
|
|
|
|
Debe contemplar:
|
|
|
|
* Mayúsculas y minúsculas.
|
|
* Tildes.
|
|
* Espacios dobles.
|
|
* Orden de nombres y apellidos.
|
|
* Iniciales.
|
|
* Primer y segundo nombre.
|
|
* Palabras comunes como:
|
|
|
|
* DE
|
|
* DEL
|
|
* LA
|
|
* LAS
|
|
* LOS
|
|
* Y
|
|
* DA
|
|
* DO
|
|
* DAS
|
|
* DOS
|
|
|
|
### Normalización de montos
|
|
|
|
Debe contemplar:
|
|
|
|
* Separadores de miles.
|
|
* Decimales.
|
|
* Moneda.
|
|
* Redondeos.
|
|
* Diferencias menores dentro de la tolerancia permitida.
|
|
|
|
### Normalización de cuentas bancarias
|
|
|
|
Debe contemplar:
|
|
|
|
* Cuentas como texto.
|
|
* Ceros a la izquierda.
|
|
* Espacios.
|
|
* Guiones.
|
|
* Formatos distintos entre banco y nómina.
|
|
|
|
---
|
|
|
|
## Criterios de Coincidencia
|
|
|
|
### Coincidencia alta
|
|
|
|
```txt
|
|
Employee Number coincide
|
|
+
|
|
Cuenta bancaria coincide
|
|
+
|
|
Monto coincide dentro de tolerancia
|
|
```
|
|
|
|
### Coincidencia media
|
|
|
|
```txt
|
|
Cuenta bancaria coincide
|
|
+
|
|
Monto coincide
|
|
+
|
|
Nombre normalizado compatible
|
|
```
|
|
|
|
### Coincidencia baja
|
|
|
|
```txt
|
|
Nombre parecido
|
|
+
|
|
Monto parecido
|
|
```
|
|
|
|
### Sin coincidencia
|
|
|
|
```txt
|
|
No existe relación confiable entre BambooHR, nómina y banco.
|
|
```
|
|
|
|
Los casos con coincidencia baja o sin coincidencia deben ir al reporte de revisión.
|
|
|
|
---
|
|
|
|
## Reporte de Salida Objetivo
|
|
|
|
El sistema debe generar un reporte claro y accionable.
|
|
|
|
|
|
### Columnas sugeridas
|
|
|
|
```txt
|
|
Período
|
|
Tipo de Cruce
|
|
Employee Number
|
|
Empleado
|
|
Cuenta Nómina
|
|
Cuenta Banco
|
|
Moneda Nómina
|
|
Moneda Banco
|
|
Monto Nómina
|
|
Monto Banco
|
|
Diferencia
|
|
Estado BambooHR
|
|
Fecha de Baja
|
|
Categoría Hallazgo
|
|
Nivel de Confianza
|
|
Comentario
|
|
Acción Recomendada
|
|
```
|
|
|
|
---
|
|
|
|
## Flujo Principal Objetivo
|
|
|
|
```txt
|
|
1. El usuario entra al portal.
|
|
2. El sistema valida el acceso.
|
|
3. El usuario selecciona Guatemala.
|
|
4. El usuario selecciona mes, año y tipo de cruce.
|
|
5. El usuario carga el archivo de nómina.
|
|
6. El usuario carga uno o varios archivos bancarios.
|
|
7. El frontend envía archivos y parámetros al webhook de n8n.
|
|
8. n8n consulta BambooHR API.
|
|
9. n8n normaliza BambooHR, nómina, banco, nombres, cuentas, monedas y montos.
|
|
10. n8n cruza BambooHR vs Nómina.
|
|
11. n8n cruza Nómina vs Banco.
|
|
12. n8n identifica diferencias e irregularidades.
|
|
13. n8n genera resumen ejecutivo.
|
|
14. n8n genera archivo final.
|
|
15. n8n guarda metadata en Supabase.
|
|
16. n8n devuelve el resultado al frontend.
|
|
17. El usuario descarga el reporte.
|
|
18. El usuario puede consultar el cruce en Reportes Históricos.
|
|
```
|
|
|
|
---
|
|
|
|
## Schedules / Triggers
|
|
|
|
| Trigger | Frecuencia | Descripción |
|
|
| -------------------------------- | ---------- | ---------------------------------------------------- |
|
|
| Webhook POST `/cruce-cuentas-gt` | On demand | Disparado por el frontend al ejecutar un cruce |
|
|
| Consulta BambooHR API | On demand | Ejecutada por n8n durante el cruce |
|
|
| Guardado en Supabase | On demand | Registra metadata e historial de la ejecución |
|
|
| Generación de reporte | On demand | Crea archivo Excel o Google Sheets final |
|
|
| Notificación final | On demand | Avisa si el cruce terminó o falló |
|
|
| Consulta de históricos | Manual | El frontend consulta registros guardados en Supabase |
|
|
|
|
---
|
|
|
|
## Estructura Actual del Repositorio
|
|
|
|
```txt
|
|
Cruce-De-Cuentas-GLM-Guatemala/
|
|
|-- README.md
|
|
|-- .env.example
|
|
|-- .gitignore
|
|
|-- index.html
|
|
|-- metadata.json
|
|
|-- package.json
|
|
|-- package-lock.json
|
|
|-- tsconfig.json
|
|
|-- vite.config.ts
|
|
|
|
|
|-- src/
|
|
| |-- App.tsx
|
|
| |-- main.tsx
|
|
| |-- index.css
|
|
| |-- types.ts
|
|
| |
|
|
| └-- components/
|
|
| |-- Dashboard.tsx
|
|
| |-- History.tsx
|
|
| |-- Login.tsx
|
|
| |-- Sidebar.tsx
|
|
| └-- Toast.tsx
|
|
|
|
|
└-- dist/
|
|
└-- index.html
|
|
```
|
|
|
|
---
|
|
|
|
## Estructura Objetivo del Repositorio
|
|
|
|
```txt
|
|
cruce-cuentas-gt/
|
|
|-- README.md
|
|
|-- .env.example
|
|
|-- package.json
|
|
|-- package-lock.json
|
|
|
|
|
|-- src/
|
|
| |-- app/
|
|
| |-- components/
|
|
| |-- lib/
|
|
| |-- services/
|
|
| |-- utils/
|
|
| └-- types/
|
|
|
|
|
|-- n8n/
|
|
| |-- workflow-cruce-cuentas-gt.json
|
|
| └-- README.md
|
|
|
|
|
|-- docs/
|
|
| |-- PRD.md
|
|
| |-- WORKFLOW.md
|
|
| |-- N8N_FLOW.md
|
|
| |-- FIELD_MAPPING.md
|
|
| |-- SUPABASE_SCHEMA.md
|
|
| |-- TEST_CASES.md
|
|
| └-- architecture.png
|
|
|
|
|
|-- supabase/
|
|
| |-- schema.sql
|
|
| └-- migrations/
|
|
|
|
|
|-- samples/
|
|
| |-- payroll-template.xlsx
|
|
| |-- bank-template.csv
|
|
| └-- exceptions-template.xlsx
|
|
|
|
|
|-- CHANGELOG.md
|
|
└-- DECISIONS.md
|
|
```
|
|
|
|
---
|
|
|
|
## Configuración y Setup
|
|
|
|
### Prerrequisitos
|
|
|
|
* Node.js v18 o superior.
|
|
* npm.
|
|
* Acceso al repositorio.
|
|
* Acceso al workflow de n8n.
|
|
* Credencial de BambooHR configurada en n8n.
|
|
* Proyecto Supabase configurado para históricos.
|
|
* Archivo `.env.local` configurado si aplica.
|
|
|
|
### Instalación
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Ejecutar en desarrollo
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
La aplicación estará disponible en:
|
|
|
|
```txt
|
|
http://localhost:3000
|
|
```
|
|
|
|
### Build de producción
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### Preview del build
|
|
|
|
```bash
|
|
npm run preview
|
|
```
|
|
|
|
### Validar TypeScript
|
|
|
|
```bash
|
|
npm run lint
|
|
```
|
|
|
|
### Limpiar build
|
|
|
|
```bash
|
|
npm run clean
|
|
```
|
|
|
|
---
|
|
|
|
## Variables de Entorno
|
|
|
|
El proyecto incluye actualmente un `.env.example` heredado del setup inicial de AI Studio.
|
|
|
|
```env
|
|
GEMINI_API_KEY="MY_GEMINI_API_KEY"
|
|
APP_URL="MY_APP_URL"
|
|
```
|
|
|
|
### Estado actual
|
|
|
|
* `GEMINI_API_KEY` existe en el ejemplo, pero no hay integración real activa con Gemini en el frontend actual.
|
|
* `APP_URL` puede usarse para despliegue o callbacks futuros.
|
|
* Las variables reales no deben commitearse.
|
|
|
|
### Variables futuras sugeridas para frontend
|
|
|
|
```env
|
|
APP_ENV=development
|
|
APP_URL=http://localhost:3000
|
|
|
|
# n8n
|
|
VITE_N8N_CRUCE_GT_WEBHOOK_URL=
|
|
|
|
# Supabase
|
|
VITE_SUPABASE_URL=
|
|
VITE_SUPABASE_ANON_KEY=
|
|
|
|
# Auth
|
|
VITE_GOOGLE_CLIENT_ID=
|
|
```
|
|
|
|
### Variables y credenciales dentro de n8n
|
|
|
|
Estas credenciales deben vivir en n8n, no en el frontend.
|
|
|
|
```txt
|
|
BAMBOOHR_API_KEY
|
|
BAMBOOHR_SUBDOMAIN
|
|
BAMBOOHR_BASE_URL
|
|
SUPABASE_SERVICE_ROLE_KEY
|
|
GOOGLE_DRIVE_FOLDER_ID
|
|
GOOGLE_SHEETS_OUTPUT_FOLDER_ID
|
|
GMAIL_CREDENTIAL
|
|
GOOGLE_CHAT_WEBHOOK
|
|
```
|
|
|
|
|
|
---
|
|
|
|
## Supabase Schema Objetivo
|
|
|
|
### Tabla: reconciliation_runs
|
|
|
|
```sql
|
|
create table reconciliation_runs (
|
|
id uuid primary key default gen_random_uuid(),
|
|
country text not null default 'GT',
|
|
period_month int not null,
|
|
period_year int not null,
|
|
run_type text not null,
|
|
status text not null,
|
|
executed_by text,
|
|
started_at timestamptz default now(),
|
|
completed_at timestamptz,
|
|
total_payroll_rows int default 0,
|
|
total_bank_rows int default 0,
|
|
total_bamboo_rows int default 0,
|
|
total_matches int default 0,
|
|
total_differences int default 0,
|
|
total_critical_findings int default 0,
|
|
report_url text,
|
|
error_message text
|
|
);
|
|
```
|
|
|
|
### Tabla: reconciliation_findings
|
|
|
|
```sql
|
|
create table reconciliation_findings (
|
|
id uuid primary key default gen_random_uuid(),
|
|
run_id uuid references reconciliation_runs(id),
|
|
employee_number text,
|
|
employee_name text,
|
|
finding_category text,
|
|
severity text,
|
|
confidence_level text,
|
|
payroll_amount numeric,
|
|
bank_amount numeric,
|
|
difference_amount numeric,
|
|
comment text,
|
|
recommended_action text,
|
|
created_at timestamptz default now()
|
|
);
|
|
```
|
|
|
|
### Tabla: reconciliation_files
|
|
|
|
```sql
|
|
create table reconciliation_files (
|
|
id uuid primary key default gen_random_uuid(),
|
|
run_id uuid references reconciliation_runs(id),
|
|
file_type text not null,
|
|
file_name text not null,
|
|
file_url text,
|
|
uploaded_by text,
|
|
uploaded_at timestamptz default now()
|
|
);
|
|
```
|
|
|
|
### Tabla: audit_logs
|
|
|
|
```sql
|
|
create table audit_logs (
|
|
id uuid primary key default gen_random_uuid(),
|
|
user_email text,
|
|
action text not null,
|
|
entity_type text,
|
|
entity_id text,
|
|
details jsonb,
|
|
created_at timestamptz default now()
|
|
);
|
|
```
|
|
|
|
---
|
|
|
|
## Cómo Funciona Actualmente
|
|
|
|
```txt
|
|
1. El usuario abre la app.
|
|
2. La app muestra una pantalla de login visual.
|
|
3. El usuario presiona “Continuar con Google”.
|
|
4. La app simula el acceso.
|
|
5. El usuario entra al dashboard.
|
|
6. El usuario carga un archivo de nómina.
|
|
7. El usuario carga un archivo bancario.
|
|
8. La app valida visualmente el formato del archivo.
|
|
9. El usuario ejecuta el cruce.
|
|
10. La app simula el procesamiento.
|
|
11. La app muestra resultados demo.
|
|
12. El usuario puede filtrar entre todos, coincidencias y discrepancias.
|
|
13. El usuario puede navegar a reportes históricos simulados.
|
|
```
|
|
|
|
---
|
|
|
|
## Cómo Debe Funcionar en MVP
|
|
|
|
```txt
|
|
1. El usuario abre la app.
|
|
2. El usuario inicia sesión.
|
|
3. El usuario selecciona período y tipo de cruce.
|
|
4. El usuario sube archivo de nómina.
|
|
5. El usuario sube archivo(s) de banco.
|
|
6. La app envía todo a n8n.
|
|
7. n8n crea un registro en Supabase con status "processing".
|
|
8. n8n consulta BambooHR API.
|
|
9. n8n procesa y cruza las tres fuentes.
|
|
10. n8n genera el reporte final.
|
|
11. n8n guarda el resumen y enlace en Supabase.
|
|
12. n8n responde al frontend.
|
|
13. La app muestra resumen y botón hacia archivo de Google Sheets.
|
|
14. El cruce queda disponible en Reportes Históricos.
|
|
```
|
|
|
|
---
|
|
|
|
## Decisions Log
|
|
|
|
### DEC-001 — Uso de React + Vite para el prototipo
|
|
|
|
* Fecha: Junio 2026.
|
|
* Contexto: Se necesitaba construir rápidamente un prototipo visual del portal.
|
|
* Opciones consideradas: React + Vite vs Next.js.
|
|
* Decisión: Usar React + Vite.
|
|
* Razón: Permite desarrollo rápido, build ligero y validación visual eficiente.
|
|
|
|
### DEC-002 — Guatemala como primer portal activo
|
|
|
|
* Fecha: Junio 2026.
|
|
* Contexto: El cruce se está validando inicialmente para Guatemala.
|
|
* Opciones consideradas: Activar todos los países vs iniciar con Guatemala.
|
|
* Decisión: Activar solo Guatemala en el MVP.
|
|
* Razón: Reduce complejidad inicial y permite validar la lógica antes de escalar.
|
|
|
|
### DEC-003 — Employee Number como identificador principal
|
|
|
|
* Fecha: Junio 2026.
|
|
* Contexto: El identificador debe ser consistente con BambooHR.
|
|
* Decisión: Usar Employee Number como identificador principal.
|
|
* Razón: Es el identificador oficial dentro de BambooHR y facilita la integración regional.
|
|
|
|
### DEC-004 — n8n como backend operativo del cruce
|
|
|
|
* Fecha: Junio 2026.
|
|
* Contexto: El proyecto ya cuenta con acceso a BambooHR API y el procesamiento puede orquestarse desde n8n.
|
|
* Opciones consideradas: Backend tradicional vs flujo n8n.
|
|
* Decisión: Usar n8n como motor principal del cruce.
|
|
* Razón: Reduce complejidad técnica, acelera el desarrollo y aprovecha la infraestructura existente de automatización.
|
|
|
|
### DEC-005 — Supabase solo para históricos y auditoría
|
|
|
|
* Fecha: Junio 2026.
|
|
* Contexto: El cruce será procesado por n8n, pero se necesita guardar historial y trazabilidad.
|
|
* Opciones consideradas: No usar base de datos vs usar Supabase como base principal vs usar Supabase solo para metadata.
|
|
* Decisión: Usar Supabase para Reportes Históricos, logs, auditoría y enlaces.
|
|
* Razón: Permite trazabilidad sin duplicar lógica de negocio ni almacenar datos sensibles innecesarios.
|
|
|
|
### DEC-006 — Reporte enfocado en hallazgos
|
|
|
|
* Fecha: Junio 2026.
|
|
* Contexto: Los reportes con demasiados casos OK dificultan la revisión.
|
|
* Opciones consideradas: Mostrar todos los registros vs priorizar irregularidades.
|
|
* Decisión: Priorizar diferencias, irregularidades y casos que requieren revisión.
|
|
* Razón: Facilita el análisis operativo y acelera la toma de decisiones.
|
|
|
|
---
|
|
|
|
## Contactos del Proyecto
|
|
|
|
| Rol | Nombre |
|
|
| ----------------------- | ------------- |
|
|
| Product Owner | Máximo Gomez |
|
|
| IT Manager | Luis Matos |
|
|
| Developer | Isaac Aracena |
|
|
| Nómina / Administración | Yanelly Madera |
|
|
|
|
---
|
|
|
|
## Definition of Done
|
|
|
|
* Prototipo visual validado.
|
|
* README completo y actualizado.
|
|
* Variables de entorno documentadas en `.env.example`.
|
|
* Flujo de carga de archivos validado.
|
|
* Estados visuales de error y éxito probados.
|
|
* Criterios de cruce real documentados.
|
|
* Employee Number definido como identificador principal.
|
|
* Datos demo removidos o restringidos antes del MVP productivo.
|
|
* Webhook de n8n configurado.
|
|
* Credencial BambooHR configurada en n8n.
|
|
* Workflow de n8n exportado en `/n8n/workflow-cruce-cuentas-gt.json`.
|
|
* Cruce real ejecutado desde n8n.
|
|
* Reporte final generado correctamente.
|
|
* Supabase guardando Reportes Históricos.
|
|
* Audit log básico funcionando.
|
|
* Plantillas de archivos documentadas.
|
|
* Código commiteado y pusheado al repositorio.
|
|
* Probado en ambiente real, no solo local.
|
|
* Luis Matos validó el output.
|
|
* Product Owner aprobó el resultado final.
|
|
|
|
---
|
|
|
|
## Notas Finales
|
|
|
|
Este proyecto se encuentra en etapa de prototipo frontend. La aplicación actual sirve para validar la experiencia de usuario y la estructura visual del flujo de cruce de cuentas de Guatemala.
|
|
|
|
La arquitectura objetivo no contempla un backend tradicional. El procesamiento real será ejecutado mediante n8n, utilizando BambooHR API como fuente oficial de empleados y Supabase como base liviana para históricos, auditoría y enlaces de reportes generados.
|