zdokumentovani noveho pohleud na planovani nabijeni

2026-06-01 19:53:04 +02:00
parent d44a2cbb44
commit 1429d402e5
7 changed files with 413 additions and 6 deletions
--- a/docs/04-modules/planning-charge-slot-budget.md
+++ b/docs/04-modules/planning-charge-slot-budget.md
@@ -0,0 +1,340 @@
+# Plánování: rozpočet nabíjecích slotů (Wh × ceny × forecast)
+
+**Stav:** návrh k implementaci (2026-06) — **zatím neimplementováno** v produkčním kódu.  
+**Účel:** nahradit tvrdé prahy typu `sell > min_sell + 0,20 → bc_pv = 0` (v58) a binární pre-neg „cushion“ (v33) jednotným **energetickým rozpočtem** ve `fn_load_planning_slots_full`, který pokryje fixní tarify (BA81, KV1), spot (home-01) i zkracující se okna `sell < 0` (zima).
+
+**Související:**
+
+| Dokument | Vztah |
+|----------|--------|
+| [`planning.md`](planning.md) | LP, masky, současné v58–v62 |
+| [`planning-arbitrage-accounting.md`](planning-arbitrage-accounting.md) | proč ne `sell < buy` v jednom slotu |
+| [`planning-neg-sell-strategy.md`](planning-neg-sell-strategy.md) | rampa, tail, pole B — cílové SoC v okně |
+| [`R__063_fn_load_planning_slots_full.sql`](../../db/routines/R__063_fn_load_planning_slots_full.sql) | místo implementace masek |
+| [`planning_engine.py`](../../backend/services/planning_engine.py) | LP jen respektuje masky + objective |
+
+**Changelog (plánované):** [`docs/planning-changelog.md`](../planning-changelog.md) — sekce *Plánováno: charge-slot-budget*.
+
+---
+
+## 1. Problém, který řešíme
+
+### 1.1 Fixní tarif (BA81, KV1) — slunečný den ~60 % SoC
+
+**Symptom:** přes den nabíjení ze slunce jen na ~60–66 %, zbytek FVE jde do sítě při výkupu 2–3 Kč/kWh; nabíjení jen v 2–4 slotech u minima výkupu (~1,45 Kč).
+
+**Příčina (současný kód):**
+
+- `R__063` už počítá `v_energy_to_fill` a vrstvu A (PV) s kumulací Wh, ale u fixního tarifu řadí PV vrstvu podle **`store_score`** (future sell − sell).
+- **`planning_engine` v58:** tvrdě `bc_pv = 0` (a často i `bc_gi = 0`) když `sell > min(sell≥0) + 0,20` — LP **nesmí** nabíjet, i když SQL nastaví `allow_charge = true`.
+
+→ Rozpor mezi maskou a LP; ekonomicky „správný“ export v 10:00 blokuje doplnění baterie, i když večerní arbitráž to nevyžaduje.
+
+### 1.2 home-01 — velká baterie, kratší / slabší okno `sell < 0`
+
+**Symptom:** ráno export FVE před `sell < 0` i při výkupu ~2–3 Kč, zatímco v záporném okně by energie mohla být potřeba víc (krátké okno, slabší zimní FVE).
+
+**Příčina (současný kód):**
+
+- **v33:** `_pre_neg_pv_export_forecast_cushion_ok` — **binární** rozhodnutí: pokud forecast PV v celém denním okně `sell < 0` pokryje deficit do `soc_target[first_neg]` × 1,15 → **všechny** pre-neg sloty s přebytkem → export (`bc_pv = 0`, push `ge_pv`).
+- Neptá se: *kolik Wh musím nabít **před** oknem*, když *uvnitř* okna forecast nestačí.
+- **v44:** na neg den **žádný grid** před 1. `sell < 0` — při nedostatku FVE v okně chybí páka levného NT před oknem.
+
+### 1.3 Společná chyba modelu
+
+| Špatně | Správně |
+|--------|---------|
+| Prah `sell > min + 0,20` | **Kolik Wh** chybí do cíle a **které sloty** je nejlevněji doplní |
+| Binární cushion OK / fail | **pre_window_wh** = max(0, deficit − in_window_wh) |
+| `store_score` u fixního buy | U fixního tarifu řadit **`sell ASC`** (výkup = příležitostní cena uložení) |
+| LP přepisuje SQL masky (v58) | LP **jen** `bc_*` kde `allow_charge`; export kde maska nepřidělila charge budget |
+
+---
+
+## 2. Principy návrhu
+
+1. **SQL-first:** výběr nabíjecích slotů = **`ems.fn_load_planning_slots_full`** (rozšíření `R__063`), ne nové tvrdé větve v `solve_dispatch` kromě stávajících bezpečnostních guardů (load-first, večerní push, neg fáze).
+2. **Energetický rozpočet (Wh), ne Kč prah:** ceny řadí **prioritu slotů**; zastavení kumulace je **`cum_wh ≥ target_wh`** (± `charge_slot_buffer`).
+3. **Forecast v každém slotu:** `pv_surplus_w` = max(0, pv_a + pv_b − load_baseline − …) už ve work tabulce; nabíjecí příspěvek slotu = `min(pv_surplus_w, max_charge_w) × charge_eff × 0,25` (+ volitelně grid `per_slot_charge_wh`).
+4. **Oddělení nákupního a výprodejního okna** — viz [`planning-arbitrage-accounting.md`](planning-arbitrage-accounting.md); `charge_acquisition` z vybraných slotů, ne `min(buy)` celého horizontu.
+5. **Jeden algoritmus, více režimů:** stejná kostra pro spot i fixed; liší se **řazení** (buy vs sell), **cíl SoC** a **výjimky** (neg den, block_export).
+
+---
+
+## 3. Slovník
+
+| Symbol / pole | Význam |
+|---------------|--------|
+| `energy_to_fill_wh` | `soc_max_wh − current_soc_wh` (základní deficit do plné baterie) |
+| `charge_target_wh` | Cíl pro výběr slotů — může být `< soc_max` (rezerva neg okna, safety, večerní export) |
+| `in_window_wh` | Odhad energie do baterie **uvnitř** speciálního okna (např. všechny sloty `sell < 0` téhož pražského dne), z forecastu A+B (+ volitelně grid v okně) |
+| `pre_window_wh` | `max(0, charge_target_wh − in_window_wh × reliability_factor)` — kolik Wh je třeba doplnit **před** oknem |
+| `slot_charge_wh[t]` | Wh, které lze v `t` reálně natočit (PV surplus cap + výkon baterie) |
+| `allow_charge` | SQL maska: LP smí `bc_pv` / `bc_gi` |
+| `allow_grid_charge` | podmnožina: smí `bc_gi` |
+| `charge_slot_reason` | debug: `grid_layer_b`, `pv_layer_a`, `pre_neg_fill`, `neg_window`, `buy_negative`, … |
+
+---
+
+## 4. Jádro algoritmu (společné)
+
+Pro každý běh plánovače (site, horizont, `current_soc_wh`):
+
+### Krok 1 — Cíl energie
+
+```text
+charge_target_wh := min(
+  soc_max_wh − current_soc_wh,
+  optional_cap_from_neg_strategy,   -- viz §6
+  optional_safety_soc_target_wh
+)
+```
+
+- Výchozí: doplnit do **`soc_max_wh`** (s `charge_slot_buffer` z `asset_battery` jako dnes).
+- U **home-01** s neg dnem: cíl na vstupu do okna = **`soc_need[first_neg_sell]`** z rampy (v35/v36), ne fixních 80 %.
+- Rezerva pro okno `sell < 0`: stávající logika `v_pv_layer_cap_wh -= neg_window_pv_surplus_wh` v `R__063` zůstane jako **snížení** `charge_target_wh` před oknem, ne jako samostatný binární export.
+
+### Krok 2 — Dodávka uvnitř speciálního okna (volitelná větev)
+
+Pro každý pražský den s alespoň jedním `sell < 0`:
+
+```text
+in_window_wh := sum over slots t in neg_window(day):
+  min(pv_surplus_w[t], max_charge_w) * charge_eff * 0.25
+  + (optional) grid_wh if allow_grid in neg window (v45)
+```
+
+`reliability_factor` ∈ (0, 1] — např. **0,85** zimní / krátké okno, **1,0** letní dlouhé okno; nebo odvozené z počtu slotů `sell < 0` (≤ 4 sloty → nižší faktor).
+
+### Krok 3 — Deficit před oknem
+
+```text
+pre_window_wh := max(0, charge_target_at_neg_entry − in_window_wh * reliability_factor)
+```
+
+Kde `charge_target_at_neg_entry` = SoC potřeba na `first_neg_sell` (z rampy / `soc_need`), minus `current_soc` (pozorované), přepočteno na Wh.
+
+### Krok 4 — Fronta slotů (řazení + kumulace)
+
+Kandidáti = sloty s `slot_charge_wh > 0` **nebo** (pro grid vrstvu) sloty bez PV, kde smí síť.
+
+**Řazení (priorita):**
+
+| Režim | Primární klíč | Sekundární |
+|-------|----------------|------------|
+| Spot (`purchase_pricing_mode ≠ fixed`) | `buy_price ASC` | den plánu, před exportním oknem, `slot_ord` |
+| Fixní tarif | `sell_price ASC` | stejné geografické priority jako dnes v R__063 |
+
+**Kumulace:**
+
+```text
+cum := 0
+for slot in candidates ordered:
+  if cum >= budget_wh: break
+  allow_charge[slot] := true
+  if grid_layer: allow_grid_charge[slot] := true
+  cum += slot_charge_wh[slot]   -- u grid vrstvy min(cum increment, per_slot_charge_wh)
+```
+
+**Budgety (vrstvy, po sobě):**
+
+1. **Pre-neg / před oknem** — `budget = pre_window_wh` (jen sloty `t < first_neg_sell` téhož dne).
+2. **Grid B** — `budget = grid_target_wh` (AM/PM 50/50 jako dnes); spot: nejlevnější `buy`; fixed: nejlevnější `sell` u slotů splňujících marži.
+3. **PV A — zbytek** — `budget = max(0, charge_target_wh − grid_filled_wh − pre_neg_filled_wh)`.
+
+Po výběru: sloty **mimo** vybranou frontu nemusí mít `allow_charge` — LP pak může exportovat FVE, pokud objective dává smysl (bez v58 zákazu).
+
+### Krok 5 — Export před oknem (home-01)
+
+**Nahradit** v33 binární cushion:
+
+```text
+export_allowed_pre_neg[t] :=
+  t in pre_neg_calendar_window
+  AND pv_surplus_w[t] > threshold
+  AND NOT allow_charge[t]   -- přebytek po naplnění pre_window_wh
+  AND (optional) sell[t] >= sell_export_floor[t]  -- ne dump pod ranním pásmem (R__063 morning zone)
+```
+
+V Pythonu: `pre_neg_pv_export_ts` = sloty s exportem **jen pokud** nejsou v charge frontě; případně měkká penalizace místo `bc_pv = 0` na celé pásmo.
+
+---
+
+## 5. Fixní tarif (BA81, KV1)
+
+### 5.1 Změny oproti dnešku
+
+| Dnes (v58–v59) | Plán |
+|----------------|------|
+| `bc_pv = 0` if `sell > min + 0,20` | **Zrušit** v `planning_engine.py` |
+| PV vrstva A: `store_score DESC` | Fixed: **`sell_price ASC`** + kumulace `pv_surplus` Wh |
+| Grid: min sell sloty (v59) | Zachovat, sladit s jednotnou frontou (grid = vrstva B) |
+| Večer push: `bc_* = 0` | Zachovat (exportní okno) |
+
+### 5.2 Ekonomická interpretace
+
+- **Buy** je konstantní → rozhoduje **výkup v slotu** (opportunity cost uložení do baterie).
+- Nabíjet v pořadí **nejnižší sell**, dokud `cum < charge_target_wh`.
+- Export v slotu s vyšším sell je OK **až poté**, co je rozpočet Wh vyčerpán v levnějších slotech (včetně pozdějších levných sellů v pořadí času — viz pořadí: nejdřív globálně nejlevnější sell v rámci dne / AM-PM, viz níže).
+
+### 5.3 AM/PM a pořadí v čase
+
+Zachovat stávající **AM/PM rozpočet** `grid_target_wh` (50/50, přeliv AM→PM). Uvnitř segmentu:
+
+- fixed grid: `sell ASC` + filtr `sell ≤ min(sell≥0) + degrad + ε` (jako v59) **nebo** čistě kumulace Wh bez ε, pokud Wh budget stačí — **rozhodnutí při implementaci:** preferovat **Wh kumulaci**; ε jen jako failsafe proti grid nabíjení za 6 Kč v noci (KV1).
+
+### 5.4 Večerní špička a profitable export
+
+Beze změny principu: `allow_discharge_export` + `evening_push_ts`; v push slotech **`allow_charge = false`**.
+
+---
+
+## 6. Spot — home-01 a negativní výkup
+
+### 6.1 Běžný spot (bez neg dne v horizontu)
+
+Stejná kostra jako §4:
+
+- Grid vrstva: **`buy ASC`** (stávající spot loop + self-konzistentní filtr `pv_charge_wh_ahead`).
+- PV vrstva: **`store_score DESC`** nebo hybrid — **po** grid; budget = zbytek `charge_target_wh`.
+
+### 6.2 Den s `sell < 0` (neg strategie)
+
+Integrace s [`planning-neg-sell-strategy.md`](planning-neg-sell-strategy.md):
+
+| Komponenta | Role v charge-slot budget |
+|------------|---------------------------|
+| `soc_need[t]` rampa (v35/v36) | `charge_target_at_neg_entry` |
+| `in_window_wh` z A+B v neg sloty | sníží `pre_window_wh` |
+| `pre_window_wh > 0` | **nabíjecí fronta před `first_neg_sell`** (PV + případně grid) |
+| Tail / T / curtail | **beze změny** v LP (fáze neg okna) |
+| v44 `neg_day_no_grid_before_neg_sell` | **Změkčit:** povolit grid v N nejlevnějších `buy` slotech před oknem, pokud `pre_window_wh > in_window_wh × factor` a `buy < 0` nebo `buy ≤ ref_buy_am + degrad` |
+
+### 6.3 Nahrazení v33 cushion
+
+| v33 (dnes) | charge-slot budget |
+|------------|-------------------|
+| `cushion_ok` → export vše pre-neg | `pre_window_wh` malé → více `allow_charge` pre-neg |
+| `cushion_fail` → nabíjet | `pre_window_wh` velké → fronta nabíjení |
+| `bc_pv = 0` v celém `pre_neg_pv_export_ts` | Jen sloty, kde **není** `allow_charge` a export je ekonomicky výhodný |
+
+**Zima / krátké okno:** málo slotů `sell < 0` → malé `in_window_wh` → velké `pre_window_wh` → **více nabíjení před oknem**, i při sell 2–3 Kč, pokud jsou to nejlevnější dostupné sloty (ne plošný export).
+
+### 6.4 Velká baterie (64 kWh)
+
+- `charge_target_wh` může být **desítky kWh** — fronta musí počítat **skutečné** `slot_charge_wh`, ne jen cap 6 slotů / segment, pokud budget vyžaduje více (rozšířit `grid_charge_cap_*` odvozeně od `ceil(budget / per_slot_charge_wh)` — částečně už je).
+- `charge_acquisition` = vážený buy ve vybraných `allow_grid_charge` slotech (stávající two-pass v Pythonu).
+
+---
+
+## 7. Role LP po změně masek
+
+` solve_dispatch` **nesmí** přepisovat energetický výběr prahy typu v58.
+
+| Oblast | LP chování |
+|--------|------------|
+| Nabíjení | `bc_pv`, `bc_gi` jen kde `allow_charge` / `allow_grid_charge` |
+| Export FVE | objective `−ge_pv×sell`; **bez** `bc_pv=0` jen kvůli sell |
+| Export bat | `allow_discharge_export`, `charge_acquisition`, večerní push |
+| Guard | `ge_pv=0` if `sell < charge_acquisition − degrad` (spot) — **měkká** hranice hodnoty uložené energie |
+| Spot grid | v61: `bc_gi=0` if `buy > charge_acquisition + degrad` |
+| Neg fáze | rampa, tail, T — beze změny |
+
+---
+
+## 8. Návrh rozšíření `fn_load_planning_slots_full`
+
+Nové / rozšířené sloupce ve výstupu (nebo JSON v meta — preferováno sloupce pro debug):
+
+| Sloupec | Typ | Popis |
+|---------|-----|--------|
+| `charge_budget_wh` | numeric | celkový cíl pro tento běh |
+| `charge_slot_wh` | numeric | odhad Wh v daném slotu |
+| `charge_cum_wh` | numeric | kumulativa po řazení (audit) |
+| `charge_layer` | text | `pre_neg` / `grid_am` / `grid_pm` / `pv_a` / … |
+| `pre_window_wh` | numeric | jen informativní per běh (nebo per den v `solver_params`) |
+
+V `planning_run.solver_params` (commit meta):
+
+```json
+{
+  "charge_slot_budget": {
+    "charge_target_wh": 42000,
+    "pre_window_wh_by_day": {"2026-06-02": 18000},
+    "in_window_wh_by_day": {"2026-06-02": 12000},
+    "reliability_factor": 0.85,
+    "planner_build_tag": "…-charge-slot-budget-v1"
+  }
+}
+```
+
+---
+
+## 9. Co zrušit / neimplementovat znovu
+
+| Položka | Akce |
+|---------|------|
+| v58 `fixed_high_sell_no_pv_charge` | **odstranit** po nasazení budget |
+| v58 `FIXED_PV_CHARGE_ONLY_NEAR_MIN_SELL_CZK_KWH` | **odstranit** (konstanta) |
+| v59 `fixed_grid_charge_unprofitable` část `sell > min + 0,20` | nahradit: grid jen ve vybrané frontě; případně ponechat `sell < buy` guard pro grid |
+| v60 `sell < buy` → `bc_gi=0` (spot) | **neobnovovat** (záměrně zrušeno v61) |
+| v33 binární cushion jako hlavní páka | nahradit §4 krok 2–3; cushion ponechat jako **audit** / `solver_params.inputs.pre_neg_cushion_legacy_ok` |
+
+---
+
+## 10. Fáze implementace (doporučené pořadí)
+
+1. **Dokumentace + testy scénářů** (tento soubor, pytest fixtures s umělými sloty).
+2. **`R__063`:** fixed PV vrstva `sell ASC` + Wh kumulace; sloupce debug; bez změny Pythonu → ověřit, že v58 stále blokuje (regrese).
+3. **Python:** odstranit v58/v59 `bc_pv`/`bc_gi` fixed větve; spoléhat na masky.
+4. **`R__063` + Python:** pre-neg `pre_window_wh` pro spot; zúžit `pre_neg_pv_export_ts`.
+5. **v44 změkčení:** grid před neg jen když `pre_window_wh` > práh.
+6. **Dokumentace + changelog** tag `charge-slot-budget-v1`; MCP ověření home-01 / KV1 / BA81.
+
+---
+
+## 11. Ověření
+
+### 11.1 Automatické testy (pytest)
+
+| Scénář | Očekávání |
+|--------|-----------|
+| Fixed, slunečný den, nízký ranní SoC | `allow_charge` v mnoha PV slotech; max SoC v plánu → blízko `soc_max` |
+| Fixed, min sell odpoledne | dřívější sloty s vyšším sell **bez** `allow_charge`, pokud budget vyčerpán v levnějších |
+| Spot, krátké neg okno (2–4 sloty), slabá FVE | `pre_window_wh > 0`; nabíjení před `first_neg_sell`; **ne** plošný pre-neg export |
+| Spot, dlouhé neg okno, silná FVE | po naplnění `pre_window_wh` může export pre-neg v drahých sell |
+| home-01 velká baterie | kumulace ≥ desítky kWh přes více slotů |
+
+### 11.2 SQL / MCP
+
+```sql
+select interval_start, allow_charge, allow_grid_charge,
+       charge_layer, charge_slot_wh, charge_cum_wh,
+       sell_price, pv_surplus_w
+from ems.fn_load_planning_slots_full(<site_id>, <from>, <to>, <soc_wh>)
+where allow_charge
+order by interval_start;
+```
+
+Po deployi: aktivní `planning_run.solver_params->'charge_slot_budget'`; u home-01 `pre_neg_pv_export_slots` ⊆ sloty bez `allow_charge`.
+
+### 11.3 Regrese
+
+- Večerní push (v57), spot v61, KV1 noc v62 — **nesmí** rozpadnout.
+- Neg rampa v35/v36 — SoC v okně `sell < 0` stejné cíle, mění se jen **příprava před oknem**.
+
+---
+
+## 12. Otevřené body (rozhodnutí před kódem)
+
+1. **`reliability_factor`:** fixní 0,85 vs funkce počtu neg slotů?
+2. **Fixed řazení:** globální `sell ASC` přes den vs AM/PM segmenty (doporučení: AM/PM budget + `sell ASC` v segmentu).
+3. **Večer před neg dnem:** zda `charge_target_wh` zahrnuje večerní výboj D−1 (`neg_evening_before_neg`) — ano, přes `soc_need`, ne duplicitní budget.
+4. **Multi-day horizont:** každý pražský den vlastní `pre_window_wh` (jako v36 bundle) — **ano**.
+5. **UI:** badge „charge budget“ ve frontendu — volitelné, až budou sloupce v API.
+
+---
+
+## 13. Shrnutí pro produkt
+
+Jednou větou: **místo prahu „sell nad minimum + 20 haléřů“ spočítáme, kolik Wh chybí do cíle, kolik jich dodá záporné výkupní okno z forecastu, a zbytek nabijeme v nejlevnějších slotech (buy nebo sell podle tarifu) s ohledem na PV přebytek a spotřebu — u home-01 tím nahradíme plošný ranní export před `sell < 0`, u KV1/BA81 doplníme baterii ve slunečný den nad ~60 %.**