📊 Analítica Núcleo

Sistema de análisis financiero y operativo para Núcleo Río Frío

Plataforma web moderna para visualizar y analizar datos de ingresos de café, rechazos, cosechas y métricas financieras. Desarrollada con Nuxt 4 e integrada con Metabase para cálculos analíticos server-side.

---

🎯 Filosofía de Arquitectura

"Metabase calcula TODO. Vue solo renderiza."

Esta aplicación sigue el principio de delegar todos los cálculos, agregaciones y transformaciones de datos a Metabase mediante queries SQL optimizadas. El frontend Vue solo recibe datos pre-calculados listos para mostrar, sin lógica de negocio ni métricas computadas en el cliente.

Beneficios:

• ✅ Consistencia total entre frontend y backend
• ✅ Queries SQL auditables y versionadas
• ✅ Frontend ligero y reactivo
• ✅ Cálculos complejos optimizados en base de datos
• ✅ Sin duplicación de lógica de negocio

---

✨ Características

📈 Informes y Dashboards

• Panorama Facturador: Vista consolidada de totales financieros, inversiones, depósitos y rechazos (9 queries de Metabase)
• Informe de Ingresos: Análisis detallado con filtros avanzados por tipo, estado, fechas, clientes, ubicaciones y calidades (8 queries de Metabase)
• Comparativa de Cosechas: Comparación histórica entre temporadas
• Explorador de Datos: Navegación interactiva de tablas y metadatos
• Metabase Debug: Herramienta de debugging para verificar queries configuradas

🔐 Seguridad

• Autenticación OAuth2 con Authentik
• Control de acceso basado en roles (RBAC)
• Sesiones seguras y tokens JWT
• Rutas protegidas con middleware de autenticación

🚀 Progressive Web App (PWA)

• Instalable en escritorio y móvil
• Funcionamiento offline con Service Worker
• Actualizaciones automáticas
• Experiencia de app nativa

🎨 Interfaz de Usuario

• Diseño responsivo con Nuxt UI
• Tema personalizado en tonos café/dorado
• Componentes reutilizables y tipados
• Animaciones y transiciones fluidas

---

🛠️ Stack Tecnológico

Frontend

• Nuxt 4 - Framework Vue.js con SSR
• Vue 3 - Framework reactivo con Composition API
• TypeScript - Tipado estático
• Nuxt UI - Librería de componentes UI
• Tailwind CSS - Framework CSS utility-first
• Vite PWA - Progressive Web App

Backend / Integración

• Nuxt Server API - Endpoints server-side
• Metabase - Plataforma de analítica y queries
• PostgreSQL - Base de datos (via Metabase)
• Authentik - Sistema de autenticación OAuth2

DevOps

• Docker - Contenedores
• Gitea Actions - CI/CD
• Traefik - Reverse proxy y SSL
• Gitea Registry - Registro de imágenes Docker

---

📁 Estructura del Proyecto

analiticaNucleo/
├── nuxt4-app/                  # Aplicación Nuxt 4
│   ├── app/
│   │   ├── components/         # Componentes Vue reutilizables
│   │   │   ├── ingresos/      # Componentes de ingresos
│   │   │   ├── rechazos/      # Componentes de rechazos
│   │   │   └── ui/            # Componentes UI generales
│   │   ├── layouts/           # Layouts de página
│   │   ├── pages/             # Rutas/páginas de la aplicación
│   │   │   ├── panorama.vue           # Dashboard principal
│   │   │   ├── informe-ingresos.vue   # Informe detallado
│   │   │   ├── comparativa-cosechas.vue
│   │   │   └── metabase-debug.vue     # Debugging Metabase
│   │   ├── middleware/        # Middleware de autenticación
│   │   └── assets/            # CSS, imágenes, fuentes
│   ├── server/
│   │   ├── api/
│   │   │   └── metabase/      # Endpoints de Metabase
│   │   │       ├── panorama.post.ts      # 9 queries Panorama
│   │   │       ├── informe.post.ts       # 8 queries Informe
│   │   │       ├── query-config.get.ts   # Config de queries
│   │   │       ├── cards.get.ts          # Lista de cards
│   │   │       └── databases.get.ts      # Databases disponibles
│   │   ├── config/
│   │   │   └── metabase-queries.ts       # Config centralizada de queries
│   │   └── utils/
│   │       └── metabase.ts    # Utilidades para API de Metabase
│   ├── public/                # Archivos estáticos (iconos, PWA)
│   └── nuxt.config.ts         # Configuración de Nuxt
├── .gitea/
│   └── workflows/             # Gitea Actions CI/CD
│       └── build-and-deploy.yml
├── docker-compose.yml         # Configuración de contenedores
├── Dockerfile                 # Imagen Docker de la app
├── METABASE_QUERIES_PANORAMA.md         # Documentación de queries
├── METABASE_QUERIES_INFORME_INGRESOS.md
├── METABASE_QUERIES_COMPARATIVA_COSECHAS.md
├── METABASE_API_ENDPOINTS.md            # Referencia API Metabase
├── DEPLOYMENT.md              # Guía de despliegue
└── RESTORATION_GUIDE.md       # Guía de restauración

