From caefe317e08cd4c889e595a81ebbca25be4a29e5 Mon Sep 17 00:00:00 2001 From: josedario87 Date: Mon, 27 Oct 2025 15:54:09 -0600 Subject: [PATCH] Agregar README completo del proyecto --- README.md | 366 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 366 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..5ab65a0 --- /dev/null +++ b/README.md @@ -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! ☕**