Manual Técnico

Configuración, mantenimiento y flujo de trabajo de la plataforma Revo Analytics.

Visión general

Revo Analytics es una plataforma multi-tenant que extrae datos de la API de Revo XEF, los transforma en un modelo analítico estrella (star schema) y los expone a través de:

• Dashboard web (13 páginas de analítica, informes compartibles).
• OData v4 (22 entidades, compatible con Power BI/Excel).
• Panel Admin (gestión de distribuidores, tenants, usuarios, API keys).

Stack tecnológico

Arquitectura

┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│   Revo XEF   │────▶│     ETL      │────▶│  PostgreSQL  │
│   (API REST) │     │  pipeline.py │     │ Star Schema  │
└──────────────┘     └──────────────┘     └──────┬───────┘
                                                 │
                           ┌─────────────────────┼─────────────────────┐
                           │                     │                     │
                    ┌──────▼──────┐     ┌────────▼────────┐  ┌────────▼────────┐
                    │  Dashboard  │     │   OData v4 API  │  │   Admin Panel   │
                    │  index.html │     │ /odata/v1/{ent} │  │    /panel       │
                    │  (Chart.js) │     │  (Power BI)     │  │  (JWT + RBAC)   │
                    └─────────────┘     └─────────────────┘  └─────────────────┘
                         │                      │                     │
                    API Key auth          API Key / Basic        JWT Bearer

Estructura de archivos

Requisitos del sistema

• Python 3.12+
• PostgreSQL 16+ (con usuario y base de datos creados)
• Git (para clonar y actualizar)
• ngrok (opcional, para exponer a internet)
• Sistema operativo: Windows (probado), Linux o macOS
• RAM: Mínimo 2 GB. Recomendado 4 GB.

Instalación paso a paso

1. Clonar el repositorio

git clone <repo-url> revo-analytics
cd revo-analytics

2. Crear entorno virtual

# Windows
python -m venv .venv
.venv\Scripts\activate

# Linux / macOS
python3 -m venv .venv
source .venv/bin/activate

3. Instalar dependencias

pip install -r requirements.txt

4. Crear archivo .env

copy .env.example .env     # Windows
# cp .env.example .env     # Linux

Edita el archivo con tus valores (ver sección siguiente).

5. Crear base de datos e inicializar tablas

# Crear la BD en PostgreSQL
psql -U postgres -c "CREATE DATABASE revo_analytics;"

# Crear todas las tablas
python scripts/setup_db.py

# Generar dimensión de tiempo (calendario)
python scripts/generate_dim_tiempo.py

6. Crear superadmin

python scripts/create_superadmin.py --email admin@tudominio.com --password tu_password --nombre "Admin"

7. Iniciar servidor

uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

Configuración .env

El archivo .env configura toda la plataforma. Variables agrupadas por prefijo:

PostgreSQL (destino analítico)

MySQL (lectura legacy, opcional)

Revo OAuth

Servidor OData

ETL

Admin Panel

Ejemplo de .env mínimo

# PostgreSQL
PG_HOST=localhost
PG_PORT=5432
PG_DB=revo_analytics
PG_USER=postgres
PG_PASS=postgres

# Admin
ADMIN_SECRET=mi_clave_secreta_muy_larga_32_chars

# Revo OAuth (si ya tienes tokens)
REVO_CLIENT_ID=tu_client_id
REVO_ACCESS_TOKEN=ey...
REVO_REFRESH_TOKEN=def...

Crear base de datos

# Conectar a PostgreSQL como superusuario
psql -U postgres

-- Crear BD y usuario (ajustar nombre/password)
CREATE DATABASE revo_analytics;
CREATE USER analytics WITH PASSWORD 'tu_password';
GRANT ALL PRIVILEGES ON DATABASE revo_analytics TO analytics;
\q

# Crear tablas SQLAlchemy
python scripts/setup_db.py

# Generar dimensión de tiempo (2020-2030)
python scripts/generate_dim_tiempo.py

Crear superadmin

python scripts/create_superadmin.py \
  --email admin@tudominio.com \
  --password una_password_segura \
  --nombre "Administrador"

El script crea un usuario con rol superadmin. La contraseña se hashea con bcrypt. Se puede ejecutar varias veces con diferentes emails.

Primer tenant

python scripts/create_first_tenant.py

