diff --git a/README.md b/README.md index e69de29..c3541a8 100644 --- a/README.md +++ b/README.md @@ -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.