399 lines
12 KiB
Markdown
399 lines
12 KiB
Markdown
# 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
|
|
|
|
```txt
|
|
Usuario autorizado
|
|
↓
|
|
Google Login
|
|
↓
|
|
Supabase Auth
|
|
↓
|
|
Portal Central Cruce de Cuentas GLM
|
|
↓
|
|
Tarjetas por país
|
|
↓
|
|
Modal informativo / redirección futura
|
|
```
|
|
|
|
### Arquitectura objetivo
|
|
|
|
```txt
|
|
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.
|
|
|
|
```txt
|
|
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
|
|
|
|
1. Solo usuarios autorizados pueden acceder al portal.
|
|
|
|
2. El usuario debe iniciar sesión mediante Google.
|
|
|
|
3. La autenticación se gestiona con Supabase Auth.
|
|
|
|
4. Los correos autorizados se validan actualmente desde el frontend.
|
|
|
|
5. El portal debe mostrar todos los países disponibles.
|
|
|
|
6. Guatemala debe mostrarse como el primer módulo iniciado.
|
|
|
|
7. Los países no implementados deben mostrarse como pendientes, no iniciados o deshabilitados.
|
|
|
|
8. Al seleccionar un país activo, el sistema debe redireccionar al portal correspondiente.
|
|
|
|
9. Al seleccionar un país no activo, el sistema debe informar que el módulo aún no está disponible.
|
|
|
|
10. Este portal no debe procesar archivos de nómina ni banco.
|
|
|
|
11. Este portal no debe ejecutar conciliaciones.
|
|
|
|
12. Este portal no debe almacenar archivos sensibles.
|
|
|
|
13. Cada portal país debe manejar su propia lógica, flujo de n8n y reglas de cruce.
|
|
|
|
14. Las URLs de redirección deben mantenerse documentadas y controladas.
|
|
|
|
15. 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:
|
|
|
|
```sql
|
|
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`.
|
|
|
|
```env
|
|
VITE_SUPABASE_URL="https://TU-PROYECTO.supabase.co"
|
|
VITE_SUPABASE_ANON_KEY="TU_SUPABASE_ANON_KEY"
|
|
```
|
|
|
|
|
|
---
|
|
|
|
## Instalación / Ejecución Local
|
|
|
|
### Instalar dependencias
|
|
|
|
```bash
|
|
npm install
|
|
```
|
|
|
|
### Ejecutar en desarrollo
|
|
|
|
```bash
|
|
npm run dev
|
|
```
|
|
|
|
La aplicación estará disponible en:
|
|
|
|
```txt
|
|
http://localhost:3000
|
|
```
|
|
|
|
### Generar build de producción
|
|
|
|
```bash
|
|
npm run build
|
|
```
|
|
|
|
### Preview del build
|
|
|
|
```bash
|
|
npm run preview
|
|
```
|
|
|
|
### Validar TypeScript
|
|
|
|
```bash
|
|
npm run lint
|
|
```
|
|
|
|
### Limpiar build
|
|
|
|
```bash
|
|
npm run clean
|
|
```
|
|
|
|
---
|
|
|
|
## Configuración de Vite
|
|
|
|
El proyecto está configurado para desplegarse bajo la ruta:
|
|
|
|
```txt
|
|
/cruce-cuentas/
|
|
```
|
|
|
|
En `vite.config.ts`:
|
|
|
|
```ts
|
|
base: "/cruce-cuentas/"
|
|
```
|
|
|
|
URL de producción esperada:
|
|
|
|
```txt
|
|
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.
|
|
|
|
---
|