feat: agregar página de debug para Metabase

- Crear componente MetabaseCardDisplay para mostrar detalles de queries - Crear componente MetabaseCardsTable para listar todas las queries - Crear página /metabase-debug con vistas de tabla, cards y queries Panorama - Agregar API routes para cards de Metabase (GET, POST, export) - Actualizar metabase.ts para soportar API Key authentication - Agregar configuración de Metabase API Key en nuxt.config.ts - Documentar todos los endpoints disponibles en METABASE_API_ENDPOINTS.md
2025-10-14 01:34:56 -06:00
parent d0b0dc3c56
commit 90aebbde3d
10 changed files with 1069 additions and 8 deletions
--- a/METABASE_API_ENDPOINTS.md
+++ b/METABASE_API_ENDPOINTS.md
@@ -0,0 +1,269 @@
+# 🔌 REPORTE DE ENDPOINTS API DE METABASE
+
+**Fecha:** 2025-10-14
+**Instancia:** metabase.nucleoriofrio.com
+**Autenticación:** X-API-KEY header
+**Formato:** JSON
+
+---
+
+## 📋 ENDPOINTS PRINCIPALES
+
+### 🎯 **CARDS (Questions/Queries)**
+
+Estos son los endpoints MÁS IMPORTANTES para nuestro caso, ya que trabajaremos con las 9 queries documentadas.
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/card` | Listar todas las cards/preguntas |
+| `GET` | `/api/card/:id` | Obtener detalles de una card específica |
+| `POST` | `/api/card` | Crear una nueva card |
+| `PUT` | `/api/card/:id` | Actualizar una card existente |
+| `DELETE` | `/api/card/:id` | Eliminar una card |
+| `POST` | `/api/card/:id/query` | **⭐ EJECUTAR una query y obtener resultados** |
+| `GET` | `/api/card/:id/query` | Ejecutar query con caché |
+| `GET` | `/api/card/:id/query/:export-format` | Exportar resultados (csv, json, xlsx) |
+
+**💡 Endpoint clave:** `/api/card/:id/query` - Este lo usaremos para ejecutar las 9 queries con parámetros.
+
+---
+
+### 🗄️ **DATABASE**
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/database` | Listar todas las bases de datos |
+| `GET` | `/api/database/:id` | Obtener detalles de una BD |
+| `POST` | `/api/database` | Crear conexión a BD |
+| `PUT` | `/api/database/:id` | Actualizar conexión |
+| `POST` | `/api/database/:id/sync_schema` | Sincronizar esquema |
+| `GET` | `/api/database/:id/metadata` | Obtener metadata de tablas/campos |
+| `POST` | `/api/database/validate` | Validar conexión antes de guardar |
+
+---
+
+### 📊 **DATASET (Queries Ad-hoc)**
+
+Endpoints para ejecutar queries SQL nativas sin crear cards.
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `POST` | `/api/dataset` | **⭐ Ejecutar query SQL nativa directamente** |
+| `POST` | `/api/dataset/:export-format` | Ejecutar y exportar (csv, json, xlsx) |
+
+**💡 Uso importante:** Podemos usar `/api/dataset` para probar queries SQL antes de crearlas como cards.
+
+**Ejemplo de payload:**
+```json
+{
+  "database": 2,
+  "type": "native",
+  "native": {
+    "query": "SELECT * FROM vista_detalle_ingresos LIMIT 10",
+    "template-tags": {}
+  }
+}
+```
+
+---
+
+### 📁 **COLLECTION**
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/collection` | Listar colecciones |
+| `GET` | `/api/collection/:id` | Detalles de colección |
+| `GET` | `/api/collection/:id/items` | Items dentro de colección |
+| `POST` | `/api/collection` | Crear colección |
+| `PUT` | `/api/collection/:id` | Actualizar colección |
+
+---
+
+### 📈 **DASHBOARD**
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/dashboard` | Listar dashboards |
+| `GET` | `/api/dashboard/:id` | Detalles de dashboard |
+| `POST` | `/api/dashboard` | Crear dashboard |
+| `PUT` | `/api/dashboard/:id` | Actualizar dashboard |
+| `POST` | `/api/dashboard/:id/cards` | Agregar card a dashboard |
+| `GET` | `/api/dashboard/:id/params/:param-key/values` | Valores para parámetro |
+
+---
+
+### 🔍 **TABLE & FIELD**
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/table/:id` | Detalles de tabla |
+| `GET` | `/api/table/:id/query_metadata` | Metadata completa de tabla |
+| `GET` | `/api/field/:id` | Detalles de campo |
+| `POST` | `/api/field/:id/values` | Valores únicos de un campo |
+
+---
+
+### 👤 **USER & SESSION**
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/user/current` | Usuario autenticado actual |
+| `GET` | `/api/user` | Listar usuarios |
+| `POST` | `/api/session` | Login (crear sesión) |
+| `DELETE` | `/api/session` | Logout |
+
+---
+
+### ⚙️ **SETTINGS**
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/setting` | Obtener configuraciones |
+| `PUT` | `/api/setting/:key` | Actualizar configuración |
+
+---
+
+### 🔐 **PERMISSIONS**
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/permissions/graph` | Ver árbol de permisos |
+| `PUT` | `/api/permissions/graph` | Actualizar permisos |
+| `GET` | `/api/permissions/group` | Listar grupos |
+
+---
+
+### 📤 **UPLOAD** (Anteriormente CSV)
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `POST` | `/api/upload/csv` | Subir CSV como tabla |
+
+---
+
+### 📧 **NOTIFICATION** (Reemplaza Pulse/Alert)
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/notification` | Listar notificaciones |
+| `POST` | `/api/notification` | Crear notificación |
+| `PUT` | `/api/notification/:id` | Actualizar notificación |
+
+---
+
+### 🔧 **UTIL & ANALYTICS**
+
+| Método | Endpoint | Descripción |
+|--------|----------|-------------|
+| `GET` | `/api/analytics/anonymous-stats` | Estadísticas de uso (antes /util/stats) |
+| `GET` | `/api/util/logs` | Logs del sistema |
+| `POST` | `/api/util/password_check` | Validar contraseña |
+
+---
+
+## 🎯 ENDPOINTS CRÍTICOS PARA NUESTRO PROYECTO
+
+### 1. **Ejecutar queries con parámetros**
+```http
+POST /api/card/:id/query
+Content-Type: application/json
+X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=
+
+{
+  "parameters": [
+    {"type": "date/single", "target": ["variable", ["template-tag", "fecha_desde"]], "value": "2025-01-01"},
+    {"type": "date/single", "target": ["variable", ["template-tag", "fecha_hasta"]], "value": "2025-12-31"},
+    {"type": "category", "target": ["variable", ["template-tag", "incluir_anulados"]], "value": false}
+  ]
+}
+```
+
+### 2. **Ejecutar SQL nativa directamente**
+```http
+POST /api/dataset
+Content-Type: application/json
+X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=
+
+{
+  "database": 2,
+  "type": "native",
+  "native": {
+    "query": "SELECT COALESCE(SUM(...), 0) as total FROM vista_detalle_ingresos WHERE ...",
+    "template-tags": {
+      "incluir_anulados": {
+        "type": "boolean",
+        "default": false
+      }
+    }
+  }
+}
+```
+
+### 3. **Listar todas las cards para encontrar IDs**
+```http
+GET /api/card?f=all
+X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=
+```
+
+### 4. **Obtener metadata de una card**
+```http
+GET /api/card/:id
+X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=
+```
+
+---
+
+## 📝 NOTAS IMPORTANTES
+
+1. **Autenticación:** Todos los requests requieren header `X-API-KEY: mb_bRFd1DTqU1eK1GeYFo3z0WhwKcqdA5qHNCXko3ZV6FU=`
+
+2. **Estructura de respuesta de queries:**
+```json
+{
+  "data": {
+    "rows": [...],           // Array de arrays con los valores
+    "cols": [...],           // Metadata de columnas (nombre, tipo, etc)
+    "rows_truncated": 1000,  // Límite de filas
+    "native_form": {...}     // Query SQL ejecutada
+  },
+  "database_id": 2,
+  "started_at": "...",
+  "json_query": {...},
+  "average_execution_time": null,
+  "status": "completed",
+  "context": "ad-hoc",
+  "row_count": 1,
+  "running_time": 45
+}
+```
+
+3. **IDs de las 9 queries del Panorama:**
+   - Query 1: `/api/card/38/query` (panorama_totales_financieros_principales)
+   - Query 2-9: Por determinar
+
+4. **Parámetros template-tags:**
+   - `fecha_desde`: tipo `date/single`, opcional
+   - `fecha_hasta`: tipo `date/single`, opcional
+   - `incluir_anulados`: tipo `boolean`, default `false`
+
+5. **Testing de queries:**
+   - Usar `/api/dataset` para probar SQL antes de crear/editar cards
+   - Usar `/api/card/:id/query` para probar cards existentes con diferentes parámetros
+
+---
+
+## 🚀 PRÓXIMOS PASOS
+
+1. ✅ Listar todas las cards con `GET /api/card?f=all` para identificar las 9 queries
+2. ✅ Para cada query (1-9):
+   - Obtener metadata con `GET /api/card/:id`
+   - Ejecutar con parámetros default usando `POST /api/card/:id/query`
+   - Verificar estructura de respuesta
+   - Validar que coincida con la especificación en `METABASE_QUERIES_PANORAMA.md`
+3. ✅ Ajustar queries que no devuelvan la estructura correcta
+
+---
+
+**Documento creado:** 2025-10-14
+**Autor:** Claude Code
+**Proyecto:** Analítica Núcleo - Exploración API Metabase