948 lines
27 KiB
Markdown
948 lines
27 KiB
Markdown
# 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.
|