---

🚀 Inicio Rápido

Prerrequisitos

• Node.js 22+ y npm
• Docker y Docker Compose (para despliegue)
• Acceso a instancia de Metabase
• Acceso a servidor Authentik

Instalación Local

# Clonar el repositorio
git clone https://gitea.nucleoriofrio.com/nucleo000/analiticaNucleo.git
cd analiticaNucleo/nuxt4-app

# Instalar dependencias
npm install

# Configurar variables de entorno
cp ../.env.example ../.env
# Editar .env con tus credenciales

Variables de Entorno

Crear archivo .env en la raíz del proyecto:

# Authentik
NUXT_PUBLIC_AUTHENTIK_URL=https://authentik.nucleoriofrio.com

# Metabase (usar prefijo NUXT_ para runtime config)
NUXT_METABASE_URL=http://metabase:3000
NUXT_METABASE_API_KEY=mb_xxxxxxxxxxxxx
NUXT_METABASE_EMAIL=usuario@dominio.com
NUXT_METABASE_PASSWORD=tu-password

Desarrollo

cd nuxt4-app
npm run dev

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

Build de Producción

cd nuxt4-app
npm run build
npm run preview

---

🐳 Despliegue con Docker

Usando Docker Compose

# Build de la imagen
docker compose build

# Iniciar servicios
docker compose up -d

# Ver logs
docker compose logs -f

Despliegue Automático con Gitea Actions

El proyecto incluye CI/CD automático:

1. Push a master → Dispara workflow de Gitea Actions
2. Build → Construye imagen Docker
3. Push → Sube imagen al registro de Gitea
4. Deploy → Despliega contenedor en el servidor

Ver DEPLOYMENT.md para más detalles.

---

📊 Integración con Metabase

La aplicación se integra con Metabase mediante su API REST. Todas las queries están documentadas en archivos Markdown y centralizadas en código:

Documentación de Queries

• METABASE_QUERIES_PANORAMA.md - 9 queries del Panorama Facturador
• METABASE_QUERIES_INFORME_INGRESOS.md - 8 queries del Informe de Ingresos
• METABASE_QUERIES_COMPARATIVA_COSECHAS.md - Queries de comparativa
• METABASE_API_ENDPOINTS.md - Referencia completa de endpoints

Configuración Centralizada

Los nombres de las queries están definidos en server/config/metabase-queries.ts:

export const METABASE_QUERIES = {
  panorama: {
    totales_financieros_principales: 'panorama_totales_financieros_principales',
    totales_ingreso_compra: 'panorama_totales_ingreso_compra',
    // ... 9 queries total
  },
  informe: {
    totales_ingreso_compra: 'Informe Ingresos - Totales Ingreso y Compra',
    totales_monetarios: 'Informe Ingresos - Totales Monetarios',
    // ... 8 queries total
  }
}

Beneficios:

• ✅ Single source of truth para nombres de queries
• ✅ Búsqueda automática por nombre en Metabase
• ✅ Fácil actualización si cambian nombres
• ✅ Type-safe en TypeScript

Flujo de Datos

Usuario (Browser)
    ↓
Vue Component (panorama.vue)
    ↓ $fetch POST /api/metabase/panorama
Nuxt Server API (server/api/metabase/panorama.post.ts)
    ↓ Promise.all([9 queries en paralelo])
