nucleo000/analiticaNucleo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
d2c5cb1e0a608438e980c0551930bc2ee1b89ed6
analiticaNucleo/README.md
josedario87 646057188e
All checks were successful
build-and-deploy / build-and-deploy (push) Successful in 8s
Details
Actualizar README con cambios v1.1.0: Informe de Ingresos y config centralizada
2025-10-27 17:24:04 -06:00

424 lines
13 KiB
Markdown
Raw Blame History

# 📊 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
```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 archivos Markdown y centralizadas en código:
### Documentación de Queries
- [METABASE_QUERIES_PANORAMA.md](./METABASE_QUERIES_PANORAMA.md) - 9 queries del Panorama Facturador
- [METABASE_QUERIES_INFORME_INGRESOS.md](./METABASE_QUERIES_INFORME_INGRESOS.md) - 8 queries del Informe de Ingresos
- [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
### Configuración Centralizada
Los nombres de las queries están definidos en `server/config/metabase-queries.ts`:
```typescript
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
```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.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! ☕**
Reference in New Issue View Git Blame Copy Permalink