Actualizar README.md
This commit is contained in:
@@ -0,0 +1,947 @@
|
||||
# Cruce de Cuentas GT
|
||||
|
||||
> 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.
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
| Fecha de Inicio | A completar |
|
||||
| Fecha de Cierre Estimada | A completar |
|
||||
| Ciclo Shape Up | A completar |
|
||||
| Board de Ejecución | A completar |
|
||||
| PRD del Proyecto | A completar |
|
||||
|
||||
---
|
||||
|
||||
## Objetivo
|
||||
|
||||
### 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.
|
||||
|
||||
### Solución implementada
|
||||
|
||||
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.
|
||||
|
||||
### 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 la base del portal de Cruce de Cuentas GT.
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
|
||||
* 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.
|
||||
|
||||
### Funcionalidades objetivo
|
||||
|
||||
* Portal centralizado por país.
|
||||
* Portal Guatemala activo.
|
||||
* Portales de otros países deshabilitados visualmente.
|
||||
* Consulta directa a BambooHR API.
|
||||
* 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.
|
||||
|
||||
---
|
||||
|
||||
## Alcance del MVP
|
||||
|
||||
El MVP debe enfocarse en el cruce de cuentas de Guatemala.
|
||||
|
||||
### Incluido en MVP
|
||||
|
||||
* Portal de Guatemala activo.
|
||||
* Selección de mes y año.
|
||||
* Selección de tipo de cruce:
|
||||
|
||||
* Mensual.
|
||||
* Quincena 15.
|
||||
* Quincena 30.
|
||||
* Carga de archivo de nómina.
|
||||
* Carga de archivo o archivos bancarios.
|
||||
* Consulta o carga de datos de BambooHR.
|
||||
* Ejecución del cruce.
|
||||
* Generación de reporte final.
|
||||
* Visualización de diferencias.
|
||||
* Descarga del resultado.
|
||||
|
||||
### Fuera de alcance para MVP
|
||||
|
||||
* Automatización completa para todos los países.
|
||||
* Edición manual de datos desde la app.
|
||||
* Conexión directa con sistemas bancarios.
|
||||
* Envío automático a terceros.
|
||||
* Aprobaciones de nómina.
|
||||
* Sustitución oficial del proceso contable sin validación humana.
|
||||
|
||||
---
|
||||
|
||||
## Arquitectura
|
||||
|
||||
### Arquitectura actual
|
||||
|
||||
```txt
|
||||
Usuario
|
||||
↓
|
||||
App Web Cruce de Cuentas GT
|
||||
↓
|
||||
Carga de archivos / Datos de entrada
|
||||
↓
|
||||
Motor de validación
|
||||
↓
|
||||
Reporte de diferencias
|
||||
```
|
||||
|
||||
### Arquitectura objetivo
|
||||
|
||||
```txt
|
||||
Usuario autorizado
|
||||
↓
|
||||
App Web Centralizada
|
||||
↓
|
||||
Portal Guatemala
|
||||
↓
|
||||
n8n / Backend
|
||||
↓
|
||||
BambooHR API + Nómina + Banco
|
||||
↓
|
||||
Motor de conciliación
|
||||
↓
|
||||
Reporte final en Excel / Google Sheets
|
||||
↓
|
||||
Notificación al responsable
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stack Tecnológico
|
||||
|
||||
| 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 / EasyPanel | Hosting de servicios internos |
|
||||
|
||||
---
|
||||
|
||||
## Integraciones Externas
|
||||
|
||||
| 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 |
|
||||
|
||||
---
|
||||
|
||||
## Reglas de Negocio
|
||||
|
||||
1. El identificador principal del empleado debe ser `Employee Number` de BambooHR.
|
||||
|
||||
2. No se debe usar DPI como identificador principal del reporte.
|
||||
|
||||
3. El cruce debe comparar empleados entre BambooHR, nómina y banco.
|
||||
|
||||
4. Un empleado activo en BambooHR con monto en nómina debe tener pago bancario correspondiente, salvo excepción documentada.
|
||||
|
||||
5. Un pago bancario sin empleado relacionado en nómina debe marcarse como pago no conciliado.
|
||||
|
||||
6. Un pago bancario a una cuenta no reconocida debe marcarse como posible irregularidad.
|
||||
|
||||
7. Un empleado inactivo en BambooHR con pago en nómina o banco debe marcarse para revisión.
|
||||
|
||||
8. Las diferencias pequeñas por redondeo pueden tolerarse según la tolerancia configurada.
|
||||
|
||||
9. La tolerancia sugerida para diferencias monetarias es `0.02`.
|
||||
|
||||
10. Las variaciones de nombres no deben considerarse irregularidad automáticamente.
|
||||
|
||||
11. El sistema debe normalizar nombres para reducir falsos positivos.
|
||||
|
||||
12. La coincidencia puede realizarse por:
|
||||
|
||||
* Employee Number.
|
||||
* Cuenta bancaria.
|
||||
* Nombre normalizado.
|
||||
* Monto.
|
||||
* Combinación de nombre + monto.
|
||||
|
||||
13. Las cuentas con moneda especial o excepción deben manejarse en una tabla de excepciones.
|
||||
|
||||
14. Si la moneda no se detecta de forma confiable, el sistema debe marcar el caso para revisión.
|
||||
|
||||
15. El reporte final debe priorizar hallazgos, diferencias e irregularidades, no llenar al usuario de casos correctos.
|
||||
|
||||
16. El resultado debe ser revisado por una persona responsable antes de tomar acciones operativas.
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|
||||
---
|
||||
|
||||
## Fuentes de Datos
|
||||
|
||||
### BambooHR
|
||||
|
||||
Fuente oficial para validar:
|
||||
|
||||
* Employee Number.
|
||||
* Nombre del empleado.
|
||||
* Estado del empleado.
|
||||
* Fecha de baja.
|
||||
* Puesto.
|
||||
* País.
|
||||
* Departamento.
|
||||
* Información laboral relevante.
|
||||
|
||||
### Nómina
|
||||
|
||||
Fuente para validar lo que debe pagarse:
|
||||
|
||||
* Employee Number.
|
||||
* Nombre completo.
|
||||
* Cuenta bancaria.
|
||||
* Periodo.
|
||||
* Moneda.
|
||||
* Salario.
|
||||
* Bonificaciones.
|
||||
* Deducciones.
|
||||
* Neto a pagar.
|
||||
* Estatus.
|
||||
* Comentarios.
|
||||
|
||||
### Banco
|
||||
|
||||
Fuente para validar lo que realmente se pagó:
|
||||
|
||||
* Fecha de pago.
|
||||
* Cuenta destino.
|
||||
* Nombre asociado.
|
||||
* Monto pagado.
|
||||
* Moneda.
|
||||
* Referencia bancaria.
|
||||
* Descripción o concepto.
|
||||
|
||||
---
|
||||
|
||||
## Normalización de Datos
|
||||
|
||||
El sistema debe limpiar y estandarizar los datos antes de cruzarlos.
|
||||
|
||||
### 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
|
||||
|
||||
Debe contemplar:
|
||||
|
||||
* Cuentas como texto.
|
||||
* Ceros a la izquierda.
|
||||
* Espacios.
|
||||
* Guiones.
|
||||
* Formatos distintos entre banco y nómina.
|
||||
|
||||
---
|
||||
|
||||
## Criterios de Coincidencia
|
||||
|
||||
El motor de cruce debe evaluar coincidencias con distintos niveles de confianza.
|
||||
|
||||
### 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.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
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
|
||||
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
|
||||
|
||||
```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.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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 |
|
||||
|
||||
---
|
||||
|
||||
## Configuración y Setup
|
||||
|
||||
### Prerrequisitos
|
||||
|
||||
* Node.js v18 o superior.
|
||||
* pnpm o 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.
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```bash
|
||||
git clone https://gitea.glm.com/glm-it/cruce-cuentas-gt.git
|
||||
cd cruce-cuentas-gt
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
La aplicación estará disponible en:
|
||||
|
||||
```txt
|
||||
http://localhost:3000
|
||||
```
|
||||
|
||||
### Build de producción
|
||||
|
||||
```bash
|
||||
pnpm run build
|
||||
```
|
||||
|
||||
### Ejecutar build
|
||||
|
||||
```bash
|
||||
pnpm run start
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Estructura del Repositorio
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Esquema de Base de Datos Objetivo
|
||||
|
||||
Tablas sugeridas:
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### Tabla: currency_exceptions
|
||||
|
||||
```txt
|
||||
id
|
||||
bank_account
|
||||
employee_name
|
||||
correct_currency
|
||||
comment
|
||||
created_at
|
||||
updated_at
|
||||
```
|
||||
|
||||
### Tabla: audit_logs
|
||||
|
||||
```txt
|
||||
id
|
||||
user_id
|
||||
action
|
||||
entity_type
|
||||
entity_id
|
||||
old_value
|
||||
new_value
|
||||
created_at
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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:
|
||||
|
||||
```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.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 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
|
||||
|
||||
```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.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Decisions Log
|
||||
|
||||
### DEC-001 — Guatemala como primer portal activo
|
||||
|
||||
* Fecha: A completar.
|
||||
* Contexto: El proceso de 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
|
||||
|
||||
* Fecha: A completar.
|
||||
* Contexto: El identificador debe ser consistente con BambooHR y evitar dependencias de documentos locales.
|
||||
* 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
|
||||
|
||||
* 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.
|
||||
|
||||
### DEC-004 — Reportar solo hallazgos relevantes
|
||||
|
||||
* 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.
|
||||
* 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 | Contacto |
|
||||
| ----------------------- | ------------- | ----------- |
|
||||
| Product Owner | A completar | A completar |
|
||||
| IT Manager | Luis Matos | A completar |
|
||||
| Developer | Isaac Aracena | A completar |
|
||||
| RRHH Guatemala | A completar | A completar |
|
||||
| Nómina / Administración | A completar | A completar |
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
* Todos los criterios principales del cruce Guatemala validados.
|
||||
* Código commiteado y pusheado al repositorio.
|
||||
* 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.
|
||||
* Reporte final generado correctamente.
|
||||
* Hallazgos clasificados correctamente.
|
||||
* Probado en ambiente real, no solo local.
|
||||
* Luis Matos validó el output.
|
||||
* Product Owner aprobó el resultado final.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
El sistema no reemplaza la revisión humana final, pero permite detectar diferencias de forma más rápida, ordenada y trazable.
|
||||
|
||||
Reference in New Issue
Block a user