O créalo desde el Panel Admin (/panel) una vez iniciada sesión como superadmin: Pestaña Tenants → + Nuevo Tenant.

Después de crear el tenant, configura sus tokens OAuth (editando desde el panel o directamente en la BD) y ejecuta el primer ETL:

python scripts/run_etl.py --tenant-id 1 --mode full --days 90

Iniciar servidor

Desarrollo (con auto-reload)

uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

Producción

# Con múltiples workers
uvicorn api.main:app --host 0.0.0.0 --port 8000 --workers 4

# O con gunicorn (Linux)
gunicorn api.main:app -w 4 -k uvicorn.workers.UvicornWorker -b 0.0.0.0:8000

URLs principales

ETL manual

Comando

python scripts/run_etl.py [opciones]

Opciones

Modos

Flujo ETL

1. Leer config del tenant (tokens, empresa_id)
2. Obtener token válido (refresh si expirado)
3. Extraer datos de API Revo XEF:
   - Órdenes con líneas de detalle
   - Pagos y desglose
   - Catálogos (productos, categorías, grupos, camareros, mesas, métodos de pago)
4. Parsear JSON → DataFrames
5. Transformar:
   - DimTiempo (merge)
   - DimProducto, DimCategoria, DimGrupo
   - DimCamarero, DimMesa, DimMetodoPago
   - FactFactura, FactVentasLinea
   - Descuentos
6. Cargar a PostgreSQL (bulk upsert)
7. Post-procesamiento (14 pasos):
   - Clasificación ABC (Pareto)
   - Menu Engineering (BCG)
   - Heatmap de ocupación
   - KPIs resumen
   - Forecast (predicción)
   - Alertas (anomalías)
   - Combinaciones (cross-selling)
   - Clientes RFM
   - Cohortes retención
   - Rentabilidad
   - Anulaciones
   - Velocidad de servicio
   - Desglose pagos/impuestos
8. Registrar resultado en EtlLog

Scheduler automático

El script scripts/etl_scheduler.py ejecuta automáticamente el ETL para cada tenant según su hora programada.

Cómo funciona

1. Lee todos los tenants con activo=True y etl_habilitado=True.
2. Filtra los que tienen etl_hora_ejecucion ≤ hora_actual.
3. Excluye los que ya se ejecutaron hoy (compara ultimo_etl con la fecha actual).
4. Ejecuta ETL incremental para cada tenant pendiente.
5. Actualiza ultimo_etl en caso de éxito.

Opciones del scheduler

Configurar en Windows (Task Scheduler)

Configurar en Linux (cron)

# Editar crontab
crontab -e

# Ejecutar cada hora
0 * * * * cd /opt/revo-analytics && /opt/revo-analytics/.venv/bin/python scripts/etl_scheduler.py >> /var/log/revo-etl.log 2>&1

Exponer con ngrok y OData remoto

Para hacer accesible tu servidor local (incluyendo la API OData) desde internet, sigue estos pasos exactos:

1. Activar entorno y arrancar servidor

# 1. Abrir terminal en la carpeta del proyecto
cd C:\xampp\htdocs\python

# 2. Activar entorno virtual
.venv\Scripts\activate

# 3. Arrancar el servidor web (puerto 8000)
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

2. Arrancar ngrok con tu dominio estático

En otra terminal, ejecuta el siguiente comando para vincular tu dominio reservado al puerto 8000 local:

ngrok http --domain=sylvie-snobbish-shantae.ngrok-free.dev 8000

3. Verificar conexión

• Web: https://sylvie-snobbish-shantae.ngrok-free.dev/static/index.html
• OData (Power BI): https://sylvie-snobbish-shantae.ngrok-free.dev/odata/v1/

Logs y diagnóstico

Log ETL en base de datos

Cada ejecución se registra en la tabla etl_log:

SELECT id, tenant_id, modo, status, duracion_seg, ordenes,
       error_mensaje, created_at
FROM etl_log
ORDER BY created_at DESC
LIMIT 20;

Log del servidor

Uvicorn escribe a stdout. Para persistir:

uvicorn api.main:app --port 8000 2>&1 | tee server.log     # Linux
uvicorn api.main:app --port 8000 *>&1 | Tee-Object server.log  # PowerShell

Consultas de diagnóstico útiles

