Manual Técnico

src/
├── App.tsx                 # Componente raíz, navegación state-driven
├── main.tsx                # Punto de entrada React
├── index.css               # Estilos globales + Tailwind
├── components/             # 27 pantallas/vistas
│   ├── LoginScreen.tsx     # Login + conexión Supabase/Demo
│   ├── DashboardGlobal.tsx # Vista presidencia
│   ├── VPView.tsx          # Vista vicepresidencia
│   ├── GerenciaView.tsx    # Vista gerencia + carga datos
│   ├── CorporateScorecard  # BSC con 4 perspectivas
│   ├── AnalisisHistorico   # Gráficas de evolución
│   ├── AnalisisPredictivo  # Proyecciones ML
│   ├── AlertasEmail.tsx    # Configuración alertas email
│   ├── AlertasGestion.tsx  # Notificaciones en pantalla
│   ├── AdminUsuarios.tsx   # CRUD usuarios
│   ├── ReporteEjecutivo    # Reportes consolidados
│   ├── GestionRiesgos      # Matriz de riesgos
│   ├── ImportadorDatos     # Importación CSV global
│   ├── CargaMasiva.tsx     # Carga CSV por gerencia
│   └── ...                 # 12 componentes más
├── lib/
│   ├── supabase.ts         # Cliente Supabase + tipos DB
│   ├── auth.ts             # Servicio autenticación
│   └── services.ts         # 18 servicios de negocio
├── types/
│   └── index.ts            # Tipos TypeScript frontend
├── data/
│   ├── organizacion.ts     # Estructura VP/Gerencias hardcoded (demo)
│   └── corporateScorecard  # Datos BSC demo
├── hooks/
│   └── useSupabase.ts      # Hook conexión Supabase
├── config/
│   └── navigation.ts       # Configuración menú lateral
└── utils/
    └── cn.ts               # Utilidad clases Tailwind condicionales

database/
├── schema.sql              # DDL completo (21 tablas, 3 vistas, triggers)
├── functions/
│   └── is_admin.sql        # Función SECURITY DEFINER
├── policies/
│   ├── base_multitenant_policies.sql  # RLS todas las tablas
│   └── usuarios_prod.sql  # RLS tabla usuarios
├── seeds/                  # Datos iniciales
├── migrations/             # Migraciones históricas
└── maintenance/            # Scripts de limpieza

4.1 Tablas Principales

4.2 Vistas Materializadas

4.3 Índices (16)

-- Principales índices para rendimiento
idx_gerencias_vp_id             ON gerencias(vicepresidencia_id)
idx_usuarios_email              ON usuarios(email)
idx_usuarios_rol                ON usuarios(rol_id)
idx_ind_def_perspectiva         ON indicadores_definicion(perspectiva_id)
idx_ind_def_gerencia            ON indicadores_definicion(gerencia_id)
idx_ind_val_indicador           ON indicadores_valores(indicador_id)
idx_ind_val_periodo             ON indicadores_valores(periodo_id)
idx_ind_val_estado              ON indicadores_valores(estado)
idx_alertas_severidad           ON alertas(severidad)
idx_alertas_leida               ON alertas(leida)
idx_planes_gerencia_periodo     ON planes_accion(gerencia_id, periodo_id)

5.1 Funciones Helper (SECURITY DEFINER)

-- Determina si el usuario actual es admin
is_admin(p_uid uuid) → boolean

-- Obtiene el rol del usuario autenticado
get_rol_actual() → text

-- Obtiene la VP asignada al usuario
get_vp_actual() → uuid

-- Obtiene la gerencia asignada al usuario
get_gerencia_actual() → uuid

5.2 Políticas por Tabla

El sistema usa Supabase Auth con JWT. El flujo de login:

1. Usuario ingresa email + password
2. supabase.auth.signInWithPassword() → JWT + Session
3. authService.login() busca en tabla 'usuarios' por email
4. Si auth_user_id es NULL → auto-vincula auth.uid() al registro
5. Verifica usuario.activo === true
6. Carga joins: rol, vicepresidencia, gerencia
7. Retorna { auth: AuthResponse, usuario: DBUsuario }

Métodos del authService

Todos los servicios están en src/lib/services.ts. Cada entidad del dominio tiene su propio objeto de servicio con métodos CRUD y operaciones especializadas.

Servicios Disponibles (18)

valorService — Métodos Clave

El servicio más complejo, maneja el ciclo de vida completo de los valores:

