Agregar README completo del proyecto
All checks were successful
build-and-deploy / build-and-deploy (push) Successful in 8s
All checks were successful
build-and-deploy / build-and-deploy (push) Successful in 8s
This commit is contained in:
366
README.md
Normal file
366
README.md
Normal file
@@ -0,0 +1,366 @@
|
||||
# 📊 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! ☕**
|
||||
Reference in New Issue
Block a user