Inteligencia Operacional Cambiaso (IOC) - Frontend

Plataforma de Business Intelligence y Gestión Operacional desarrollada para Empresas Cambiaso. Este repositorio contiene el cliente web (SPA) que permite la visualización de dashboards, gestión de usuarios (RBAC) e ingesta de datos.

📋 Descripción del Proyecto

IOC Frontend es la interfaz de usuario que conecta a los tomadores de decisiones con los datos de producción. Implementa una arquitectura moderna basada en React 19 y TypeScript, enfocada en la velocidad, seguridad y experiencia de usuario.

Pilares Funcionales:

1. Visualización: Embedding seguro de Dashboards de Metabase mediante JWT firmados.
2. Gobernanza: Sistema de gestión de usuarios, roles y permisos (RBAC).
3. Ingesta de Datos: Interfaz para carga de archivos ETL con validación en tiempo real.
4. Inteligencia Artificial: Integración con Gemini AI para explicaciones narrativas de gráficos vía Streaming.

---

🛠 Stack Tecnológico

Basado en la sección 3.1 del Manual Técnico:

• Core: React 19, TypeScript, Vite.
• Estilos: TailwindCSS v4, clsx, tailwind-merge.
• Estado & Data Fetching: TanStack Query (vía Refine Core), Context API.
• Autenticación: Supabase Auth (GoTrue Client).
• Formularios: React Hook Form + Zod (Validación de esquemas).
• Componentes UI: Headless UI, Heroicons, ApexCharts, FullCalendar.
• Testing: Vitest + React Testing Library.

---

🚀 Instalación y Configuración

Prerrequisitos

• Node.js v20.x (LTS recomendado)
• npm v10.x+

Pasos

1. Clonar el repositorio:

   git clone https://github.com/tu-org/ioc-frontend.git
   cd ioc-frontend

2. Instalar dependencias:

   npm install

3. Configurar Variables de Entorno: Crea un archivo .env en la raíz del proyecto basándote en el siguiente esquema (NO uses valores reales en producción):

   # === SUPABASE AUTH ===
   VITE_SUPABASE_URL=https://tu-proyecto.supabase.co
   VITE_SUPABASE_ANON_KEY=tu-anon-key-publica
   
   # === BACKEND API ===
   # Desarrollo: http://localhost:8080
   # Producción: https://ioc-backend.onrender.com
   VITE_API_BASE_URL=http://localhost:8080
   
   # === METABASE CONFIGURATION ===
   VITE_DASHBOARD_GERENCIAL_ID=5
   VITE_DASHBOARD_OPERACIONAL_ID=3

4. Ejecutar en Desarrollo:

   npm run dev

   La aplicación estará disponible en http://localhost:5173.

---

📂 Estructura del Proyecto

src/
├── components/         # 90+ Componentes Reutilizables
│   ├── auth/           # Formularios de Login/Registro
│   ├── admin/          # Paneles de gestión (Usuarios, ETL)
│   ├── common/         # UI Kits (Botones, Modales, Tablas)
│   └── charts/         # Gráficos locales (ApexCharts)
├── pages/              # 28 Vistas de la aplicación
│   ├── Dashboard/      # Vistas principales
│   ├── admin/          # Vistas protegidas de administración
│   └── AuthPages/      # Login, Recovery, etc.
├── hooks/              # Custom Hooks (useAuth, useAiExplanation)
├── services/           # Comunicación con APIs (Axios)
├── context/            # Global State (Auth, Theme, Sidebar)
├── layout/             # Estructura principal (Sidebar + Header)
└── schemas/            # Validaciones Zod

---

🔑 Características Clave

1. Seguridad y RBAC

Implementación de rutas protegidas mediante RoleProtectedRoute.

• Admin: Acceso total (Configuración, ETL).
• Gerente: Acceso solo a Dashboards Estratégicos.
• Analista: Acceso a Dashboards Operacionales y descarga de reportes.

2. Integración con Metabase

El componente DashboardEmbed.tsx gestiona la solicitud de URLs firmadas al backend.

• Renovación automática de tokens.
• Redimensionamiento responsivo (iFrame).

3. Análisis con IA (Streaming)

Uso de Server-Sent Events (SSE) para recibir explicaciones generadas por Google Gemini en tiempo real, mejorando la percepción de velocidad del usuario.

4. Ingesta ETL

Módulo de carga de archivos con validación en el cliente (Frontend) antes de enviar al servidor:

• Validación de extensión (.txt).
• Verificación de cabeceras.
• Detección de errores de formato (encoding).

---

🧪 Testing

El proyecto utiliza Vitest para pruebas unitarias.

# Ejecutar tests
npm run test

# Ejecutar tests en modo watch
npm run test:watch

Cobertura actual: Tests unitarios de esquemas de validación (user.schema.test.ts).

---

📦 Despliegue

El proyecto está optimizado para desplegarse en Vercel.

1. Conectar repositorio de GitHub a Vercel.
2. Configurar las variables de entorno en el panel de Vercel.
3. El build se ejecuta automáticamente con:

   npm run build

---

👥 Autores

• Boris Arriagada - Product Owner & Developer
• Jaime Vicencio - Scrum Master & Developer

---

Proyecto Capstone - Duoc UC 2025