Guía técnica y manual de usuario

Arquitectura técnica

Backend hexagonal en cuatro capas: la dependencia siempre apunta hacia adentro y solo dos archivos, los composition roots, conectan interfaces con implementaciones.

flowchart LR
  U["Analista"] --> W["Sitio web
Next.js 16 + React 19"]
  W -->|"reescribe /api/v1/*"| A["API REST
FastAPI"]
  A --> D[("DuckDB
hidrologia.duckdb")]
  S["Sincronizador
CLI Python"] --> D
  S --> X["SIMEM y API de XM"]
  I["Importador de Outputs
CLI Python"] --> D
  O["Excel del modelo
de largo plazo"] --> I

sequenceDiagram
  actor U as Usuario
  participant W as Sitio (Next.js)
  participant A as API (FastAPI)
  participant C as Caso de uso
  participant R as Repositorios
  participant D as DuckDB
  U->>W: Abre el tablero
  W->>A: GET /api/v1/embalses/resumen
  A->>C: ObtenerResumenNacional.ejecutar()
  C->>R: última medición por embalse
  R->>D: SELECT ... FROM mediciones
  D-->>R: filas
  R-->>C: entidades del dominio
  C-->>A: DTO con KPI, regiones y embalses
  A-->>W: JSON
  W-->>U: tarjetas, gráficos y tabla

Modelo de datos

Un solo archivo DuckDB de unos 11 MB: cuatro tablas de embalses y las de cada modelo analítico (carbón, DNS y los resultados de gas, optimización y apagón). Una conexión única se serializa con un lock, porque FastAPI atiende peticiones en varios hilos.

Diccionario de datos de mediciones

Los 24 embalses por región

Integraciones y fuentes de datos

Cuatro fuentes de datos y tres servicios de plataforma. Ninguna fuente requiere credenciales: SIMEM y la API de XM son públicas.

Modelo de cargue e integración de datos

Cómo llega un dato desde XM hasta un tablero: descarga, normalización, carga idempotente en DuckDB, servicio por API y lectura en el sitio. Este apartado es la base para construir tableros nuevos.

4.1 Diagrama de flujo de datos

flowchart LR
  subgraph FUENTES["Fuentes públicas"]
    S1["SIMEM 138ED1
volumen y capacidad"]
    S2["SIMEM 1445AC
descargas"]
    S3["SIMEM 02B289
aportes por río"]
    X1["API XM
energía y capacidad GWh"]
  end
  subgraph CARGUE["Cargue (CLI Python)"]
    C["Clientes HTTP
bloques de 30 días"] --> N["Normalización pura
unidades y mapeo río→embalse"]
    N --> U["Upsert idempotente
desde última fecha − 7 días"]
  end
  subgraph MODELO["Modelo de largo plazo"]
    E["Excel P10/P50/P90"] --> V["Importador con validaciones"]
  end
  S1 & S2 & S3 & X1 --> C
  U --> M[("mediciones
embalses
fuente_datos")]
  V --> P[("proyecciones_senda")]
  M --> API["API FastAPI
solo lectura"]
  P --> API
  API --> SITIO["Sitio Next.js
reescritura /api/v1/*"]
  SITIO --> T["Tableros"]

4.2 Mapa de conexión interactivo

Toca cualquier elemento: el mapa resalta lo que lo alimenta o lo consume y muestra su ficha.

4.3 Secuencia de una sincronización

sequenceDiagram
  actor O as Operador
  participant CLI as sincronizar.py
  participant SI as SIMEM
  participant XM as API de XM
  participant DB as DuckDB
  O->>CLI: --fuente simem (API local detenida)
  CLI->>DB: última fecha guardada
  DB-->>CLI: 2026-09-22
  Note over CLI: desde = última fecha − 7 días
  CLI->>SI: 138ED1, 1445AC, 02B289 (desde..hasta)
  SI-->>CLI: filas por embalse y día
  loop bloques de 30 días
    CLI->>XM: VoluUtilDiarEner y CapaUtilDiarEner
    XM-->>CLI: kWh por embalse
  end
  Note over CLI: convierte m³ a Mm³, m³/día a m³/s, kWh a GWh
y asigna cada río a su embalse
  CLI->>DB: upsert de mediciones y embalses
  CLI->>DB: fuente_datos (corte, es_real)
  CLI-->>O: Sincronizado: 24 embalses, fecha de corte
  O->>O: scripts/desplegar-vercel.sh

4.4 Periodicidad

4.5 Linaje de datos por tablero

Elige un tablero para ver el camino completo de sus datos, desde la fuente hasta el componente que los dibuja.

4.6 Controles de calidad en el cargue

4.7 Cómo construir un tablero nuevo

El patrón es el mismo para todos los tableros existentes. Marca los pasos a medida que avanzas; el progreso queda en tu navegador.

Copiar# Cargar y publicar datos nuevos
cd backend && source .venv/bin/activate
python -m infrastructure.ingesta.sincronizar --fuente simem          # con la API local detenida
python -m infrastructure.ingesta.importar_proyeccion --xlsx "<ruta>/proyeccion_montecarlo_enso <fecha>.xlsx"
cd .. && scripts/desplegar-vercel.sh                                  # publica la API con la base actual

Importadores de los modelos analíticos

Los modelos no se descargan de una API: sus salidas se importan desde la carpeta de cada proyecto. Todos validan los archivos antes de escribir, reemplazan en una transacción (si algo falla queda la corrida anterior) y no se borran con --reiniciar.

Cálculos y modelos

Los cálculos hidráulicos son funciones puras en domain/services; los agregados y las proyecciones se arman en application.

%V. útil y nivel de riesgo

%V_útil = volumen útil del día ÷ capacidad útil del día × 100

La capacidad es la que XM publica ese mismo día, porque la revisa con el tiempo. La clasificación tiene cinco niveles y es la misma para embalses, regiones y el sistema.

Agregados nacional y regional

El %V. útil de un conjunto de embalses es el promedio ponderado por la capacidad útil en energía (GWh) de cada embalse ese día, como hace la métrica oficial de XM. Un embalse de caída alta almacena mucha más energía por metro cúbico que uno de caída baja.

%V_agregado = Σ(%V_i × w_i) ÷ Σ w_i        con w_i = capacidad útil en energía (GWh)

Reproduce el agregado oficial del SIN con un error medio de 0,046 puntos porcentuales sobre 1.725 días. Incluye el Agregado Bogotá.

Aportes, autonomía y capacidad guardada

Aportes %   = Σ aportes (m³/s) ÷ Σ media histórica (m³/s) × 100      (solo embalses con ambos datos)
Autonomía   = volumen útil ÷ (turbinado + vertimientos − aportes)          (Mm³/día; None si aportes ≥ salidas)
Capacidad guardada = Σ energía útil almacenada (GWh)                       (si falta, no se suma)

La autonomía no incluye evaporación porque XM no la publica, y en embalses en cadena (por ejemplo Punchiná) puede resultar engañosamente baja.

Proyección de largo plazo y pronóstico diario

API REST

Disponible en https://plataforma-embalses-api.vercel.app (local: http://localhost:8000) con OpenAPI en /docs. Todas las rutas cuelgan de /api/v1.

Plataformas, despliegue y operación

El sitio se despliega solo por Git y la API se publica a mano, porque la base de datos no está en el repositorio.

flowchart TD
  PR["Pull request"] --> CI{"CI: backend y frontend"}
  CI -->|"falla"| PR
  CI -->|"verde"| M["Merge con squash a main"]
  M --> VS["Vercel publica el sitio"]
  L["Cargue local de datos"] --> SC["desplegar-vercel.sh"] --> VA["Vercel publica la API
con la base nueva"]
  VS -. "reescribe /api/v1/*" .-> VA

Procedimientos de mantenimiento

1. Actualizar datos: detener la API local, sincronizar y publicar la API.
2. Corrida nueva del modelo: importar el Excel y publicar la API.
3. Cambiar el sitio: PR con chequeos en verde y merge con squash. Si depende de endpoints nuevos, publicar la API antes del merge.
4. Nunca desplegar el sitio con vercel deploy desde frontend/.
5. Credenciales: vercel link deja un token temporal en .env.local; el script lo retira y .env* está ignorado por git.

Calidad y pruebas

1.050 pruebas automatizadas (583 de backend, 430 unitarias de frontend y 37 de extremo a extremo con navegador real), sin red ni base externa, en cada pull request. Se comprobó que detectan fallos introduciendo regresiones a propósito.

Mapa de la pantalla

Se entra por tableros-analiticos.vercel.app desde cualquier navegador actual, sin usuario ni contraseña. Toca una zona para ir a su capítulo.

El encabezado y el pie

• Corte al …: fecha del último dato disponible. Todo lo que ves corresponde a ese día. XM publica con uno o dos días de rezago.
• Botón de tema: alterna claro y oscuro; se recuerda en tu navegador y, la primera vez, sigue el sistema.
• Pie: muestra Datos reales, la fuente y el corte. Si los datos fueran de demostración diría Datos no reales en ámbar.

Filtros

Cuatro campos iguales y un botón. Cada uno tiene un botón ⓘ con su explicación.

Región y embalse gobiernan todo el tablero a la vez: tarjetas, gráfico principal, distribución regional, senda de largo plazo y tabla. Las fechas solo mueven el histórico diario del gráfico principal.

• Al abrir la página los filtros están en «Todas las regiones» y «Todos los embalses»: el gráfico principal y la senda muestran el total nacional.
• Al cambiar de región, el embalse vuelve a «Todos los embalses» y todo muestra el agregado de esa región.
• «Todos los embalses» muestra el total nacional o, con región, el agregado de esa región; elegir un embalse lo reduce todo a ese embalse.
• Un clic en una fila de la tabla elige ese embalse. La tabla queda con una sola fila: elige «Todos los embalses» o pulsa Restablecer para volver.
• “Desde” no puede pasar de “Hasta”, y viceversa.
• Restablecer filtros devuelve región y embalse a “Todos” y las fechas a 180 días.

Estados que conviene ver

Tarjetas de indicadores

Cuatro tarjetas de igual tamaño resumen el estado del sistema en el último corte.

Un guion “—” significa que XM no publicó el dato; nunca es un cero.

Gráfico principal: %V. útil vs. aportes y proyección

La historia reciente y el futuro esperado del embalse elegido. Con “Todos los embalses” muestra el total nacional o el de la región.

• 1m, 3m, 6m, 12m: cuánto se proyecta: 30, 90, 180 o 360 días. Con 12 meses llega a mediados de septiembre de 2027: la curva termina donde publica el modelo, así que cuantos más días pasan desde su corrida, menos días se proyectan.
• Si el subtítulo dice “escenarios P10–P90”, la banda no es un intervalo de confianza. Si dice “IC 95%”, es el respaldo Holt-Winters (Agregado Bogotá y agregados regionales), que no incorpora el clima.
• El eje vertical se ajusta a los datos: los picos de aportes lo estiran.

Distribución regional del %V. útil

Barras horizontales de menor a mayor. Cada barra promedia los embalses de la región ponderados por energía.

• El color sigue el riesgo: verde normal, cian estable, ámbar alerta temprana, naranja situación delicada y rojo crítico. Al corte del 25-oct-2026, Oriente está en Normal; Antioquia, Caribe, Caldas y Centro en Estable; y Valle en Situación delicada.
• Al pasar el cursor por una barra aparece su valor. Con una región elegida solo se muestra esa región, y con un embalse elegido, solo la región a la que pertenece.

Oriente (88,5 %) es la única región en Normal y Valle (58,3 %) la única en Situación delicada. Caldas (38,7 %) y Antioquia (54,0 %) tienen los aportes más bajos frente a su media.

Senda del volumen útil: proyección de largo plazo

El %V. útil mensual observado desde enero de 2022 y su proyección, por defecto para el total nacional.

• Semáforo de la senda: rojo bajo 55 %, ámbar bajo 65 %, verde desde 65 %. Es distinto de la clasificación de cinco niveles porque juzga un mínimo futuro.
• Con la proyección del modelo aparece un recuadro azul “Sobre esta proyección” en lugar de la tabla de validación, porque los Outputs no traen validación fuera de muestra.
• Con el respaldo Holt-Winters (Agregado Bogotá) aparece la tabla walk-forward: modelo, MAE y R² contra la persistencia.

Tabla de embalses y reportes

Una fila por embalse con el dato más reciente. Sigue los filtros: con una región muestra sus embalses (con Centro, 6 filas) y con un embalse elegido, solo esa fila.

• Ordenar: clic en un encabezado; otro clic invierte. Arranca por % Vol. útil de menor a mayor.
• Buscar: por nombre o región mientras escribes.
• Seleccionar: clic en una fila la resalta y cambia el gráfico principal. Los enlaces CSV/JSON no cambian la selección.

Copiarfecha,pct_volumen_util,energia_util_gwh,aportes_m3s,aportes_pct_media,vertimientos_m3s,turbinado_m3s

Archivo <CODIGO>_reporte.csv (por ejemplo PENOL_reporte.csv). Una celda vacía es un dato no publicado, nunca un cero. Para otro rango: GET /api/v1/embalses/{id}/reporte?formato=csv&fecha_inicio=…&fecha_fin=….

Panel principal: Tableros Analíticos

La página de inicio (/) es el acceso a todos los tableros. Está organizada en dos grupos para que se vea de un vistazo qué ya muestra resultados y qué todavía no.

• Dos accesos por tarjeta: el título abre el tablero (toda la tarjeta es clicable) y «Guía de este tablero» abre el capítulo de esta guía que lo explica.
• Cada tarjeta dice en una frase qué se puede ver, tres temas concretos y de dónde salen los datos.
• Dentro de cualquier tablero, el botón Tableros del encabezado vuelve al panel y Información abre esta guía en otra pestaña.
• Un tablero nuevo se agrega con una entrada en frontend/lib/tableros.ts, su ruta en frontend/lib/rutas.ts y una carpeta en app/; el panel lo muestra solo.

Rutas y direcciones: cada vista tiene su URL

Cada tablero tiene una ruta propia y cada filtro y cada alternancia queda en la dirección de la página. Puedes copiar el enlace para compartir la vista exacta, recargar sin perderla o volver con «atrás». Lo que vale su valor por defecto no aparece en la dirección.

• Ejemplo: /dns?periodo=12&region=Caribe&origen=programada abre el tablero de demanda no atendida de los últimos 12 meses, en el Caribe, solo eventos programados.
• Direcciones alternativas: /tableros, /demanda-no-atendida, /riesgo-apagon, /gas-natural y otras redirigen a la ruta canónica.
• Seguridad: cada parámetro se valida contra la misma lista cerrada que acepta la API. Un valor inválido (por ejemplo horizonte=2) se ignora y queda el valor por defecto; nunca llega a la API ni rompe la página.
• Historial: cambiar un filtro reemplaza la entrada del historial (no la apila), así «atrás» vuelve a la pantalla anterior y no al filtro anterior.
• Una dirección que no existe muestra una página 404 con el camino de vuelta al panel y la lista de tableros.

Tablero de carbón térmico: mapa de la pantalla

Mismo esquema que el de embalses: encabezado, filtros, tarjetas, gráficos y detalle. Toca un número para ver qué es cada zona.

Filtros del tablero de carbón

Cuatro campos y «Restablecer filtros». Solo ofrecen valores que la API acepta; cada uno tiene su botón ⓘ.

• kt/día = GBTU/día ÷ 26,27 (poder calorífico, MBTU/t).
• Restablecer filtros devuelve los cuatro a su valor por defecto.

Tarjetas de indicadores del carbón

Gráficos del tablero de carbón

• Consumo de carbón térmico: línea azul = observado (solo meses completos), línea punteada oscura = proyección P50, banda = escenarios P10–P90; las líneas horizontales son el techo (rojo) y el récord (ámbar). Si el mes en curso tiene datos parciales, una nota los informa aparte.
• Consumo por trimestre (Mt): barras P50 y tabla con P10–P90. Un trimestre que no cabe completo en el horizonte se atenúa y se rotula «parcial».
• Inventario requerido (kt): barras por mes, P50 (central) y P90 (adverso).
• Modelo frente a XM: proyección P50 y banda frente al caso estocástico de XM; avisa en cuántos meses XM supera el techo físico: consulta a XM ese supuesto antes de usarlo como referencia.

Validación, supuestos y limitaciones

• Criterios: el modelo cumple 35 de 38 criterios de validez. Primero se muestran los que no cumplen (son limitaciones reales); los que cumplen están en un desplegable.
• Error medio (MAE) por horizonte: compara el modelo con métodos ingenuos (persistencia, estacional, climatología).
• Episodios críticos: cómo se habría comportado en El Niño 2014-16, 2018-19 y 2023-24 (real, P50, error y cobertura P10–P90).
• Supuestos: ecuaciones, muestra de estimación, techo, simulaciones, poder calorífico y la proyección de XM comparada. La proyección no reemplaza el despacho ni el análisis de XM.

Tablero de demanda no atendida (DNS): mapa de la pantalla

Analiza los eventos de demanda no atendida (la energía que el sistema deja de suministrar) y de desconexión automática de carga (EDAC) que se reportan a SIMEM por subárea operativa, desde 2013. Toca un número para ver qué es cada zona.

Filtros y tarjetas del tablero DNS

• Eventos y energía no atendida: la variación es frente al período anterior de igual duración; subir es desfavorable (rojo) y bajar favorable (verde). Con «todo el histórico» no hay con qué comparar.
• Eventos críticos: los que dejan sin atender 100 MWh (100.000 kWh) o más.
• Eventos no programados: los que no estaban planeados; debajo se informa cuántos EDAC hubo.
• Restablecer filtros devuelve los cuatro a su valor por defecto.

Gráficos, causas y modelo predictivo

• Serie mensual: eventos o energía (botones Eventos / Energía). El último mes está atenuado si aún no termina. El punto de pronóstico es lo que el modelo estima para ese mes sumando las subáreas del filtro.
• Paneles ampliables: «Priorización de zonas» y «Modelo predictivo» son largos, así que por defecto miden lo mismo que el panel de al lado (para conservar la simetría) y se desplazan por dentro. El botón Ver todo los extiende para ver todos los datos y Ver menos los devuelve; el estado queda en la dirección (?ampliar=zonas,modelo).
• Priorización de zonas: índice 0-100 con magnitud (40 %), frecuencia (20 %), criticidad (20 %) y tendencia (20 %); los pesos son una decisión editorial. En rojo, las zonas cuya energía de los últimos 24 meses empeoró frente a los 24 previos.
• Patrones: por hora, día y franja. Se excluyen los eventos con «hora desconocida» (00:00:00 exacto, valor por defecto de SIMEM).
• Causas: la reportada por el operador o, si falta, inferida del texto (reglas y TF-IDF). Se avisa qué porcentaje es inferido.
• Cambios en la forma de reportar: subáreas con más descripciones genéricas y menos causa conocida desde un mes; explican parte del aumento de eventos en 2024-2025.
• Modelo predictivo: error (MAE, RMSE) de cada algoritmo frente a la persistencia; un modelo que no la supera no se reporta como exitoso.

Tableros de gas, optimización hidrotérmica y riesgo de apagón

Los tres tienen la misma estructura. Gas y apagón ya tienen resultados importados; optimización solo tiene una prueba técnica sin resultados, así que muestra la ficha y cómo cargarlos. Nunca se inventan cifras. La captura muestra el estado de un modelo sin resultados.

• Estado: «Sin resultados publicados» (ámbar), «Prueba técnica: no publicable» (rojo) o «Con resultados importados» (verde).
• Cifras documentadas: datos que ya están en los documentos; cada tarjeta dice de cuál.
• Ficha: pregunta, método, datos, alcance, limitaciones y siguientes pasos, en secciones plegables.
• Con resultados aparecen los filtros del modelo y Desde / Hasta, que recortan a la vez todos los gráficos y tablas, además de indicadores con nivel, advertencias y la procedencia de la corrida. Las líneas punteadas son referencias (por ejemplo, la curva de Arps).

Actualizar los tableros con archivos

La página /actualizar (enlace «Acceso para actualizar datos» al pie del panel) permite cargar los archivos nuevos de un modelo sin usar la línea de comandos. Requiere una cuenta; cada acceso y cada carga queda registrado.

• Roles: el administrador actualiza todos los tableros y ve la bitácora; el cargador solo los que se le asignaron.
• Riesgo de apagón (visor): el módulo no ejecuta el modelo. Se genera la tanda de 468 escenarios con importar_escenarios_apagon --exportar-csv y se carga el CSV.
• Sin base externa: si el entorno no guarda datos de forma permanente, puedes revisar archivos pero no aplicarlos (la página lo avisa).

Ayuda contextual, tema y preguntas frecuentes

Botones de ayuda ⓘ

Cada encabezado técnico, filtro, selector y columna tiene un botón circular azul claro.

Cursor encima	Aparece la explicación; se oculta al salir
Tecla Tab	Se muestra al enfocar
Toque en celular	Abre; tocar fuera cierra
Escape, scroll o redimensionar	Cierra

Tema oscuro y celular

Preguntas frecuentes

Límites conocidos y glosario

Fuentes y referencias

Cifras y comportamientos salen del código y la base de la plataforma al corte del 25-oct-2026, de las pruebas automatizadas y de las comparaciones contra los insumos y resultados del modelo de largo plazo. SIMEM y la API de XM se consumen mediante los clientes del backend; no se consultaron sus portales para redactar esta guía.

• Repositorio, README y pruebas
• Sitio en producción · API y OpenAPI
• Ministerio de Minas y Energía: paleta GOV.CO, tipografías y logos
• Insumos del modelo (138ED1, 1445AC, 02B289, 1d3ef8, NOOA) y resultados (resultados 20260923.xlsx, proyeccion_montecarlo_enso 20260923.xlsx) en la carpeta 1. Modelo niveles de embalses del proyecto de modelado