second version

docs/04-modules/forecast.md

@@ -89,10 +89,15 @@ def calculate_pv_power(
 
 | Trigger | Čas | Popis |
 |---|---|---|
-| Scheduled (cron) | každý den 14:30 CET | Po importu cen, před plánováním |
-| Scheduled (cron) | každý den 06:00 CET | Aktualizace predikce na dnešní den |
-| Před plánováním | automaticky | Plánovač zkontroluje čerstvost, spustí pokud starší než 2h |
-| Manual trigger | na vyžádání | `POST /admin/run-forecast?site_id=1&date=YYYY-MM-DD` |
+| Scheduled (cron) | každé 2 hodiny v `:05` | Průběžný refresh forecastu pro všechny aktivní site |
+| Manual trigger | na vyžádání | `POST /api/v1/sites/{site_id}/forecast/run` |
+
+### Implementované provozní změny (2026-03)
+
+- Forecast horizont je konfigurovatelný přes `open_meteo_forecast_days`.
+- Runtime guard: hodnota se clampuje do rozmezí `2..16`.
+- Default je `7` dní.
+- Endpoint `GET /api/v1/sites/{site_id}/forecast/pv?date=YYYY-MM-DD` vrací vždy poslední `ok` run per `(interval_start, pv_array_id)` (`DISTINCT ON`), takže UI nevidí duplikáty z historických běhů.
 
 ---
 
@@ -153,11 +158,21 @@ Viz `03-data-model.md`:
 
 ---
 
+## Tracking přesnosti forecastu
+
+- **`ems.forecast_accuracy`** – pro každý úspěšný `forecast_pv_run` a každý 15min slot ukládá predikovaný výkon, čas vzniku predikce, lead time (hodiny před začátkem slotu), později doplněnou skutečnost z telemetrie a odchylku (`error_w`, `error_pct`). Záznamy se **uchovávají trvale** (včetně všech historických běhů v `forecast_pv_run` / `forecast_pv_interval` – ty se nemazají).
+- **`ems.fn_fill_forecast_accuracy(site_id, lookback_hours)`** – inkrementálně vloží nebo aktualizuje řádky z `forecast_pv_interval` + run metadata a dopočte `actual_power_w` jako průměr 1min telemetrie ve slotu (pole B: `gen_port_power_w`, pole A: `pv1_power_w` + `pv2_power_w`). Volat **každých 15 minut** (např. spolu s audit fillerem); parametr `lookback_hours` omezuje okno zpětného zpracování (např. 48 h běžně, větší hodnota pro jednorázový backfill).
+- **`ems.vw_forecast_accuracy_by_lead_time`** – agregace přesnosti podle bucketů lead time (0–6 h, …, 48 h+); noční sloty s nízkou výrobou (`actual_power_w` ≤ 100 W) se v metrikách typicky vynechávají.
+- **`ems.vw_forecast_accuracy_daily`** – denní součty forecast vs actual v kWh (Praha kalendářní den) a relativní odchylka dne.
+- **Po 4+ týdnech dat** lze statistiky použít pro kalibraci `safety_factor` (nebo obdobných parametrů) v solveru – viz plánovací modul.
+
+---
+
 ## Konfigurace (env proměnné)
 
 ```env
 OPEN_METEO_API_URL=https://api.open-meteo.com/v1/forecast
-FORECAST_HORIZON_DAYS=3
+OPEN_METEO_FORECAST_DAYS=7
 FORECAST_MAX_AGE_HOURS=2      # plánovač odmítne starší predikci
 FORECAST_RETRY_COUNT=3
 ```