From 2114c146c16553b259786f1c769379c9c810c1ef Mon Sep 17 00:00:00 2001 From: Isaac_Aracena Date: Fri, 12 Jun 2026 21:19:47 +0000 Subject: [PATCH] Actualizar README.md --- README.md | 1132 +++++++++++++++++++++++++++-------------------------- 1 file changed, 583 insertions(+), 549 deletions(-) diff --git a/README.md b/README.md index f72e001..761aba4 100644 --- a/README.md +++ b/README.md @@ -1,19 +1,19 @@ -# Cruce de Cuentas GT +# Cruce de Cuentas GLM - Guatemala -> Aplicación interna para cruzar información de BambooHR, nómina y banco en Guatemala, detectando diferencias, pagos no conciliados e irregularidades antes del cierre de nómina. +> 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 GT | -| Área | RRHH / Nómina / Administración | -| Estado | En Progreso / Prototipo funcional | -| Developer Principal | Isaac Aracena | -| IT Manager | Luis Matos | -| Product Owner | Máximo Gómez | +| 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 | --- @@ -22,113 +22,136 @@ ### Problema que resuelve -Actualmente, el cruce entre empleados activos en BambooHR, archivo de nómina y pagos realizados por banco 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 existen en BambooHR. +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 implementada +### Solución propuesta -Cruce de Cuentas GT centraliza el análisis de nómina de Guatemala en una aplicación web que permite cargar o consultar las fuentes necesarias, ejecutar validaciones automáticas y generar un reporte de diferencias e irregularidades para revisión del equipo responsable. +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 +* Equipo de RRHH Guatemala. +* Equipo de Nómina. +* Administración / Finanzas. +* IT. +* Gerencia responsable de control interno. --- ## Estado Actual del Proyecto -Este repositorio contiene la base del portal de Cruce de Cuentas GT. +Este repositorio contiene actualmente un **prototipo frontend** generado inicialmente desde Antigravity / AI Studio. -El objetivo del proyecto es convertir el proceso manual de validación de nómina en una herramienta interna más segura, trazable y fácil de usar. +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. -En esta etapa, el enfoque principal es Guatemala. Los demás países o portales pueden quedar visibles como módulos futuros, pero deshabilitados hasta que su lógica sea definida y validada. --- ## Características Principales -### Funcionalidades principales +### Funcionalidades del prototipo -* Selección de país, mes, año y tipo de cruce. -* Cruce de empleados contra BambooHR. -* Cruce de nómina contra archivo bancario. -* Validación de montos pagados vs montos esperados. -* Detección de empleados no encontrados en BambooHR. -* Detección de pagos bancarios no conciliados. -* Detección de empleados inactivos con pago. -* Validación por cuenta bancaria. -* Validación por nombre normalizado. -* Validación por monto. -* Manejo de monedas y excepciones. -* Generación de reporte final de irregularidades. -* Descarga de archivo resultado para revisión. -* Base preparada para integración con n8n y BambooHR API. +* 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 por país. -* Portal Guatemala activo. -* Portales de otros países deshabilitados visualmente. -* Consulta directa a BambooHR API. +* Portal centralizado para el cruce de cuentas de Guatemala. +* Selección de mes, año y tipo de cruce. +* Cruce mensual, quincena 15 o quincena 30. * Carga de archivo de nómina. -* Carga de uno o varios CSV del banco. -* Cruce mensual o por quincena. -* Reporte ejecutivo de diferencias. -* Historial de cruces ejecutados. -* Control de usuarios y permisos. -* Registro de auditoría de ejecuciones. -* Alertas automáticas si se detectan irregularidades críticas. +* 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 en el cruce de cuentas de Guatemala. +El MVP debe enfocarse únicamente en Guatemala. ### Incluido en MVP -* Portal de Guatemala activo. -* Selección de mes y año. +* Portal Guatemala activo. +* Selección de período. * Selección de tipo de cruce: * Mensual. - * Quincena - + * Quincena 15. + * Quincena 30. * Carga de archivo de nómina. -* Carga de archivo o archivos bancarios. -* Consulta de BambooHR vía el API. -* Ejecución del cruce. -* Generación de reporte final. -* Visualización de diferencias. -* Descarga del resultado. +* 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 -* Automatización completa para todos los países. -* Edición manual de datos desde la app. -* Envío automático a terceros. -* Aprobaciones de nómina. -* Sustitución oficial del proceso contable sin validación humana. +* 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 +### Arquitectura actual del prototipo ```txt Usuario ↓ -App Web Cruce de Cuentas GT +React + Vite Frontend ↓ -Carga de archivos / Datos de entrada +Carga visual de archivos ↓ -Motor de validación +Cruce simulado con data demo ↓ -Reporte de diferencias +Tabla visual de resultados ``` ### Arquitectura objetivo @@ -136,49 +159,172 @@ Reporte de diferencias ```txt Usuario autorizado ↓ -App Web Centralizada +App Web Cruce de Cuentas GT ↓ -Portal Guatemala +Webhook n8n ↓ -n8n / Backend +n8n consulta BambooHR API ↓ -BambooHR API + Nómina + Banco +n8n procesa Nómina + Banco + BambooHR ↓ -Motor de conciliación +n8n genera reporte final ↓ -Reporte final en Excel / Google Sheets +n8n guarda metadata en Supabase ↓ -Notificación al responsable +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 ``` --- -## Stack Tecnológico +## Uso de Supabase -| Componente | Tecnología | Propósito | -| ------------------ | --------------------------------- | ----------------------------------------------------------- | -| Frontend | React / Vite o Next.js | Interfaz web del portal | -| Backend | Node.js / API / n8n | Procesamiento del cruce y orquestación | -| Automatización | n8n | Integración con BambooHR, archivos y generación de reportes | -| RRHH | BambooHR API | Fuente oficial de empleados | -| Archivos de nómina | Excel / CSV | Fuente de pagos esperados | -| Banco | CSV / Excel / PDF convertido | Fuente de pagos ejecutados | -| Reportes | Excel / Google Sheets | Salida del cruce y hallazgos | -| Base de datos | Supabase / PostgreSQL recomendado | Historial de ejecuciones, usuarios y auditoría | -| Infraestructura | Servidor GLM | Hosting de servicios internos | +Supabase no será el motor principal del cruce. Su uso recomendado es para persistencia liviana y trazabilidad. ---- +### Tablas sugeridas -## Integraciones Externas +```txt +users +reconciliation_runs +reconciliation_files +reconciliation_summary +reconciliation_findings +report_links +audit_logs +``` -| Sistema | Tipo de integración | Datos que fluyen | -| ------------------- | -------------------------- | ------------------------------------------------------------ | -| BambooHR | API REST | Empleados, estado, número de empleado, datos laborales | -| Archivo de nómina | Carga manual / Excel | Monto neto, cuenta, empleado, moneda, periodo | -| Banco | Carga manual / CSV / Excel | Pagos realizados, cuentas, montos, moneda | -| n8n | Webhook / Workflow | Orquestación del proceso y generación de salida | -| Google Sheets | API / Export | Reporte de resultados y revisión operativa | -| Gmail / Google Chat | OAuth / Webhook | Notificaciones futuras de cruce finalizado o irregularidades | +### 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. --- @@ -186,46 +332,44 @@ Notificación al responsable 1. El identificador principal del empleado debe ser `Employee Number` de BambooHR. -2. El cruce debe comparar empleados entre BambooHR, nómina y banco. +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 pago bancario correspondiente, salvo excepción documentada. +3. Un empleado activo en BambooHR con monto en nómina debe tener un pago bancario correspondiente. -4. Un pago bancario sin empleado relacionado en nómina debe marcarse como pago no conciliado. +4. Un pago bancario sin relación confiable con nómina debe marcarse como pago no conciliado. -5. Un pago bancario a una cuenta no reconocida debe marcarse como posible irregularidad. +5. Un empleado inactivo en BambooHR con pago debe marcarse como hallazgo crítico. -6. Un empleado inactivo en BambooHR con pago en nómina o banco debe marcarse para revisión. +6. Las variaciones de nombre no deben considerarse irregularidad automáticamente. -7. Las variaciones de nombres no deben considerarse irregularidad automáticamente. +7. El sistema debe normalizar nombres para reducir falsos positivos. -8. 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 coincidencia puede realizarse por: +9. La moneda debe validarse contra la nómina, el banco y las excepciones configuradas. - * Employee Number. - * Cuenta bancaria. - * Nombre normalizado. - * Monto. - * Combinación de nombre + monto. +10. El reporte final debe priorizar hallazgos relevantes, diferencias e irregularidades. -10. Las cuentas con moneda especial o excepción deben manejarse en una tabla de excepciones. +11. Los casos correctos pueden incluirse en una hoja de detalle, pero no deben saturar la vista principal. -11. Si la moneda no se detecta de forma confiable, el sistema debe marcar el caso para revisión. +12. Todo cruce ejecutado debe registrar usuario, fecha, archivos utilizados y resultado. -12. El reporte final debe priorizar hallazgos, diferencias e irregularidades, no llenar al usuario de casos correctos. +13. No se debe permitir la ejecución si falta una fuente crítica de datos. -13. El resultado debe ser revisado por una persona responsable antes de tomar acciones operativas. +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 15 | Cruce correspondiente a la primera quincena | -| Quincena 30 | Cruce correspondiente a la segunda quincena | -| Especial | Cruce puntual para archivos extraordinarios o reprocesos | +| Tipo de cruce | Descripción | +| ------------- | ----------------------------------------------------- | +| Mensual | Cruce completo del mes seleccionado | +| Quincena 15 | Cruce de la primera quincena | +| Quincena 30 | Cruce de la segunda quincena | +| Especial | Cruce puntual para reprocesos o casos extraordinarios | --- @@ -239,9 +383,10 @@ Fuente oficial para validar: * Nombre del empleado. * Estado del empleado. * Fecha de baja. -* Puesto. * País. * Departamento. +* Posición. +* Email. * Información laboral relevante. ### Nómina @@ -251,13 +396,13 @@ Fuente para validar lo que debe pagarse: * Employee Number. * Nombre completo. * Cuenta bancaria. -* Periodo. +* Período. * Moneda. * Salario. * Bonificaciones. * Deducciones. * Neto a pagar. -* Estatus. +* Estado. * Comentarios. ### Banco @@ -266,7 +411,7 @@ Fuente para validar lo que realmente se pagó: * Fecha de pago. * Cuenta destino. -* Nombre asociado. +* Nombre del beneficiario. * Monto pagado. * Moneda. * Referencia bancaria. @@ -276,7 +421,7 @@ Fuente para validar lo que realmente se pagó: ## Normalización de Datos -El sistema debe limpiar y estandarizar los datos antes de cruzarlos. +Antes de cruzar información, n8n debe limpiar y estandarizar los datos. ### Normalización de nombres @@ -311,7 +456,7 @@ Debe contemplar: * Redondeos. * Diferencias menores dentro de la tolerancia permitida. -### Normalización de cuentas +### Normalización de cuentas bancarias Debe contemplar: @@ -325,8 +470,6 @@ Debe contemplar: ## Criterios de Coincidencia -El motor de cruce debe evaluar coincidencias con distintos niveles de confianza. - ### Coincidencia alta ```txt @@ -358,54 +501,22 @@ Monto parecido ### Sin coincidencia ```txt -No existe relación confiable entre BambooHR, nómina y banco +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. --- -## Categorías de Hallazgos - -El reporte final debe clasificar los casos encontrados. - -| Categoría | Descripción | -| ---------------------------------- | -------------------------------------------------------------------------- | -| OK | Caso conciliado correctamente | -| Diferencia de monto | El monto de nómina no coincide con el monto pagado | -| Pago no encontrado en banco | Está en nómina, pero no aparece pagado | -| Pago bancario no conciliado | Está en banco, pero no aparece en nómina | -| Empleado no encontrado en BambooHR | Está en nómina o banco, pero no existe en BambooHR | -| Empleado inactivo con pago | Tiene fecha de baja o estado inactivo y aparece con pago | -| Cuenta bancaria diferente | La cuenta esperada no coincide con la cuenta pagada | -| Moneda inconsistente | La moneda no coincide o no pudo validarse | -| Posible duplicado | Hay más de un pago o registro asociado al mismo empleado | -| Requiere revisión manual | El sistema no tiene suficiente confianza para clasificarlo automáticamente | - ---- - -## Reporte de Salida +## Reporte de Salida Objetivo El sistema debe generar un reporte claro y accionable. -### Hojas sugeridas del Excel final - -```txt -Resumen Ejecutivo -Irregularidades -Diferencias de Monto -Pagos No Encontrados -Pagos Bancarios No Conciliados -Empleados Inactivos -Posibles Duplicados -Detalle Completo -Excepciones Aplicadas -``` ### Columnas sugeridas ```txt -Periodo +Período Tipo de Cruce Employee Number Empleado @@ -426,36 +537,119 @@ Acción Recomendada --- -## Flujo Principal +## Flujo Principal Objetivo ```txt -1. El usuario entra al portal central. -2. Selecciona el módulo Guatemala. -3. Selecciona mes, año y tipo de cruce. -4. Carga el archivo de nómina. -5. Carga uno o varios archivos del banco. -6. El sistema consulta o recibe los datos de BambooHR. -7. El motor normaliza empleados, cuentas, nombres, monedas y montos. -8. El sistema cruza BambooHR vs Nómina. -9. El sistema cruza Nómina vs Banco. -10. El sistema identifica diferencias e irregularidades. -11. El sistema genera un resumen ejecutivo. -12. El sistema genera el Excel final. -13. El usuario descarga el reporte. -14. Opcionalmente, el sistema registra la ejecución en historial. +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-gt` | On demand | Ejecuta el cruce cuando el usuario procesa archivos | -| Carga manual de archivos | On demand | Usuario sube nómina y banco | -| Consulta BambooHR | On demand | Obtiene datos actualizados de empleados | -| Notificación final | On demand | Avisa cuando el cruce terminó | -| Revisión de historial | Manual | Usuario consulta cruces anteriores | +| 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 +``` --- @@ -464,81 +658,23 @@ Acción Recomendada ### Prerrequisitos * Node.js v18 o superior. -* pnpm o npm. +* npm. * Acceso al repositorio. -* Acceso a BambooHR API. -* Acceso a n8n si el procesamiento se ejecuta vía workflow. -* Acceso a carpeta o fuente donde se reciben archivos de nómina y banco. -* Variables de entorno configuradas. -* Credenciales guardadas en el vault de GLM IT. +* Acceso al workflow de n8n. +* Credencial de BambooHR configurada en n8n. +* Proyecto Supabase configurado para históricos. +* Archivo `.env.local` configurado si aplica. ---- - -## Variables de Entorno - -Crear un archivo `.env` o `.env.local` basado en `.env.example`. - -```env -APP_ENV=development -APP_URL=http://localhost:3000 - -# BambooHR -BAMBOOHR_API_KEY= -BAMBOOHR_SUBDOMAIN= -BAMBOOHR_BASE_URL= - -# n8n -N8N_WEBHOOK_URL= -N8N_API_KEY= - -# Base de datos -DATABASE_URL= -SUPABASE_URL= -SUPABASE_ANON_KEY= -SUPABASE_SERVICE_ROLE_KEY= - -# Google / Reportes -GOOGLE_CLIENT_ID= -GOOGLE_CLIENT_SECRET= -GOOGLE_DRIVE_FOLDER_ID= -GOOGLE_SHEETS_OUTPUT_FOLDER_ID= - -# Seguridad -JWT_SECRET= -SESSION_SECRET= -``` - -> Nunca commitear credenciales reales al repositorio. Todas las llaves, tokens y secretos deben guardarse en el vault o gestor de credenciales definido por GLM IT. - ---- - -## Instalación / Deploy - -### Clonar repositorio +### Instalación ```bash -git clone https://gitea.glm.com/glm-it/cruce-cuentas-gt.git -cd cruce-cuentas-gt +npm install ``` -### Instalar dependencias - -```bash -pnpm install -``` - -### Configurar variables - -```bash -cp .env.example .env.local -``` - -Editar `.env.local` con las credenciales reales del ambiente correspondiente. - ### Ejecutar en desarrollo ```bash -pnpm run dev +npm run dev ``` La aplicación estará disponible en: @@ -550,380 +686,278 @@ http://localhost:3000 ### Build de producción ```bash -pnpm run build +npm run build ``` -### Ejecutar build +### Preview del build ```bash -pnpm run start +npm run preview +``` + +### Validar TypeScript + +```bash +npm run lint +``` + +### Limpiar build + +```bash +npm run clean ``` --- -## Estructura del Repositorio +## 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 -/cruce-cuentas-gt -|-- README.md -|-- .env.example -|-- package.json -|-- pnpm-lock.yaml -| -|-- /src -| |-- /app -| |-- /components -| |-- /lib -| |-- /services -| |-- /utils -| |-- /db -| | |-- schema.sql -| | └-- migrations -| └-- /types -| -|-- /n8n -| └-- workflow.json -| -|-- /docs -| |-- PRD.md -| |-- WORKFLOW.md -| |-- DATABASE_SCHEMA.md -| |-- FIELD_MAPPING.md -| |-- TEST_CASES.md -| └-- architecture.png -| -|-- /scripts -| |-- normalize-payroll.ts -| |-- normalize-bank.ts -| |-- bamboohr-sync.ts -| └-- generate-report.ts -| -|-- /samples -| |-- payroll-template.xlsx -| |-- bank-template.csv -| └-- exceptions-template.xlsx -| -|-- CHANGELOG.md -└-- DECISIONS.md +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 ``` + --- -## Esquema de Base de Datos Objetivo +## Supabase Schema Objetivo -Tablas sugeridas: +### Tabla: reconciliation_runs -```txt -users -countries -payroll_runs -payroll_rows -bank_transactions -bamboo_employees -reconciliation_results -reconciliation_findings -currency_exceptions -execution_logs -audit_logs -uploaded_files -``` - -### Tabla: payroll_runs - -```txt -id -country -period_month -period_year -run_type -status -created_by -created_at -completed_at -output_file_url -``` - -### Tabla: payroll_rows - -```txt -id -payroll_run_id -employee_number -employee_name -bank_account -currency -net_amount -status -raw_payload -created_at -``` - -### Tabla: bank_transactions - -```txt -id -payroll_run_id -transaction_date -bank_account -beneficiary_name -currency -amount -reference -description -raw_payload -created_at -``` - -### Tabla: bamboo_employees - -```txt -id -employee_number -employee_name -status -termination_date -country -department -position -email -raw_payload -synced_at +```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 -```txt -id -payroll_run_id -employee_number -employee_name -finding_category -severity -confidence_level -payroll_amount -bank_amount -difference_amount -comment -recommended_action -created_at +```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: currency_exceptions +### Tabla: reconciliation_files -```txt -id -bank_account -employee_name -correct_currency -comment -created_at -updated_at +```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 -```txt -id -user_id -action -entity_type -entity_id -old_value -new_value -created_at +```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 - -### Paso a paso - -1. El usuario selecciona Guatemala en el portal. -2. El usuario selecciona el periodo del cruce. -3. El usuario define si el cruce será mensual, quincena 15 o quincena 30. -4. El usuario carga el archivo de nómina. -5. El usuario carga el archivo o archivos del banco. -6. El sistema obtiene la data de BambooHR. -7. El sistema normaliza nombres, cuentas, monedas y montos. -8. El sistema cruza empleados de nómina contra BambooHR. -9. El sistema cruza pagos esperados contra pagos bancarios. -10. El sistema calcula diferencias. -11. El sistema clasifica hallazgos. -12. El sistema genera el reporte. -13. El usuario descarga el Excel final. -14. El sistema guarda historial y logs de ejecución. - ---- - -## Testing - -Casos de prueba mínimos: - -| Caso | Input | Output esperado | Estado | -| ------------------------------ | --------------------------------------------- | ------------------------------------------------- | ----------- | -| Caso feliz | BambooHR, nómina y banco coinciden | Reporte sin irregularidades críticas | A completar | -| Diferencia de monto | Monto de nómina distinto al banco | Hallazgo de diferencia de monto | A completar | -| Pago faltante | Empleado en nómina no aparece en banco | Hallazgo de pago no encontrado | A completar | -| Pago no conciliado | Pago en banco no aparece en nómina | Hallazgo de pago bancario no conciliado | A completar | -| Empleado no existe en BambooHR | Registro en nómina sin Employee Number válido | Hallazgo de empleado no encontrado | A completar | -| Empleado inactivo | Empleado con baja aparece con pago | Hallazgo de empleado inactivo con pago | A completar | -| Cuenta diferente | Cuenta de nómina no coincide con banco | Hallazgo de cuenta bancaria diferente | A completar | -| Moneda distinta | Moneda de banco distinta a nómina | Hallazgo de moneda inconsistente | A completar | -| Diferencia menor a tolerancia | Diferencia <= 0.02 | Caso marcado como conciliado o diferencia menor | A completar | -| Nombre con variación | Nombre parcial o con iniciales | Coincidencia aceptada si cuenta y monto coinciden | A completar | -| Archivo inválido | Archivo sin columnas requeridas | Error manejado y mensaje claro | A completar | -| API caída | BambooHR no responde | Error manejado, no se genera reporte incompleto | A completar | - ---- - -## Errores Conocidos y Troubleshooting - -| Error | Causa probable | Solución | -| ---------------------------------- | --------------------------------------- | --------------------------------------------------- | -| 401 Unauthorized BambooHR | API Key inválida o vencida | Renovar credencial y actualizar `.env` | -| Archivo no procesa | Formato incorrecto o columnas faltantes | Validar plantilla esperada | -| Montos aparecen como texto | Formato de Excel/CSV incorrecto | Normalizar columna antes del cruce | -| Cuentas pierden ceros iniciales | Excel interpreta cuenta como número | Leer cuentas como texto | -| Muchos falsos positivos por nombre | Nombres no normalizados | Revisar función de normalización | -| Moneda no detectada | Archivo no trae moneda clara | Revisar excepciones de moneda | -| Webhook no responde | n8n apagado o URL incorrecta | Revisar n8n Executions y variable `N8N_WEBHOOK_URL` | -| Output vacío | No llegaron archivos o el parser falló | Revisar logs de ejecución | -| Reporte incompleto | Error en una fuente de datos | Bloquear salida y mostrar error al usuario | -| Timeout | Archivo muy grande o servicio lento | Aumentar timeout o procesar en background | - ---- - -## Monitoreo - -Cuando el sistema esté operativo, revisar: - -* Ejecuciones de n8n. -* Logs de backend. -* Errores de BambooHR API. -* Archivos subidos. -* Cruces fallidos. -* Reportes generados. -* Hallazgos críticos. -* Historial de ejecuciones. -* Alertas enviadas. -* Tiempo promedio de procesamiento. - -### Output esperado - -Un cruce exitoso debe producir: +## Cómo Funciona Actualmente ```txt -1. Resumen ejecutivo. -2. Archivo Excel con hallazgos. -3. Detalle completo del cruce. -4. Clasificación de irregularidades. -5. Log de ejecución. -6. Enlace de descarga del resultado. +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. ``` --- -## Seguridad - -1. No se deben commitear archivos reales de nómina. -2. No se deben commitear archivos reales del banco. -3. No se deben commitear credenciales. -4. Los archivos de prueba deben ser anonimizados. -5. El acceso debe limitarse a usuarios autorizados. -6. Los reportes deben almacenarse en carpetas controladas. -7. Las acciones relevantes deben registrarse en audit log. -8. Los datos sensibles deben eliminarse o archivarse según política interna. - ---- - -## Changelog +## Cómo Debe Funcionar en MVP ```txt -[YYYY-MM-DD] v0.1 — Inicio del repositorio y documentación base. -[YYYY-MM-DD] v0.2 — Definición de reglas de negocio para cruce Guatemala. -[YYYY-MM-DD] v0.3 — Preparación de estructura para BambooHR, nómina y banco. +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 — Guatemala como primer portal activo +### DEC-001 — Uso de React + Vite para el prototipo * Fecha: A completar. -* Contexto: El proceso de cruce se está validando inicialmente para Guatemala. +* 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: A completar. +* 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-002 — Employee Number como identificador principal +### DEC-003 — Employee Number como identificador principal * Fecha: A completar. -* Contexto: El identificador debe ser consistente con BambooHR y evitar dependencias de documentos locales. +* Contexto: El identificador debe ser consistente con BambooHR. * Opciones consideradas: DPI vs Employee Number. * Decisión: Usar Employee Number como identificador principal. * Razón: Es el identificador oficial dentro de BambooHR y facilita la integración regional. -### DEC-003 — BambooHR como fuente oficial de empleados +### DEC-004 — n8n como backend operativo del cruce * Fecha: A completar. -* Contexto: El sistema necesita validar si un empleado existe y si está activo. -* Opciones consideradas: Archivo manual de empleados vs BambooHR API. -* Decisión: Usar BambooHR como fuente oficial. -* Razón: Reduce errores manuales y permite validar empleados activos, inactivos y bajas. +* 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 MVP y aprovecha la infraestructura existente de automatización. -### DEC-004 — Reportar solo hallazgos relevantes +### DEC-005 — Supabase solo para históricos y auditoría + +* Fecha: A completar. +* 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: A completar. * Contexto: Los reportes con demasiados casos OK dificultan la revisión. -* Opciones consideradas: Reporte completo de todos los registros vs reporte enfocado en irregularidades. +* 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. -### DEC-005 — Mantener tolerancia monetaria - -* Fecha: A completar. -* Contexto: Pueden existir diferencias pequeñas por redondeo o formato. -* Opciones consideradas: Coincidencia exacta vs tolerancia configurable. -* Decisión: Usar tolerancia sugerida de `0.02`. -* Razón: Reduce falsos positivos sin ocultar diferencias materiales. - -### DEC-006 — Manejar excepciones de moneda - -* Fecha: A completar. -* Contexto: Algunos empleados o cuentas pueden tener moneda distinta a la moneda por defecto. -* Opciones consideradas: Asumir moneda por defecto vs tabla de excepciones. -* Decisión: Mantener una tabla de excepciones de moneda. -* Razón: Evita clasificar erróneamente pagos válidos como irregularidades. - --- ## Contactos del Proyecto -| Rol | Nombre | -| ----------------------- | ------------- | -| Product Owner | Máximo Gómez | -| IT Manager | Luis Matos | -| Developer | Isaac Aracena | -| RRHH Guatemala | - | -| Nómina / Administración | - | +| Rol | Nombre | +| ----------------------- | ------------- | +| Product Owner | Máximo Gomez | +| IT Manager | Luis Matos | +| Developer | Isaac Aracena | +| Nómina / Administración | Yanelly Madera | --- ## Definition of Done -* Todos los criterios principales del cruce Guatemala validados. -* Código commiteado y pusheado al repositorio. +* Prototipo visual validado. * README completo y actualizado. * Variables de entorno documentadas en `.env.example`. -* Tests básicos pasando. -* Workflow de n8n exportado en `/n8n/workflow.json`, si aplica. -* Schema SQL documentado en `/src/db/schema.sql`, si aplica. -* Plantillas de archivos documentadas. -* Casos de prueba ejecutados con datos anonimizados. +* 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. -* Hallazgos clasificados 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. @@ -932,6 +966,6 @@ Un cruce exitoso debe producir: ## Notas Finales -Cruce de Cuentas GT busca reducir el riesgo operativo en el proceso de nómina de Guatemala mediante una validación automática entre BambooHR, nómina y banco. +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. -El sistema no reemplaza la revisión humana final, pero permite detectar diferencias de forma más rápida, ordenada y trazable. +La arquitectura objetivo no contempla un backend tradicional en el MVP. 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.