From ee27f4e3fd332880403471a2f9854ecff4aa9042 Mon Sep 17 00:00:00 2001
From: Dusan Vojacek <dusan.vojacek@direct.cz>
Date: Sun, 19 Apr 2026 14:17:14 +0200
Subject: [PATCH] doc - plan explain

---
 .cursor/rules/plan-explain-bundle.mdc | 33 +++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)
 create mode 100644 .cursor/rules/plan-explain-bundle.mdc

diff --git a/.cursor/rules/plan-explain-bundle.mdc b/.cursor/rules/plan-explain-bundle.mdc
new file mode 100644
index 0000000..3ecefcc
--- /dev/null
+++ b/.cursor/rules/plan-explain-bundle.mdc
@@ -0,0 +1,33 @@
+---
+description: Jak z DB vytáhnout snapshot plánu (vysvětlení „proč je plán takový“) bez zbytečných tokenů
+globs:
+alwaysApply: false
+---
+
+# Vysvětlení plánu z databáze (tokenová efektivita)
+
+Když uživatel ptá na **důvod tvaru plánu** (např. nejbližších **6 hodin**, nabíjení/vybíjení, export, EV, TČ, ceny), **nejprve** si stáhni jeden balík z DB — **nevymýšlej dotazy znovu od nuly**.
+
+## 1) Primární zdroj (doporučeno)
+
+```sql
+SELECT ems.fn_plan_explain_bundle(<site_id>, 6);
+```
+
+- Druhý argument = počet hodin od **začátku aktuálního 15min slotu** (UTC, stejně jako `planning_engine._current_slot_start`).
+- Vrací **jeden JSONB**: aktivní `planning_run`, `planning_interval` jen v okně, `site_operating_mode`, `asset_battery`, `site_grid_connection`, `asset_heat_pump`, otevřené `ev_session`, poslední řádky `forecast_correction_log`, překrývající se `site_override`, metadata + krátký `ai_readme` s odkazy na kód.
+
+Pokud `error = no_active_plan`, v odpovědi uveď že aktivní plán v DB není (404 i u API `/plan/current`).
+
+## 2) Co z JSONu číst při odpovědi
+
+- **Proč baterie / síť**: `intervals_next_window` → `battery_setpoint_w`, `grid_setpoint_w`, `effective_buy_price` / `effective_sell_price`, `is_predicted_price`, vstupy `load_baseline_w`, `pv_*_forecast_*_w`, výstup `pv_a_curtailed_w`.
+- **Provozní rámec**: `operating_mode.mode_code` (AUTO vs CHARGE_CHEAP vs …) — LP constraints v `solve_dispatch()`.
+- **Limity**: `site_grid_connection`, `asset_battery` (`min_soc_percent`, `reserve_soc_percent`, `usable_capacity_wh`, degradace).
+- **EV deadline**: `ev_sessions_open` + sloupce `target_deadline` / `target_soc_pct` v kontextu intervalů (`ev1_setpoint_w`, `ev2_setpoint_w`).
+- **Rolling vs daily**: `active_planning_run.run_type`, `triggered_by`, `forecast_correction_factor`, `replan_from`, `soc_at_replan_wh`.
+- **Váhy LP podle vzdálenosti od začátku horizontu**: u každého intervalu je `hours_from_plan_horizon_start`; mapování 0–36h / 36–72h / 72–96h je v `ai_readme` a v `CLAUDE.md`.
+
+## 3) Volitelně (UI stejné jako dashboard)
+
+REST `GET /api/v1/sites/{site_id}/plan/current` vrací širší horizont než 6 h; pro **vysvětlování** preferuj `fn_plan_explain_bundle`, aby výstup byl úzký a jednorázový.