Isaac_Aracena/cruce-cuentas-glm-centralizado

Files

T

Isaac_Aracena a6e66e6a89 Actualizar README.md

2026-06-12 23:41:39 +00:00

12 KiB

Raw Blame History

Cruce de Cuentas GLM

Portal centralizado para acceder a los módulos de Cruce de Cuentas por país, permitiendo tener un único punto de entrada seguro para los portales regionales de conciliación.

Información General

Campo	Detalle
Proyecto	Cruce de Cuentas GLM
Área	Nómina
Estado	Prototipo funcional / Portal central
Developer Principal	Isaac Aracena
IT Manager	Luis Matos
Product Owner	Máximo Gómez

Objetivo

Problema que resuelve

Actualmente, los procesos de cruce de cuentas por país pueden quedar dispersos en diferentes aplicaciones, enlaces, flujos o repositorios. Esto dificulta el acceso ordenado, el control de permisos y la visibilidad de cuáles países tienen un portal activo, pendiente o en desarrollo.

Solución implementada

Cruce de Cuentas GLM funciona como un portal central de acceso. Desde esta aplicación, los usuarios autorizados pueden iniciar sesión con Google, visualizar los países disponibles y acceder al portal correspondiente de cada país.

Este repositorio no ejecuta el cruce de nómina ni procesa archivos bancarios. Su responsabilidad principal es centralizar el acceso y redireccionar a los portales operativos de cada país.

Usuarios / Beneficiarios

Equipo de Nómina.
IT.
Gerencia regional.
Usuarios autorizados que necesiten acceder a los portales de cruce por país.

Estado Actual del Proyecto

Este repositorio contiene un portal frontend centralizado desarrollado con React, Vite, TypeScript y Supabase Auth.

La aplicación permite:

Iniciar sesión con Google mediante Supabase Auth.
Validar correos autorizados.
Mostrar una pantalla central con países disponibles.
Visualizar tarjetas por país.
Identificar el portal de Guatemala como módulo iniciado.
Mostrar los demás países como módulos pendientes o no iniciados.
Preparar la navegación hacia los portales independientes de cada país.

Arquitectura

Arquitectura actual

Usuario autorizado
  ↓
Google Login
  ↓
Supabase Auth
  ↓
Portal Central Cruce de Cuentas GLM
  ↓
Tarjetas por país
  ↓
Modal informativo / redirección futura

Arquitectura objetivo

Usuario autorizado
  ↓
Portal Central Cruce de Cuentas GLM
  ↓
Selección de país
  ↓
Redirección al portal del país
  ↓
Portal específico ejecuta su propio flujo
  ↓
n8n / BambooHR / Banco / Nómina / Reportes

Stack Tecnológico

Componente	Tecnología	Propósito
Frontend	React 19	Interfaz del portal central
Build Tool	Vite	Desarrollo local y build de producción
Lenguaje	TypeScript	Tipado del frontend
Estilos	Tailwind CSS 4	Diseño visual
Animaciones	Motion	Transiciones y animaciones
Iconos	Lucide React	Iconografía
Autenticación	Supabase Auth	Login con Google
Package Manager	npm	Gestión de dependencias
Infraestructura	Servidor GLM	Hosting del portal

Integraciones

Integraciones actuales

Sistema	Tipo de integración	Uso
Supabase Auth	OAuth con Google	Autenticación de usuarios
Google Login	Provider de Supabase	Inicio de sesión corporativo
Frontend React	SPA	Portal visual centralizado

Integraciones futuras

Sistema	Tipo de integración	Uso
Portales por país	Redirección por URL	Enviar al usuario al portal correspondiente
Supabase Database	Opcional	Configurar países, URLs, estado y permisos desde base de datos
n8n	Indirecta	Cada portal país podrá disparar su propio flujo de cruce
BambooHR	Indirecta	Será usado por el flujo del país, no por este portal central

Regla Principal del Sistema

Este portal solo centraliza accesos.

Portal Central ≠ Motor de Cruce
Portal Central = Login + Selección de país + Redirección

La lógica operativa debe mantenerse separada por país para evitar mezclar reglas, formatos de nómina, monedas, bancos, excepciones y reportes.

Reglas de Negocio

Solo usuarios autorizados pueden acceder al portal.
El usuario debe iniciar sesión mediante Google.
La autenticación se gestiona con Supabase Auth.
Los correos autorizados se validan actualmente desde el frontend.
El portal debe mostrar todos los países disponibles.
Guatemala debe mostrarse como el primer módulo iniciado.
Los países no implementados deben mostrarse como pendientes, no iniciados o deshabilitados.
Al seleccionar un país activo, el sistema debe redireccionar al portal correspondiente.
Al seleccionar un país no activo, el sistema debe informar que el módulo aún no está disponible.
Este portal no debe procesar archivos de nómina ni banco.
Este portal no debe ejecutar conciliaciones.
Este portal no debe almacenar archivos sensibles.
Cada portal país debe manejar su propia lógica, flujo de n8n y reglas de cruce.
Las URLs de redirección deben mantenerse documentadas y controladas.
Cualquier cambio de permisos debe ser validado por IT.

