# 📊 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
- **Informe de Ingresos**: Análisis detallado por tipo de café (uva, oreado, mojado, verde)
- **Comparativa de Cosechas**: Comparación histórica entre temporadas
- **Explorador de Datos**: Navegación interactiva de tablas y metadatos

### 🔐 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
│   │   │       ├── cards.get.ts
│   │   │       └── databases.get.ts
│   │   └── 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

```bash
# 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:

```bash
# 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

```bash
cd nuxt4-app
npm run dev
```

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

### Build de Producción

```bash
cd nuxt4-app
npm run build
npm run preview
```

---

## 🐳 Despliegue con Docker

### Usando Docker Compose

```bash
# 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](./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:

- [METABASE_QUERIES_PANORAMA.md](./METABASE_QUERIES_PANORAMA.md) - 9 queries del Panorama Facturador
- [METABASE_QUERIES_INFORME_INGRESOS.md](./METABASE_QUERIES_INFORME_INGRESOS.md) - Queries de informe detallado
- [METABASE_QUERIES_COMPARATIVA_COSECHAS.md](./METABASE_QUERIES_COMPARATIVA_COSECHAS.md) - Queries de comparativa
- [METABASE_API_ENDPOINTS.md](./METABASE_API_ENDPOINTS.md) - Referencia completa de endpoints

### 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

```typescript
// 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:

```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](./DEPLOYMENT.md) - Guía completa de despliegue
- [RESTORATION_GUIDE.md](./RESTORATION_GUIDE.md) - Restauración desde backup
- [METABASE_API_ENDPOINTS.md](./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.0.0 - 2025-01

#### Agregado
- ✨ Panorama Facturador con 9 queries de Metabase
- ✨ Informe de Ingresos detallado
- ✨ 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 legacy
- 🔧 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! ☕**