-- Tenants sin tokens
SELECT id, nombre FROM tenants WHERE revo_access_token IS NULL OR revo_access_token = '';

-- Tenants con ETL fallido hoy
SELECT t.nombre, e.status, e.error_mensaje
FROM etl_log e JOIN tenants t ON t.id = e.tenant_id
WHERE e.created_at::date = CURRENT_DATE AND e.status = 'error';

-- API Keys más usadas hoy
SELECT a.nombre, a.requests_hoy, t.nombre as tenant
FROM api_keys a JOIN tenants t ON t.id = a.tenant_id
ORDER BY a.requests_hoy DESC;

-- Volumen de datos por tenant
SELECT empresa_id, COUNT(*) as lineas
FROM fact_ventas_linea GROUP BY empresa_id;

Gestión de tokens OAuth

Flujo de tokens

1. Se pegan manualmente los tokens en el tenant (Access + Refresh).
2. El ETL usa el Access Token para llamar a la API de Revo.
3. Si el Access Token ha expirado, el sistema usa el Refresh Token para obtener uno nuevo.
4. Los nuevos tokens (access + refresh + expires_at) se guardan automáticamente en la BD.
5. Si el Refresh Token también ha expirado, el ETL falla y hay que obtener nuevos tokens.

Obtener tokens manualmente

Mientras no haya flujo OAuth automatizado, los tokens se obtienen del proceso de autorización de Revo y se pegan en el Panel Admin (editar tenant → campos de tokens).

Actualizar tokens por SQL (emergencia)

UPDATE tenants SET
  revo_access_token = 'nuevo_access_token_aqui',
  revo_refresh_token = 'nuevo_refresh_token_aqui',
  revo_token_expires_at = '2026-03-15T12:00:00'
WHERE id = 1;

Backups

Backup completo de la BD

# Dump completo
pg_dump -U postgres revo_analytics > backup_$(date +%Y%m%d).sql

# Solo tablas de sistema (config, sin datos analíticos)
pg_dump -U postgres revo_analytics \
  -t distribuidores -t tenants -t users -t api_keys -t informes \
  > backup_system_$(date +%Y%m%d).sql

Restaurar

psql -U postgres revo_analytics < backup_20260210.sql

Script de backup automático (cron)

# Backup diario a las 6 AM, mantener 30 días
0 6 * * * pg_dump -U postgres revo_analytics | gzip > /backups/revo_$(date +\%Y\%m\%d).sql.gz
0 7 * * * find /backups -name "revo_*.sql.gz" -mtime +30 -delete

Actualizar código

# Parar servidor
# (Ctrl+C o matar el proceso)

# Obtener cambios
git pull origin main

# Actualizar dependencias (si cambiaron)
pip install -r requirements.txt

# Aplicar cambios de esquema (si hay)
python scripts/setup_db.py

# Reiniciar servidor
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

Llamadas a la API de Revo

Este apartado documenta todas las peticiones HTTP que el sistema realiza a la API de Revo XEF durante un ciclo ETL. Úsalo para auditar, optimizar y diagnosticar el consumo de la API.

Resumen de llamadas por ejecución ETL

Fase 1 — Classic Catalog API

Se ejecuta siempre (en los 3 modos: incremental, full, catalog). Obtiene los catálogos básicos del restaurante.

1. Productos

2. Categorías

3. Grupos

4. Métodos de pago

Fase 2 — Catalog API v1 (enriquecimiento)

Se ejecuta siempre, después de la fase Classic. Obtiene datos adicionales de cada entidad que el Classic API no proporciona. Si falla, se omite el enriquecimiento sin cancelar el ETL.

5. Items (Catalog v1)

6. Categories (Catalog v1)

7. Groups (Catalog v1)

8. General Groups (Catalog v1)

Fase 3 — Orders API (datos transaccionales)

Se ejecuta solo en modos incremental y full (NO en catalog). Es la llamada más costosa en volumen.

9. Órdenes

Token Refresh

Además, si cualquier petición recibe un HTTP 401, se intenta un refresh automático y se reintenta la petición original.

Análisis de optimización

Flujo de llamadas por modo