// Flujo de validación
valorService.enviarAValidacion(gerenciaId, periodoId)  // pendiente → en_validacion
valorService.aprobarGerencia(gerenciaId, periodoId, validadoPorId) // → validado
valorService.rechazarValor(valorId, motivoRechazo, rechazadoPorId) // → rechazado

// Bulk operations
valorService.upsert(valores[])       // Conflict on indicador_id+periodo_id
valorService.deleteByPeriodo(periodoId, gerenciaId?)  // Returns count

// Queries especializadas
valorService.getAllHistorico(limit=5000) // Para análisis de tendencias
valorService.getPendientesAprobacionPorVP(vpId, periodoId) // Para VP

Dos capas de tipos: DB types en supabase.ts (prefijo DB*) para comunicación con Supabase, y frontend types en types/index.ts para lógica de presentación.

Tipos Clave

// Estado del semáforo
type EstadoSemaforo = 'verde' | 'amarillo' | 'rojo'

// Perspectivas BSC
type PerspectivaBSC = 'financiera' | 'clientes' | 'procesos' | 'aprendizaje'

// Roles de usuario
type RolUsuario = 'presidencia' | 'vicepresidencia' | 'gerencia'
                | 'admin_global' | 'admin_vp' | 'admin_gerencia' | 'visualizador'

// Tendencia de indicador (DB)
type Tendencia = 'mayor_mejor' | 'menor_mejor' | 'objetivo'

// Estado de período (DB)
type EstadoPeriodo = 'abierto' | 'cerrado' | 'bloqueado' | 'pendiente'

// Estado de validación (DB)
type EstadoValidacion = 'pendiente' | 'en_validacion' | 'validado' | 'rechazado'

Función: calcular_estado_indicador

calcular_estado_indicador(
    p_valor_real  DECIMAL,
    p_meta        DECIMAL,
    p_umbral_rojo INT,
    p_umbral_amarillo INT,
    p_tendencia   TEXT
) → TEXT

-- Lógica:
-- Si valor_real IS NULL → 'sin_dato'
-- Si tendencia = 'mayor_mejor':  cumplimiento = (real / meta) * 100
-- Si tendencia = 'menor_mejor':  cumplimiento = LEAST(100, (meta / real) * 100)
-- cumplimiento >= umbral_amarillo → 'verde'
-- cumplimiento >= umbral_rojo    → 'amarillo'
-- else                           → 'rojo'

Triggers Automáticos

send-alert-email

Función Deno desplegada en Supabase Edge Functions. Gestiona el envío de correos electrónicos de alerta.

// Modos de invocación:

// 1. Envío de prueba
{ configId: "uuid", test: true }

// 2. Evaluación masiva de todas las reglas configuradas
{ evalAll: true }

// 3. Envío directo ad-hoc
{ direct: true, to: ["email@..."], subject: "...", html: "..." }

El sistema implementa un caché en memoria con TTL de 30 segundos para reducir llamadas redundantes a Supabase.

// Implementación en services.ts
const cache = new Map<string, { data: any, timestamp: number }>()
const CACHE_TTL = 30_000 // 30 segundos

function getCached<T>(key: string): T | null
function setCache(key: string, data: any): void
function invalidateCache(prefix?: string): void  // Limpia por prefijo

Servicios con caché: valorService.getByPeriodo, valorService.getAllHistorico. Las mutaciones (create/update/delete) invalidan el caché automáticamente.

Vercel (Producción)

# Build command
npm run build

# Output: dist/ → single HTML file (vite-plugin-singlefile)

# Rama de deploy: main
# Repo: hermeshs34/Indicadores_Empresariales

Desarrollo Local

# Instalar dependencias
npm install

# Crear .env con las variables de Supabase
echo "VITE_SUPABASE_URL=https://fciaudxeuycqtuzyurnb.supabase.co" > .env
echo "VITE_SUPABASE_ANON_KEY=tu-anon-key" >> .env

# Iniciar servidor de desarrollo
npm run dev

# Verificar tipos TypeScript
npm run typecheck

# Ejecutar tests
npm test

El proyecto usa Vitest como framework de testing con @testing-library/react para componentes.

# Ejecutar tests
npm test

# Tests con coverage
npx vitest --coverage

# Archivo de tests: tests/smoke.test.ts

Las migraciones se aplican manualmente en el SQL Editor de Supabase. Se mantienen en database/migrations/.