Cualquier otro correo que inicie sesión con Google debe ser rechazado y cerrado automáticamente.

Nota: En una versión futura, esta validación debería moverse a una tabla de permisos en Supabase o a una política controlada por IT, para evitar mantener correos hardcodeados en el frontend.

Estado actual

El portal usa Supabase Auth para autenticación, pero no requiere una base de datos compleja para operar como portal central.

Uso opcional de Supabase Database

Si se desea evitar URLs hardcodeadas en el frontend, Supabase puede usarse para guardar configuración dinámica de portales.

Tabla sugerida:

create table country_portals (
  id uuid primary key default gen_random_uuid(),
  country_name text not null,
  country_code text not null unique,
  portal_url text,
  status text not null default 'pending',
  is_visible boolean not null default true,
  display_order int not null default 0,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

Campos sugeridos:

Campo	Descripción
country_name	Nombre del país
country_code	Código del país
portal_url	URL del portal específico
status	Estado del portal
is_visible	Define si se muestra o no en pantalla
display_order	Orden visual
created_at	Fecha de creación
updated_at	Fecha de actualización

Configuración y Setup

Prerrequisitos

Node.js v18 o superior.
npm.
Acceso al repositorio.
Proyecto Supabase configurado.
Supabase Auth con Google habilitado.
Variables de entorno configuradas.
URLs de redirección configuradas en Supabase.

Variables de Entorno

Crear un archivo .env.local en la raíz del proyecto basado en .env.example.

VITE_SUPABASE_URL="https://TU-PROYECTO.supabase.co"
VITE_SUPABASE_ANON_KEY="TU_SUPABASE_ANON_KEY"

Instalación / Ejecución Local

Instalar dependencias

npm install

Ejecutar en desarrollo

npm run dev

La aplicación estará disponible en:

http://localhost:3000

Generar build de producción

npm run build

Preview del build

npm run preview

Validar TypeScript

npm run lint

Limpiar build

npm run clean

Configuración de Vite

El proyecto está configurado para desplegarse bajo la ruta:

/cruce-cuentas/

En vite.config.ts:

base: "/cruce-cuentas/"

URL de producción esperada:

https://digitalcompass.agency/cruce-cuentas/

Supabase Auth

En Supabase Auth se debe configurar Google como proveedor de autenticación.

Decisions Log

DEC-001 — Crear un portal central en lugar de mezclar todos los cruces

Fecha: Junio 2026.
Contexto: Cada país puede tener reglas, bancos, formatos y flujos distintos.
Opciones consideradas: Un único sistema para todos los países vs portal central con módulos separados.
Decisión: Crear un portal central que redireccione a los portales por país.
Razón: Permite centralizar el acceso sin mezclar la lógica operativa de cada país.

DEC-002 — Usar Supabase Auth para el acceso

Fecha: Junio 2026.
Contexto: El portal necesita login seguro con usuarios autorizados.
Opciones consideradas: Login manual vs Google SSO vía Supabase.
Decisión: Usar Supabase Auth con Google.
Razón: Aprovecha autenticación existente, reduce complejidad y permite controlar acceso.

DEC-003 — Guatemala como primer país iniciado

Fecha: Junio 2026.
Contexto: El primer flujo operativo de cruce se está trabajando para Guatemala.
Opciones consideradas: Activar todos los países vs iniciar con Guatemala.
Decisión: Marcar Guatemala como primer módulo iniciado.
Razón: Permite validar la arquitectura antes de escalar a otros países.

DEC-004 — Separar portal central del motor de cruce

Fecha: Junio 2026.
Contexto: El portal central no debe cargar lógica pesada ni procesar datos sensibles.
Opciones consideradas: Procesar cruces desde este portal vs redireccionar a portales especializados.
Decisión: Este repositorio solo centraliza y redirecciona.
Razón: Mejora seguridad, mantenimiento y escalabilidad.

DEC-005 — Mantener países pendientes visibles

Fecha: Junio 2026.
Contexto: Se quiere mostrar la visión regional completa aunque solo algunos módulos estén activos.
Opciones consideradas: Ocultar países no activos vs mostrarlos como pendientes.
Decisión: Mostrar países pendientes con aviso de no iniciado.
Razón: Comunica el roadmap regional sin habilitar funciones incompletas.

Contactos del Proyecto

Rol	Nombre
Product Owner	Máximo Gomez
IT Manager	Luis Matos
Developer	Isaac Aracena
Usuarios autorizados	A completar

Definition of Done

README completo y actualizado.
Portal carga correctamente en local.
Portal carga correctamente en /cruce-cuentas/.
Supabase Auth configurado.
Google Login funcionando.
Correos autorizados validados.
Usuario no autorizado bloqueado.
Tarjetas de países visibles.
Guatemala configurado como módulo iniciado.
Países pendientes muestran aviso correcto.
Países activos redireccionan a su portal correspondiente.
Variables de entorno documentadas en .env.example.
Código commiteado y pusheado al repositorio.
Probado en ambiente real, no solo local.
Luis Matos validó el acceso.
Product Owner aprobó el resultado final.

12 KiB Raw Blame History