┌──────────────────────────────────────────────────────────────────────┐
│  MODO CATALOG (solo catálogos)                                      │
│  Llamadas: 8 endpoints × 1–5 páginas = ~12–20 peticiones            │
│                                                                      │
│  1. /classic/catalog/items           → dim_producto                  │
│  2. /classic/catalog/categories      → dim_categoria                 │
│  3. /classic/catalog/groups          → dim_grupo                     │
│  4. /classic/payment-methods         → dim_metodo_pago               │
│  5. /catalog/v1/items                → enrich(cost, barcode, tax)    │
│  6. /catalog/v1/categories           → enrich(general_group)         │
│  7. /catalog/v1/groups               → enrich(general_group)         │
│  8. /catalog/v1/general-groups       → lookup tabla super-grupos     │
│  ────────────────────────────────────────────────────────────────     │
│  FIN                                                                 │
└──────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────┐
│  MODO INCREMENTAL (1 día, ejecución nocturna)                       │
│  Llamadas: ~12–25 peticiones                                         │
│                                                                      │
│  [Fases 1–2 igual que Catalog]                                       │
│  9. /classic/reports/v3/orders       → 1 chunk × 1–5 páginas        │
│  ────────────────────────────────────────────────────────────────     │
│  + Post-procesamiento (14 pasos, sin API calls, todo en BD)          │
└──────────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────────┐
│  MODO FULL (90 días)                                                 │
│  Llamadas: ~40–200+ peticiones                                       │
│                                                                      │
│  [Fases 1–2 igual que Catalog]                                       │
│  9. /classic/reports/v3/orders       → 3 chunks × 5–60 páginas      │
│  ────────────────────────────────────────────────────────────────     │
│  + Post-procesamiento (14 pasos, sin API calls, todo en BD)          │
└──────────────────────────────────────────────────────────────────────┘

Puntos de optimización identificados

Métricas de controladores de eficiencia

Estimación de peticiones por tenant y modo

Modelos de datos

Modelos de sistema (system.py)

Modelos analíticos (analytics.py)

Dimensiones (9): DimTiempo, DimEmpresa, DimProducto, DimCategoria, DimGrupo, DimMetodoPago, DimCamarero, DimMesa, DimCliente

Hechos (11): FactVentasLinea, FactFactura, FactHeatmap, FactKpiResumen, FactForecast, FactAlerta, FactCombinacion, FactRentabilidad, FactAnulacion, FactMenuEngineering, FactVelocidadServicio, FactCohorteRetencion, FactDesglosePago, FactDesgloseImpuesto

Todos los facts llevan empresa_id para aislamiento multi-tenant.

API Admin — Endpoints

Autenticación

Dashboard

CRUD Distribuidores

CRUD Tenants

CRUD Usuarios

CRUD API Keys

Otros

Headers de impersonación

OData — Referencia

URL base

GET /odata/v1/{EntitySet}?$filter=...&$select=...&$orderby=...&$top=N&$skip=N&$count=true

Autenticación

• Header: X-API-Key: ra_xxxx...
• Basic Auth: Authorization: Basic base64(usuario:api_key)
• Query param: ?api_key=ra_xxxx...

22 Entidades

VentasLinea, Facturas, Productos, Categorias, Grupos,
MetodosPago, Camareros, Mesas, Calendario, Clientes,
KpisResumen, Heatmap, Alertas, Forecast, Combinaciones,
DesglosePagos, DesgloseImpuestos, Rentabilidad,
Anulaciones, MenuEngineering, VelocidadServicio, Cohortes

Ejemplo

GET /odata/v1/VentasLinea?$filter=fecha ge 2026-01-01&$select=producto_nombre,cantidad,total&$orderby=total desc&$top=100

Seguridad — Referencia

Troubleshooting

El servidor no arranca

ETL falla

Dashboard no muestra datos

Panel admin no carga

Comandos de emergencia

# Resetear contraseña de superadmin
python scripts/create_superadmin.py --email admin@tu.com --password nueva_password

# Ver últimos errores ETL
psql -U postgres revo_analytics -c "SELECT tenant_id, error_mensaje FROM etl_log WHERE status='error' ORDER BY id DESC LIMIT 5;"

# Matar servidor y reiniciar
# Windows:
Get-Process -Name python | Stop-Process -Force
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

# Recarga completa de un tenant
python scripts/run_etl.py --tenant-id 1 --mode full --days 90

# Regenerar calendario
python scripts/generate_dim_tiempo.py

Revo Analytics — Manual Técnico v1.0 — Febrero 2026