┌─────────────────────────────────────────────────────────────┐
│  Frontend  (React 19 + Vite)                                │
│  • Editor SQL con autocompletado por esquema (CodeMirror)   │
│  • Canvas visual de pipelines drag & drop (@xyflow/react)   │
│  • Dashboard, Gráficas (Recharts), Reportes PDF             │
│  • Pestañas persistentes por usuario (cross-device)         │
└────────────────────────┬────────────────────────────────────┘
                         │ HTTP / REST  (Authorization: Bearer <JWT>)
┌────────────────────────▼────────────────────────────────────┐
│  Backend  (FastAPI + SQLAlchemy 2.0 + Python 3.11+)         │
│  • /db/v1/*                Administración de BDs            │
│  • /jobs/v1/*              Motor de pipelines               │
│  • /charts/v1/*            Gráficas guardadas               │
│  • /reports/v1/*           Reportes PDF                     │
│  • /transform-blocks/v1/*  Bloques reutilizables            │
│  • /connections/v1/*       Conexiones dinámicas desde UI    │
│  • /users/v1/me/*          Preferencias del usuario         │
│  • /admin/users|roles/*    Gestión de usuarios y roles ACL  │
│  • /oauth/token            Autenticación JWT                │
│  • /mongo /redis /qdrant   Bases NoSQL                      │
└──────┬──────────────────────────┬───────────────────────────┘
       │                          │
┌──────▼──────┐          ┌────────▼──────────────────────────┐
│ app_state   │          │  Bases de datos administradas      │
│ (MySQL /    │          │  MySQL / PostgreSQL / SQLite /     │
│  PostgreSQL │          │  Oracle / MongoDB / Redis / Qdrant │
│  / SQLite)  │          │  (configuradas en .env o desde UI) │
│             │          └────────────────────────────────────┘
│ users_acl   │
│ roles       │
│ charts      │
│ jobs        │
│ job_runs    │
│ job_run_    │
│ steps       │
│ reports     │
│ transform_  │
│ blocks      │
│ db_         │
│ connections │
└─────────────┘

# requirements.txt vive en la raíz del repo, no en python_api/
pip install -r requirements.txt

# Copiar y editar el archivo de configuración
cp .env.example .env
# Editar .env: agregar JWT_SECRET, conexiones de BD, etc.

# Arrancar (desarrollo)
./run-dev-mysql.sh        # Con MySQL como BD de estado — puerto 3560
# o
./run-dev-sqlite.sh       # Con SQLite (sin dependencias externas) — puerto 3550,
                          # para poder correrlo en paralelo con el anterior
# Swagger completo:         /docs  o  /swagger
# Swagger SQL + consultas:  /swagger-consultas
# Swagger solo API datos:   /swagger-api

cd frontend
npm install
npm run dev        # Desarrollo (http://localhost:5173)
npm run build      # Producción → dist/

# Opción A: Usar el script de hash + endpoint REST
# (hash_password.py vive en la raíz del repo, no en python_api/)
python hash_password.py MiPassword123!
# → Copiar el hash y crear el usuario via POST /admin/users

# Opción B: Importar desde el ejemplo (antes del primer arranque)
cp acl_users.json.example acl_users.json
# Al arrancar, la app migra automáticamente el JSON a la BD

 [1] Iniciar (backend + frontend)
 [2] Detener / pausar
 [3] Reiniciar
 [4] Ver estado
 [5] Ver logs en vivo (solo Linux/macOS; Ctrl+C para volver al menú)
 [6] Instalar / actualizar / desinstalar (solo Linux/macOS — ver abajo)
 [7] Salir del panel (los procesos siguen corriendo)

sudo ./systemd/install.sh      # instalar/actualizar
sudo ./systemd/uninstall.sh    # desinstalar

sudo DBSTUDIO_FRONTEND_DOMAIN=app.midominio.com \
     DBSTUDIO_API_DOMAIN=api.midominio.com \
     DBSTUDIO_CERT_PATH=/etc/letsencrypt/live/midominio.com/fullchain.pem \
     DBSTUDIO_CERT_KEY_PATH=/etc/letsencrypt/live/midominio.com/privkey.pem \
     ./nginx/install.sh

# Ejemplo con MySQL:
APP_DB_TYPE=mysql
APP_DB_HOST=servidor:3306
APP_DB_USER=usuario
APP_DB_PASSWORD=clave
APP_DB_NAME=db_studio

# Ejemplo con PostgreSQL:
APP_DB_TYPE=postgresql
APP_DB_HOST=servidor:5432
APP_DB_USER=usuario
APP_DB_PASSWORD=clave
APP_DB_NAME=db_studio

DB_SERVERS=NOMBRE1,NOMBRE2          # Lista de servidores separados por coma

NOMBRE1_TYPE=mysql                  # mysql | postgresql | sqlite | oracle | mongodb | redis | qdrant
NOMBRE1_HOST=servidor:3306          # host:puerto (puerto embebido en el host)
NOMBRE1_USER=usuario
NOMBRE1_PASSWORD=contraseña

admin                               Acceso total — bypasea todo lo demás

# Bases de datos administradas
db:<bd>:read                        Leer cualquier tabla de <bd>
db:<bd>:write                       Escribir/actualizar/borrar en <bd>
db:<bd>:schema                      Crear/editar vistas, procedimientos, triggers
db:<bd>:sql                         Ejecutar SQL crudo (exec-query) y CTEs
db:<bd>:table:<tabla>:read          Lectura granular a una tabla específica
db:<bd>:table:<tabla>:write         Escritura granular a una tabla específica
db:*:read / db:*:write / etc.       Wildcard — aplica a todas las BDs

# Herramientas globales
download                            Exportar resultados como CSV/XLSX/JSON
copy                                Copiar datos de la grilla al portapapeles (UX)

# Módulos de la aplicación
charts:read / charts:write          Gráficas guardadas (definiciones)
reports:read / reports:write        Reportes PDF (definiciones + generación)
jobs:read / jobs:write              Definiciones de jobs (pipeline + cron)
jobs:execute                        Disparar corridas manuales de jobs
jobs:python                         Guardar pasos con código Python (sandbox)
transform_blocks:read / :write      Bloques de transformación reutilizables
logs:read                           Ver logs de auditoría en /admin/logs (histórico + SSE en vivo)

# Conexiones a BD (gestión dinámica desde UI)
connections:read                    Ver conexiones propias y compartidas
connections:write                   Crear/editar/borrar conexiones propias
                                     (alcance real: puede redirigir una BD ya usada
                                     por otros, ver docs/dev/acl-seguridad.md)
connections:admin                   Gestionar todas + marcar como compartidas

# NoSQL
nosql:read                          Leer datos de MongoDB/Redis/Qdrant
nosql:write                         Escribir datos en MongoDB/Redis/Qdrant
nosql:admin                         Administrar colecciones y estructuras NoSQL

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

username=ana&password=secreto

pip install pyyaml   # una sola vez
python docs/generate_openapi_exports.py

POST   /oauth/token                             Obtener JWT (usuario + contraseña)

GET    /db/v1/databases                         Listar BDs disponibles
GET    /db/v1/{db}/tables                       Listar tablas de una BD
GET    /db/v1/{db}/tables/{table}/rows          Leer filas con paginación
POST   /db/v1/{db}/tables/{table}/rows          Insertar fila
PUT    /db/v1/{db}/tables/{table}/rows/{pk}     Actualizar fila
DELETE /db/v1/{db}/tables/{table}/rows/{pk}     Borrar fila
POST   /db/v1/exec-query                        Ejecutar SQL crudo (requiere ALLOW_RAW_SQL)
POST   /db/v1/cte                               Ejecutar CTE (siempre disponible)
GET    /db/v1/export                            Exportar resultados como CSV/XLSX

GET    /charts/v1                               Listar gráficas del usuario
POST   /charts/v1                               Crear gráfica
GET    /charts/v1/{id}                          Obtener definición
PUT    /charts/v1/{id}                          Actualizar definición
DELETE /charts/v1/{id}                          Eliminar
POST   /charts/v1/{id}/data                     Ejecutar consulta(s) y devolver filas

GET    /jobs/v1                                 Listar jobs del usuario
POST   /jobs/v1                                 Crear job
GET    /jobs/v1/{id}                            Obtener definición
PUT    /jobs/v1/{id}                            Actualizar
DELETE /jobs/v1/{id}                            Eliminar
POST   /jobs/v1/{id}/run                        Ejecutar manualmente
GET    /jobs/v1/{id}/runs                       Historial de corridas
GET    /jobs/v1/runs/{run_id}                   Detalle de corrida (con pasos)
GET    /jobs/v1/{id}/data/{step_id}             Datos del último paso exitoso (JSON)
GET    /jobs/v1/{id}/latest-output/{step_id}    Archivo del último paso exitoso
GET    /jobs/v1/runs/{run_id}/download/{step}   Descargar archivo de una corrida
GET    /jobs/v1/{id}/export                     Exportar job como JSON portable
POST   /jobs/v1/import                          Importar job desde JSON
POST   /jobs/v1/uploads                         Subir CSV/XLSX para paso file_input

GET    /reports/v1                              Listar reportes del usuario
POST   /reports/v1                              Crear reporte
GET    /reports/v1/{id}                         Obtener definición
PUT    /reports/v1/{id}                         Actualizar
DELETE /reports/v1/{id}                         Eliminar
POST   /reports/v1/{id}/generate                Generar y descargar PDF

GET    /transform-blocks/v1                     Listar bloques del usuario
POST   /transform-blocks/v1                     Crear bloque
GET    /transform-blocks/v1/{id}                Obtener definición
PUT    /transform-blocks/v1/{id}                Actualizar
DELETE /transform-blocks/v1/{id}                Eliminar

GET    /connections/v1                          Listar conexiones visibles
POST   /connections/v1                          Crear conexión
GET    /connections/v1/{id}                     Obtener conexión
PUT    /connections/v1/{id}                     Actualizar
DELETE /connections/v1/{id}                     Eliminar
POST   /connections/v1/{id}/test                Probar conectividad

GET    /users/v1/me/tab-state                   Obtener pestañas guardadas
PUT    /users/v1/me/tab-state                   Guardar estado de pestañas

GET    /admin/users                             Listar usuarios ACL
POST   /admin/users                             Crear usuario
PUT    /admin/users/{username}                  Actualizar usuario
DELETE /admin/users/{username}                  Eliminar usuario
GET    /admin/roles                             Listar roles
POST   /admin/roles                             Crear rol
PUT    /admin/roles/{id}                        Actualizar rol
DELETE /admin/roles/{id}                        Eliminar rol
GET    /admin/logs                              Ver logs de auditoría (paginados)
GET    /admin/resources                         Ver métricas de sistema (CPU/RAM/disco)

# Datos normalizados del último resultado exitoso de un paso (polling periódico)
GET /jobs/v1/{job_id}/data/{step_id}
# → {"data": [{col1: val, col2: val, ...}, ...], "count": N}

# Archivo del último resultado (CSV, JSON, XML, PNG, XLSX) — sin forzar descarga
GET /jobs/v1/{job_id}/latest-output/{step_id}
# → archivo con Content-Type apropiado

# Datos en tiempo real de una gráfica guardada (si tiene varias fuentes SQL,
# se corren en paralelo y se combinan segun config.mergeMode — ver más abajo)
POST /charts/v1/{chart_id}/data
Body: {"parameters": {"fecha_inicio": "2026-01-01"}}  # opcional — sobreescribe ese parámetro en TODAS las fuentes
# → {"data": [...filas...], "meta": {"count": N}}

# Generar PDF de un reporte
POST /reports/v1/{report_id}/generate
# → archivo PDF como attachment

[YYYY-MM-DD HH:MM:SS] NIVEL     dbstudio.categoria  EVENTO  clave1=valor1  clave2=valor2  ...

[2026-07-02 21:15:04] INFO     dbstudio.ops       REQUEST_OK        method=POST  path=/db/v1/cte  user=admin  ip=127.0.0.1  status=200  duration_ms=12
[2026-07-02 21:15:10] INFO     dbstudio.security  LOGIN_OK          username=ana  ip=192.168.1.5  status=200  duration_ms=38
[2026-07-02 21:16:00] INFO     dbstudio.jobs      RUN_START         job_id=3  job_name="Export diario"  run_id=17  trigger=schedule  user=sistema  steps=4
[2026-07-02 21:16:02] INFO     dbstudio.jobs      RUN_COMPLETE      job_id=3  job_name="Export diario"  run_id=17
[2026-07-02 21:16:05] INFO     dbstudio.jobs      SANDBOX_EXEC_START  input_rows=1200  timeout=30  cpu_limit=10  mem_limit_mb=512
[2026-07-02 21:16:06] INFO     dbstudio.jobs      SANDBOX_EXEC_OK   output_rows=1200
[2026-07-02 21:16:10] INFO     dbstudio.ops       CHART_CREATED     user=ana  chart_id=7  chart="Ventas por mes"  sources=1  chart_type=bar
[2026-07-02 21:17:00] INFO     dbstudio.ops       TAB_STATE_SAVED   user=ana  tab_count=5  active=tab-3
[2026-07-02 21:40:01] WARNING  dbstudio.security  LOGIN_FAIL        username=hacker  ip=203.0.113.42  status=401  duration_ms=250
[2026-07-02 21:41:00] WARNING  dbstudio.errors    CLIENT_ERROR      method=DELETE  path=/jobs/v1/99  user=beto  ip=10.0.0.1  status=404  duration_ms=5

# Todos los logins fallidos en la última hora
grep "LOGIN_FAIL" logs/security.log | tail -50

# Corridas de job fallidas hoy
grep "RUN_FAILED\|RUN_STEP_FAIL" logs/jobs.log | grep "$(date +%Y-%m-%d)"

# Errores del servidor (5xx)
grep "SERVER_ERROR" logs/errors.log | tail -100

# Actividad de un usuario específico
grep "user=ana" logs/ops.log | tail -50

# Ejecuciones de sandbox Python con timeout
grep "SANDBOX_EXEC_TIMEOUT" logs/jobs.log

db-studio/
├── .env                          # Variables de entorno (no commitear)
├── .env.example                  # Plantilla de configuración
├── .gitattributes                # Fuerza LF en todo el repo (ver nota de line endings)
├── run-python-api.sh             # Arranque "de producción" (lee .env, sin datos de ejemplo)
├── run-dev-mysql.sh              # Script de arranque del backend (MySQL como BD de estado)
├── run-dev-sqlite.sh             # Script de arranque del backend (SQLite)
├── db-studio.bat / db-studio.ps1 # Panel de control (Windows): iniciar/detener/reiniciar front+back
├── db-studio.sh                  # Panel de control (Linux/macOS), mismo menú
├── systemd/                      # Unidades systemd + install.sh/uninstall.sh (backend+frontend como servicio)
├── nginx/                        # Plantilla opcional de reverse proxy TLS + install.sh
├── hash_password.py              # CLI para generar hashes bcrypt
├── acl_users.json.example        # Ejemplo de usuarios ACL para migración inicial
├── migration/                    # Dump + guía para migrar a un servidor nuevo
│
├── python_api/                   # Backend FastAPI
│   ├── requirements.txt
│   ├── app/
│   │   ├── main.py               # App factory: routers, middlewares, Swagger x3
│   │   ├── api/                  # Routers HTTP (uno por recurso)
│   │   │   ├── charts.py         # /charts/v1/*
│   │   │   ├── jobs.py           # /jobs/v1/*
│   │   │   ├── reports.py        # /reports/v1/*
│   │   │   ├── transform_blocks.py # /transform-blocks/v1/*
│   │   │   ├── connections.py    # /connections/v1/*
│   │   │   ├── user_prefs.py     # /users/v1/me/* (tab-state)
│   │   │   ├── admin_users.py    # /admin/users/*
│   │   │   ├── admin_roles.py    # /admin/roles/*
│   │   │   ├── admin_logs.py     # /admin/logs/*
│   │   │   ├── admin_resources.py # /admin/resources/*
│   │   │   ├── oauth.py          # /oauth/token
│   │   │   ├── mongo.py          # /mongo/v1/*
│   │   │   ├── redis_api.py      # /redis/v1/*
│   │   │   └── qdrant_api.py     # /qdrant/v1/*
│   │   ├── core/
│   │   │   ├── acl.py            # Motor de scopes (40+ scopes documentados)
│   │   │   ├── acl_users.py      # CRUD de usuarios en BD, migración desde JSON
│   │   │   ├── config.py         # Settings: clase simple sobre os.getenv() (.env → Python)
│   │   │   └── security.py       # JWT: emisión, validación, extracción de scopes
│   │   ├── db/
│   │   │   ├── app_state.py      # Motor SQLAlchemy del estado propio + migraciones in-place
│   │   │   ├── models_app.py     # ORM: UserModel (tab_state), ChartModel, JobModel, etc.
│   │   │   ├── connection.py     # Pool de conexiones a BDs administradas (DatabaseManager)
│   │   │   └── validation.py     # Helper api_error() para errores HTTP uniformes
│   │   ├── services/
│   │   │   ├── jobs_engine.py    # Motor de pipelines: 20+ tipos de paso, ejecución en hilo
│   │   │   ├── jobs_service.py   # CRUD + trigger + scheduler de jobs
│   │   │   ├── jobs_scheduler.py # APScheduler: corridas cron automáticas
│   │   │   ├── python_sandbox.py # Sandbox bwrap: aislamiento total + logging de auditoría
│   │   │   ├── charts_service.py # CRUD de gráficas + ejecución via CrudService
│   │   │   ├── reports_service.py # Generación de PDF con ReportLab
│   │   │   ├── connections_service.py # Gestión de conexiones dinámicas
│   │   │   ├── transform_blocks_service.py # CRUD de bloques reutilizables
│   │   │   ├── crud_service.py   # Consultas/CRUD sobre las BDs administradas
│   │   │   ├── resource_monitor.py # CPU/memoria/disco cada 2s + circuit breakers
│   │   │   ├── mongo_service.py  # Operaciones MongoDB
│   │   │   ├── redis_service.py  # Operaciones Redis
│   │   │   └── qdrant_service.py # Operaciones Qdrant
│   │   ├── http/
│   │   │   ├── kernel.py         # Registro de middlewares y handlers de excepción
│   │   │   ├── dependencies.py   # Dependencias FastAPI compartidas
│   │   │   └── middlewares/
│   │   │       ├── audit_log.py  # Logging de cada request HTTP (ops/security/errors)
│   │   │       ├── error_handler.py # Manejo uniforme de excepciones → JSON
│   │   │       ├── ip_allowlist.py  # Allowlist de IPs (opt-in)
│   │   │       └── request_context.py # Context var para usuario/IP en el hilo
│   │   ├── models/               # Pydantic request/response models
│   │   └── support/
│   │       ├── audit_logger.py   # Loggers por categoría con rotación diaria
│   │       ├── crypto.py         # Cifrado de contraseñas de conexiones (XOR + JWT_SECRET)
│   │       ├── dates.py          # Normalización de fechas GMT-5
│   │       └── file_export.py    # Exportación CSV/XLSX/JSON/XML
│   └── logs/                     # Logs generados en runtime
│       ├── ops.log               # Operaciones normales
│       ├── security.log          # Eventos de seguridad (90 días de retención)
│       ├── jobs.log              # Ciclo de vida de jobs y sandbox
│       └── errors.log            # Errores (7 días de retención)
│
├── frontend/                     # React 19 + Vite
│   ├── package.json
│   └── src/
│       ├── App.jsx               # Shell principal: routing por tipo de pestaña, sidebar contextual
│       ├── store/
│       │   └── AppContext.jsx    # Estado global: auth, tabs (persistencia cross-device), theme
│       ├── api/
│       │   └── client.js         # Cliente HTTP axios: interceptores, manejo de errores, API calls
│       ├── components/           # UI components
│       │   ├── TabsBar.jsx       # Barra de pestañas con persistencia automática
│       │   ├── StatusBar.jsx     # Barra de estado inferior con duración en ms
│       │   ├── SqlEditorTab.jsx  # Editor SQL + autocompletado de esquema
│       │   ├── JobCanvas.jsx     # Canvas visual drag & drop de pipelines
│       │   ├── JobEditorTab.jsx  # Editor completo de job
│       │   ├── ChartsTab.jsx     # Vista de gráficas con Recharts
│       │   ├── DashboardTab.jsx  # Dashboard de inicio
│       │   └── ...
│       ├── hooks/
│       │   └── useSqlCompletion.js # Autocompletado SQL por schema de BD
│       └── utils/
│           └── sqlUtils.js       # Detección de bindings y modo de query
│
├── job_outputs/                  # Archivos generados por pasos de exportación
├── job_uploads/                  # Archivos subidos para pasos file_input
└── job_sandbox/                  # Directorio temporal del sandbox Python (auto-limpiado)