nova stranka flow a obsluha

docs/04-modules/energy-flows.md

@@ -0,0 +1,41 @@
+# Analýza energetických toků (Fáze 2)
+
+## Účel
+
+Stránka **Toky** (`/energy-flows`) zobrazuje **modelované** směrové toky energie mezi FVE, sítí, baterií a spotřebou za den / měsíc. Nejedná se o přímé měření větví u střídače, ale o **prioritní alokaci** z minutové telemetrie.
+
+## Výpočet
+
+Funkce `ems.fn_fill_audit_interval` pro každý 15min slot:
+
+1. Načte minutové řádky `ems.telemetry_inverter` (`pv_power_w`, `load_power_w`, `grid_power_w`, `battery_power_w`).
+2. Pro každou minutu aplikuje alokaci (pořadí): PV → spotřeba → nabíjení baterie → export; pak vybití baterie → spotřeba / export; síť → zbytek spotřeby a nabíjení.
+3. Součet výkonů × 1/60 h = Wh za slot; výsledek v sloupcích `flow_*_wh` v `ems.audit_interval`.
+
+Sloupce: `flow_pv_to_load_wh`, `flow_pv_to_batt_wh`, `flow_pv_to_grid_wh`, `flow_batt_to_load_wh`, `flow_batt_to_grid_wh`, `flow_grid_to_load_wh`, `flow_grid_to_batt_wh`.
+
+Základní 6 Wh veličin (import/export, PV, baterie, load) zůstává ve Fázi 1; toky jsou nadstavba.
+
+## API
+
+- `GET /api/v1/sites/{site_id}/energy-flows/daily?month=YYYY-MM`
+- `GET /api/v1/sites/{site_id}/energy-flows/daily/{day}/intervals`
+
+## SQL
+
+- View `ems.vw_energy_flows_daily` – denní agregace z `audit_interval`.
+- PostgREST role `ems_anon`: `GRANT SELECT` na `vw_energy_flows_daily` (viz repeatable grants).
+
+## UI
+
+- Sankey (`@nivo/sankey`) – součet toků za zvolený měsíc.
+- Tři perspektivní karty (FVE / síť / baterie).
+- Tabulka dnů s rozbalením na 15min intervaly.
+
+## Backfill
+
+Po nasazení migrace V042 a opakovatelné rutiny:
+
+```sql
+SELECT ems.fn_fill_audit_range(<site_id>, '<od>'::timestamptz, now());
+```