Metabase (http://metabase:3000)
    ↓ Ejecuta SQL queries
PostgreSQL Database
    ↓ Retorna resultados
Vue Component renderiza datos ✅

Autenticación con Metabase

La app soporta dos métodos de autenticación:

1. API Key (recomendado): Header X-API-KEY
2. Session Token (fallback): Email/password → token de sesión

---

🔒 Autenticación y Autorización

Authentik OAuth2

La aplicación usa Authentik como proveedor de identidad:

• Flujo OAuth2/OIDC
• Forward Auth con Traefik
• Sesiones persistentes
• Logout seguro

Middleware de Autenticación

// app/middleware/auth.ts
export default defineNuxtRouteMiddleware((to, from) => {
  // Verifica sesión activa
  // Redirige a login si no autenticado
})

---

🎨 Personalización

Tema y Estilos

El tema está definido en app/assets/css/main.css con variables CSS:

:root {
  --brand-bg: #1b1209;           /* Fondo principal */
  --brand-primary: #c08040;      /* Color primario (dorado/café) */
  --brand-text: #f5e6d3;         /* Texto principal */
  --brand-text-muted: #b8a999;   /* Texto secundario */
}

Componentes Reutilizables

Ver directorio app/components/ para componentes personalizados:

• DateRangeSelector.vue - Selector de rangos de fechas
• TotalesMonetarios.vue - Card de totales monetarios
• TotalesIngresoCompra.vue - Totales de ingreso/compra
• SecosVendidos.vue - Métricas de secos vendidos
• RechazosSubproductos.vue - Tabla de rechazos

---

📖 Documentación Adicional

• DEPLOYMENT.md - Guía completa de despliegue
• RESTORATION_GUIDE.md - Restauración desde backup
• METABASE_API_ENDPOINTS.md - Referencia API Metabase

---

🤝 Contribuir

Este es un proyecto privado de Núcleo Río Frío. Para contribuir:

1. Crear rama desde master
2. Hacer cambios y commits descriptivos
3. Push a Gitea
4. CI/CD automático ejecutará tests y deployment

Estándares de Código

• TypeScript strict mode habilitado
• ESLint para linting (configuración Nuxt)
• Prettier para formateo automático
• Commits descriptivos en español

---

📝 Licencia

Propiedad privada de Núcleo Río Frío. Todos los derechos reservados.

---

👤 Autor

Núcleo Río Frío Desarrollado por: Dario (Leouch, Draganel, nucleo000)

---

📞 Soporte

Para reportar issues o solicitar features:

• Gitea Issues: https://gitea.nucleoriofrio.com/nucleo000/analiticaNucleo/issues
• Contacto: claudeCode0@nucleoriofrio.com

---

🔄 Changelog

v1.1.0 - 2025-10-27

Agregado

• ✨ Configuración centralizada de queries en server/config/metabase-queries.ts
• ✨ Endpoint /api/metabase/informe con 8 queries para Informe de Ingresos
• ✨ Endpoint /api/metabase/query-config para exponer config de queries al frontend
• ✨ Página de Informe de Ingresos activada con sistema de filtros avanzados:
  • Filtros por fecha (desde/hasta)
  • Filtros por tipo de café (uva, mojado, oreado, verde)
  • Filtros por estado (pagado, pendiente)
  • Granularidad temporal (día/semana/mes)
  • Incluir/excluir anulados
• ✨ Tab "Queries Informe" en Metabase Debug
• ✨ Integración con layout informe (context menu, visibilidad de secciones)

Modificado

• 🔧 Refactorización de panorama.post.ts para usar configuración centralizada
• 🔧 Actualización de metabase-debug.vue para buscar queries por config centralizado
• 🔧 Mejora de stats en Metabase Debug (5 contadores + colores dinámicos)
• 🔧 Composables useIngresosMetrics y useRechazosMetrics marcados como obsoletos

Corregido

• 🐛 Fix imports relativos en server/ para compilación correcta
• 🐛 Fix detección de queries faltantes en Metabase Debug
• 🐛 Eliminación de composables legacy de panorama.vue

v1.0.0 - 2025-01

Agregado

• ✨ Panorama Facturador con 9 queries de Metabase
• ✨ Comparativa de Cosechas
• ✨ PWA instalable con offline support
• ✨ Autenticación con Authentik
• ✨ CI/CD con Gitea Actions

Modificado

• 🔧 Refactorización completa a filosofía "Metabase calcula TODO"
• 🔧 Eliminación de composables de métricas de componentes
• 🔧 Migración a Nuxt 4

Corregido

• 🐛 Fix autenticación con Metabase usando API Key
• 🐛 Fix variables NUXT_ para runtime config
• 🐛 Fix URL interna Docker para comunicación con Metabase

---

¡Gracias por usar Analítica Núcleo! ☕