┌─────────────────────────────────────────────────────────┐
│  Frontend  (React 18 + Vite)                            │
│  • Editor SQL con autocompletado (CodeMirror)           │
│  • Canvas visual de pipelines (@xyflow/react)           │
│  • Dashboard, Gráficas (Recharts), Reportes PDF        │
└────────────────────┬────────────────────────────────────┘
                     │ HTTP / REST (Bearer JWT)
┌────────────────────▼────────────────────────────────────┐
│  Backend  (FastAPI + Python)                            │
│  • /db/v1/*           Administración de bases de datos  │
│  • /jobs/v1/*         Motor de pipelines y jobs         │
│  • /charts/v1/*       Gráficas guardadas                │
│  • /reports/v1/*      Reportes PDF                      │
│  • /transform-blocks/v1/* Bloques reutilizables         │
│  • /admin/users/*     Gestión de usuarios ACL           │
│  • /oauth/token       Autenticación JWT                 │
└──────┬──────────────────────────┬───────────────────────┘
       │                          │
┌──────▼──────┐          ┌────────▼──────────────────────┐
│ app_state   │          │  Bases de datos administradas  │
│ (SQLite /   │          │  MySQL / PostgreSQL / SQLite   │
│  MySQL /    │          │  (una o varias, configuradas   │
│  PostgreSQL)│          │   en .env como SERVERS)        │
│             │          └────────────────────────────────┘
│ users_acl   │
│ charts      │
│ jobs        │
│ job_runs    │
│ job_run_steps│
│ reports     │
│ transform_  │
│ blocks      │
└─────────────┘

cd python_api
pip install -r requirements.txt

# Configurar variables (ver sección Variables de entorno)
cp ../.env.example ../.env
# Editar .env con los datos de los servidores de BD

# Arrancar (desarrollo)
cd ..
./run-dev-mysql.sh
# o: ENABLE_ACL=true ./run-dev-mysql.sh

# El backend queda en http://localhost:3560
# 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/

cd python_api
python hash_password.py MiPassword123!
# Copia el hash y ejecuta el endpoint POST /admin/users con admin auth
# o importa acl_users.json.example como acl_users.json antes del primer arranque

SERVERS='{
  "produccion": {
    "type": "mysql",
    "host": "db.empresa.com",
    "port": 3306,
    "user": "dbstudio",
    "password": "secreto",
    "databases": ["crm", "ventas", "logistica"]
  },
  "analytics": {
    "type": "postgresql",
    "host": "analytics.empresa.com",
    "port": 5432,
    "user": "readonly",
    "password": "otro_secreto",
    "databases": ["warehouse"]
  }
}'

APP_DB_URL=mysql+pymysql://usuario:clave@servidor:3306/dbstudio_meta
# o
APP_DB_URL=postgresql+psycopg://usuario:clave@servidor:5432/dbstudio_meta

admin                               Acceso total — bypasea todo lo demás

# Bases de datos
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 y CTEs
db:<bd>:table:<tabla>:read          Lectura granular a una tabla
db:<bd>:table:<tabla>:write         Escritura granular a una tabla
db:*:read / db:*:write / etc.       Wildcard — aplica a todas las BDs

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

# Módulos de la aplicación
charts:read / charts:write          Gráficas guardadas
reports:read / reports:write        Reportes PDF
jobs:read / jobs:write              Definiciones de jobs
jobs:execute                        Disparar corridas manuales
jobs:python                         Guardar pasos con código Python (sandbox)
transform_blocks:read / :write      Bloques de transformación reutilizables

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

username=ana&password=secreto

# Datos de la última salida exitosa de un step (para polling periódico)
GET /jobs/v1/{job_id}/data/{step_id}
→ {"data": [...filas...], "count": N, "meta": {...}}

# Archivo de la última salida (CSV, JSON, XML, PNG, XLSX)
GET /jobs/v1/{job_id}/latest-output/{step_id}
→ archivo con Content-Type apropiado (sin forced download)

# Datos de una gráfica guardada
POST /charts/v1/{chart_id}/data
→ {"data": [...filas...], "meta": {...}}

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

[2026-07-01 14:32:01] INFO     dbstudio.ops  REQUEST_OK  method=POST  path=/db/v1/cte  user=ana  ip=10.0.0.5  status=200  duration_ms=142  db=crm
[2026-07-01 14:32:05] INFO     dbstudio.security  LOGIN_OK  username=ana  ip=10.0.0.5  status=200  duration_ms=38
[2026-07-01 14:33:00] INFO     dbstudio.jobs  RUN_START  job_id=3  job_name="Export diario"  run_id=17  trigger=schedule  user=sistema  steps=4
[2026-07-01 14:33:02] INFO     dbstudio.jobs  RUN_COMPLETE  job_id=3  job_name="Export diario"  run_id=17  trigger=schedule  user=sistema
[2026-07-01 14:40:01] WARNING  dbstudio.security  LOGIN_FAIL  username=hacker  ip=192.168.1.100  status=401  duration_ms=250

api-mysql/
├── .env                          # Variables de entorno (no commitear)
├── .env.example                  # Plantilla de configuración
├── run-dev-mysql.sh              # Script de arranque del backend
├── hash_password.py              # CLI para generar hashes bcrypt
├── acl_users.json.example        # Ejemplo de usuarios ACL
│
├── python_api/                   # Backend FastAPI
│   ├── app/
│   │   ├── main.py               # App factory, routers, Swagger x3
│   │   ├── api/                  # Routers HTTP
│   │   │   ├── jobs.py           # /jobs/v1/*
│   │   │   ├── charts.py         # /charts/v1/*
│   │   │   ├── reports.py        # /reports/v1/*
│   │   │   ├── transform_blocks.py # /transform-blocks/v1/*
│   │   │   ├── admin_users.py    # /admin/users/*
│   │   │   └── oauth.py          # /oauth/token
│   │   ├── core/
│   │   │   ├── acl.py            # Motor de scopes
│   │   │   ├── acl_users.py      # CRUD de usuarios en BD
│   │   │   ├── config.py         # Settings via pydantic-settings
│   │   │   └── security.py       # JWT (emisión y validación)
│   │   ├── db/
│   │   │   ├── app_state.py      # Motor SQLAlchemy para estado propio
│   │   │   ├── models_app.py     # ORM: UserModel, ChartModel, JobModel...
│   │   │   └── connection.py     # Pool de conexiones a BDs administradas
│   │   ├── services/
│   │   │   ├── jobs_engine.py    # Motor de ejecución de pipelines
│   │   │   ├── jobs_service.py   # CRUD + scheduler de jobs
│   │   │   ├── python_sandbox.py # Sandbox bwrap para python_transform
│   │   │   ├── charts_service.py
│   │   │   ├── reports_service.py
│   │   │   └── transform_blocks_service.py
│   │   ├── http/
│   │   │   └── middlewares/
│   │   │       └── audit_log.py  # Middleware de logging por request
│   │   └── support/
│   │       └── audit_logger.py   # Loggers por categoría con rotación
│   └── requirements.txt
│
├── frontend/                     # React + Vite
│   ├── src/
│   │   ├── App.jsx               # Shell principal + routing por tabs
│   │   ├── components/           # UI components
│   │   │   ├── SqlEditorTab.jsx
│   │   │   ├── JobCanvas.jsx     # Canvas visual de pipelines
│   │   │   ├── JobEditorTab.jsx
│   │   │   ├── ChartsTab.jsx
│   │   │   └── ...
│   │   ├── api/client.js         # Cliente HTTP (axios + manejo de errores)
│   │   ├── hooks/
│   │   │   └── useSqlCompletion.js # Autocompletado SQL por schema
│   │   ├── store/AppContext.jsx  # Estado global (tabs, auth, theme)
│   │   └── utils/sqlUtils.js     # Detección de bindings y modo de query
│   └── package.json
│
├── logs/                         # Logs de la app (generados en runtime)
│   ├── ops.log
│   ├── security.log
│   ├── jobs.log
│   └── errors.log
│
├── job_outputs/                  # Archivos generados por jobs
└── job_uploads/                  # Archivos subidos para pasos file_input