diff --git a/README.md b/README.md index e69de29..1fd827b 100644 --- a/README.md +++ b/README.md @@ -0,0 +1,398 @@ +# 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. + +---