Branch 5: dynamický terminal SoC factor při future neg buy

backend/services/planning_engine.py

@@ -91,8 +91,11 @@ NEG_EVENING_PREP_DISCHARGE_SHORTFALL_PENALTY_CZK_KWH = 120.0
 # Kotva: SoC na konci večera D−1 a těsně před 1. sell<0 ráno D ≤ reserve_soc.
 NEG_EVENING_RESERVE_SOC_MAX_SLACK_WH = 400.0
 NEG_EVENING_RESERVE_SOC_SLACK_PENALTY_CZK_PER_WH = 55.0
-# Terminal SoC shadow price: při blízkém buy<0 nesmí LP „šetřit“ baterii ve večerní špičce.
-FUTURE_NEG_BUY_TERMINAL_SOC_FACTOR_MULT = 0.1
+# Terminal SoC shadow price: effective_factor = base × (1 − w_neg); w_neg roste s blízkostí a záporností buy<0.
+TERMINAL_NEG_BUY_WEIGHT_HORIZON_SLOTS = int(36 / INTERVAL_H)
+TERMINAL_NEG_BUY_MAGNITUDE_REF_CZK = 1.0
+TERMINAL_NEG_BUY_MAGNITUDE_FLOOR = 0.25
+TERMINAL_NEG_BUY_WEIGHT_CAP = 0.95
 # Před prvním sell<0: export FVE jen pokud predikce v sell<0 okně pokryje dobítí na prep cíl.
 PRE_NEG_PV_EXPORT_FORECAST_MARGIN = 1.15
 PRE_NEG_PV_EXPORT_MIN_NEEDED_WH = 2500.0
@@ -1388,6 +1391,38 @@ def _first_neg_sell_idx_on_prague_day(
     return None
 
 
+def _terminal_neg_buy_weight(
+    slots: list[PlanningSlot],
+    *,
+    first_neg_buy_idx: int | None,
+) -> float:
+    """
+    w_neg ∈ [0, TERMINAL_NEG_BUY_WEIGHT_CAP]: snížení terminal SoC shadow price při buy<0 v horizontu.
+    Blížší a zápornější okno → vyšší váha; effective_factor = planner_terminal_soc_value_factor × (1 − w_neg).
+    """
+    if first_neg_buy_idx is None or first_neg_buy_idx <= 0:
+        return 0.0
+    slots_ahead = first_neg_buy_idx
+    prox = max(
+        0.0,
+        1.0 - slots_ahead / TERMINAL_NEG_BUY_WEIGHT_HORIZON_SLOTS,
+    )
+    if prox <= 0.0:
+        return 0.0
+    window_end = min(len(slots), first_neg_buy_idx + int(24 / INTERVAL_H))
+    neg_buys = [
+        float(slots[t].buy_price)
+        for t in range(first_neg_buy_idx, window_end)
+        if float(slots[t].buy_price) < 0.0
+    ]
+    if not neg_buys:
+        return 0.0
+    min_neg_buy = min(neg_buys)
+    mag_raw = min(1.0, abs(min_neg_buy) / TERMINAL_NEG_BUY_MAGNITUDE_REF_CZK)
+    mag = TERMINAL_NEG_BUY_MAGNITUDE_FLOOR + (1.0 - TERMINAL_NEG_BUY_MAGNITUDE_FLOOR) * mag_raw
+    return min(TERMINAL_NEG_BUY_WEIGHT_CAP, prox * mag)
+
+
 def _future_neg_buy_discharge_enabled(
     slots: list[PlanningSlot],
     battery: Any,
@@ -2802,9 +2837,11 @@ def solve_dispatch(
                 neg_sell_soc_target_by_t if neg_sell_phases_en else None
             ),
         )
-    terminal_factor = terminal_factor_base
-    if future_neg_buy_discharge_en:
-        terminal_factor *= FUTURE_NEG_BUY_TERMINAL_SOC_FACTOR_MULT
+    terminal_neg_buy_weight = _terminal_neg_buy_weight(
+        slots,
+        first_neg_buy_idx=first_neg_buy_idx,
+    )
+    terminal_factor = terminal_factor_base * (1.0 - terminal_neg_buy_weight)
     # Kč/Wh: ocenění energie ponechané v baterii na konci horizontu (receding horizon kotva).
     terminal_soc_kcz_per_wh = avg_buy_terminal * terminal_factor / 1000.0
 
@@ -4903,6 +4940,7 @@ def solve_dispatch(
             ),
             "evening_push_hard_suppressed": bool(evening_push_hard_suppressed),
             "future_neg_buy_discharge": bool(future_neg_buy_discharge_en),
+            "terminal_neg_buy_weight": float(terminal_neg_buy_weight),
             "terminal_soc_factor_effective": float(terminal_factor),
             "pos_sell_pre_neg_buy_ge_exempt_slots": [
                 slots[i].interval_start.isoformat()

backend/tests/test_planning_dispatch_milp.py

@@ -42,6 +42,7 @@ from services.planning_engine import (
     _slots_until_buy_le_threshold,
     _slots_until_sell_lt,
     _soc_panel_min_wh_series,
+    _terminal_neg_buy_weight,
     solve_dispatch,
     solve_dispatch_two_pass,
 )
@@ -2717,6 +2718,113 @@ class TerminalSocShadowTests(unittest.TestCase):
             msg="terminal SoC shadow price should keep end-of-horizon SoC above bare minimum",
         )
 
+    def test_terminal_neg_buy_weight_zero_without_future_neg_buy(self) -> None:
+        base = datetime(2026, 4, 3, 12, 0, tzinfo=timezone.utc)
+        slots = [
+            PlanningSlot(
+                interval_start=base + timedelta(minutes=15 * i),
+                buy_price=2.0,
+                sell_price=3.0,
+                pv_a_forecast_w=0,
+                pv_b_forecast_w=0,
+                load_baseline_w=600,
+                ev1_connected=False,
+                ev2_connected=False,
+            )
+            for i in range(8)
+        ]
+        self.assertEqual(_terminal_neg_buy_weight(slots, first_neg_buy_idx=None), 0.0)
+        self.assertEqual(_terminal_neg_buy_weight(slots, first_neg_buy_idx=0), 0.0)
+
+    def test_terminal_neg_buy_weight_scales_with_proximity_and_magnitude(self) -> None:
+        base = datetime(2026, 6, 6, 19, 0, tzinfo=timezone.utc)
+        slots_far: list[PlanningSlot] = []
+        for i in range(96):
+            buy = -0.9 if i >= 64 else 3.0
+            slots_far.append(
+                PlanningSlot(
+                    interval_start=base + timedelta(minutes=15 * i),
+                    buy_price=buy,
+                    sell_price=5.0 if buy > 0 else -0.2,
+                    pv_a_forecast_w=0,
+                    pv_b_forecast_w=0,
+                    load_baseline_w=500,
+                    ev1_connected=False,
+                    ev2_connected=False,
+                )
+            )
+        slots_near: list[PlanningSlot] = []
+        for i in range(32):
+            buy = -1.0 if i >= 8 else 3.0
+            slots_near.append(
+                PlanningSlot(
+                    interval_start=base + timedelta(minutes=15 * i),
+                    buy_price=buy,
+                    sell_price=5.0 if buy > 0 else -0.2,
+                    pv_a_forecast_w=0,
+                    pv_b_forecast_w=0,
+                    load_baseline_w=500,
+                    ev1_connected=False,
+                    ev2_connected=False,
+                )
+            )
+        w_far = _terminal_neg_buy_weight(slots_far, first_neg_buy_idx=64)
+        w_near = _terminal_neg_buy_weight(slots_near, first_neg_buy_idx=8)
+        self.assertGreater(w_far, 0.2)
+        self.assertLess(w_far, 0.75)
+        self.assertGreater(w_near, w_far)
+        self.assertGreater(w_near, 0.8)
+
+    def test_terminal_soc_factor_reduced_when_future_neg_buy(self) -> None:
+        prague = ZoneInfo("Europe/Prague")
+        base = datetime(2026, 6, 6, 19, 0, tzinfo=prague).astimezone(timezone.utc)
+        slots: list[PlanningSlot] = []
+        for i in range(96):
+            local = (base + timedelta(minutes=15 * i)).astimezone(prague)
+            d, h = local.day, local.hour
+            if d == 6:
+                buy, sell = 3.0, 5.3
+            else:
+                buy = -0.89 if 11 <= h < 14 else 2.0
+                sell = -0.2 if 5 <= h < 15 else 2.5
+            slots.append(
+                PlanningSlot(
+                    interval_start=base + timedelta(minutes=15 * i),
+                    buy_price=buy,
+                    sell_price=sell,
+                    pv_a_forecast_w=0,
+                    pv_b_forecast_w=0,
+                    load_baseline_w=500,
+                    ev1_connected=False,
+                    ev2_connected=False,
+                    allow_charge=True,
+                    allow_discharge_export=True,
+                )
+            )
+        battery = _battery(uc_wh=64_000.0, terminal_soc_value_factor=0.9)
+        hp = SimpleNamespace(rated_heating_power_w=0, tuv_min_temp_c=45.0, tuv_target_temp_c=55.0)
+        grid = SimpleNamespace(max_import_power_w=17_000, max_export_power_w=13_500)
+        vehicles = [
+            SimpleNamespace(max_charge_power_w=0, battery_capacity_kwh=1.0, default_target_soc_pct=80.0),
+            SimpleNamespace(max_charge_power_w=0, battery_capacity_kwh=1.0, default_target_soc_pct=80.0),
+        ]
+        _results, _ms, snap = solve_dispatch(
+            slots,
+            battery,
+            hp,
+            grid,
+            [None, None],
+            vehicles,
+            0.5 * battery.soc_max_wh,
+            50.0,
+            operating_mode="AUTO",
+        )
+        w_neg = float(snap["inputs"]["terminal_neg_buy_weight"])
+        eff = float(snap["inputs"]["terminal_soc_factor_effective"])
+        self.assertGreater(w_neg, 0.3)
+        self.assertLess(eff, 0.6)
+        self.assertAlmostEqual(eff, 0.9 * (1.0 - w_neg), places=6)
+
 
 class SpreadGuardHome01EconomicsTests(unittest.TestCase):
     """Regrese: sell≪buy (VT) nesmí vést k PV exportu + masivnímu grid importu ve stejném slotu."""

docs/04-modules/planning.md

@@ -8,7 +8,7 @@
 
 - **SQL-first:** horizont a sloty z DB funkcí (`fn_planning_horizon_end`, `fn_load_planning_slots_full`, …); viz **`CLAUDE.md`** → sekce *SQL-first a read-model*.
 - **Dynamický horizont (jen OTE):** konec plánu z **`ems.fn_planning_horizon_end(site_id, horizon_start)`** (výchozí strop **36 h**, minimum pro rolling **1 h** – obojí jako defaultní argumenty v SQL, úprava přes repeatable migraci). Pomocná `ems.fn_last_effective_ote` vrací konec posledního OTE intervalu. Rolling replan při `NULL` přeskočí; denní plán použije krátký (1 h) fallback v Pythonu. Sloty v solveru jsou bez predikovaných cen v rámci tohoto horizontu.
-- **Terminal SoC shadow price:** v objective je člen `−(avg_buy_prvních_24h × planner_terminal_soc_value_factor / 1000) × soc[T−1]` (Kč), kde faktor je **`ems.asset_battery.planner_terminal_soc_value_factor`** přes **`ems.fn_planning_site_context`** (default v DB **0.9**); viz sekci *Tuning pro malé baterie* níže. Účel: konec horizontu nemusí končit zbytečně vyprázdněnou baterií (receding horizon).
+- **Terminal SoC shadow price:** v objective je člen `−(avg_buy_prvních_24h × effective_factor / 1000) × soc[T−1]` (Kč), kde `effective_factor = planner_terminal_soc_value_factor × (1 − terminal_neg_buy_weight)` a základní faktor je **`ems.asset_battery.planner_terminal_soc_value_factor`** přes **`ems.fn_planning_site_context`** (default v DB **0.9**); viz sekci *Tuning pro malé baterie* níže. Při **`buy<0`** v horizontu (36 h) roste **`terminal_neg_buy_weight`** s blízkostí a záporností ceny — LP nemá „šetřit“ baterii před levným importem. Účel: konec horizontu nemusí končit zbytečně vyprázdněnou baterií (receding horizon).
 - **SoC kontinuita a export z baterie:** `soc[t]` klesá při **`bd[t]`** — výkon vybíjení na AC sběrnici z energetické bilance `pv + gi + bd = load + bc + ge`. Při exportu z baterie je v `bd` už započten i tok do sítě (`ge_bat` je součást `ge`); **`ge_bat` se v SoC znovu neodečítá** (dříve double-count → plán klesal ~2× rychleji než BMS ve večerním exportu). Tag `2026-05-28-evening-export-soc-balance-v39`.
 - **Masky `allow_charge` / `allow_discharge_export` (tenký anti-mikrocyklus):** generuje `ems.fn_load_planning_slots_full` (`R__063`). Ekonomiku primárně řídí LP podle efektivních cen; masky jen omezují počet slotů pro grid nabíjení / export baterie.
   - **PV-surplus (vrstva A):** ranking dle **`store_score DESC`** = `future_sell_opportunity − sell − max(0, buy−sell)`; jen sloty s `sell ≥ buy − degradation`. Kumulativní PV pokrývá `grid_target` (deficit SoC, nad `reserve_soc` bez násobení `charge_slot_buffer`). Zbytek → `allow_charge=false` (PV jen do sítě / `bc ≤ pv_surplus` v LP).
@@ -149,7 +149,11 @@ flowchart TD
 17. **v64 — future neg-buy večerní export (Branch 2, home-01):**
    - **`future_neg_buy_discharge`**: před **`buy<0`** dnem s dostatečnou FVE v **`sell<0`** zůstává neg-evening push + kotvy **`reserve_soc`** i při **`relaxed_neg_prep_window`**.
    - **`pos_sell_pre_neg_buy_ge_exempt_slots`**: večerní peak před **`buy<0`** — výjimka z `ge=0` při ekonomicky výhodném vývozu.
-   - **`terminal_soc_factor_effective`**: × **0,1** při **`future_neg_buy_discharge`**. Snap: `future_neg_buy_discharge`, `evening_push_hard_suppressed` (jen fallback). Tag **`2026-06-06-future-neg-buy-evening-export-v64`**.
+   - **`terminal_soc_factor_effective`**: v64 binární × **0,1** při **`future_neg_buy_discharge`** (nahrazeno v65). Tag **`2026-06-06-future-neg-buy-evening-export-v64`**.
+
+18. **v65 — dynamický terminal SoC při future neg buy (Branch 5):**
+   - **`terminal_neg_buy_weight`** (`w_neg`): `effective_factor = planner_terminal_soc_value_factor × (1 − w_neg)`; blížší a zápornější **`buy<0`** v horizontu (36 h) → vyšší `w_neg` (cap 0,95).
+   - Snap: `terminal_neg_buy_weight`, `terminal_soc_factor_effective`. Tag **`2026-06-06-terminal-soc-future-neg-buy-v65`**.
 
 **Funkce:** … home-01 **v61**; BA81/KV1 fixed **v59** (+ `R__063`).
 
@@ -637,8 +641,11 @@ Kromě **`planner_terminal_soc_value_factor`** existují od **V077** měkké mec
 V účelové funkci LP je člen **„terminal SoC shadow price“**: energie ponechaná v baterii na konci horizontu je oceněná jako záporný příspěvek k nákladům (solver má motivaci držet část SoC, pokud se to ekonomicky vyplatí oproti okamžitému vývozu / nákupu).
 
 **Výpočet (zjednodušeně):**  
-`terminal_soc_kcz_per_wh = (průměr buy v prvních 24 h slotů) × planner_terminal_soc_value_factor / 1000`  
-a v objective se přičítá `- terminal_soc_kcz_per_wh × soc[T−1]` (viz `solve_dispatch` v `backend/services/planning_engine.py`).
+`effective_factor = planner_terminal_soc_value_factor × (1 − terminal_neg_buy_weight)`  
+`terminal_soc_kcz_per_wh = (průměr buy v prvních 24 h slotů) × effective_factor / 1000`  
+a v objective se přičítá `- terminal_soc_kcz_per_wh × soc[T−1]` (viz `_terminal_neg_buy_weight` a `solve_dispatch` v `backend/services/planning_engine.py`).
+
+**`terminal_neg_buy_weight`:** pokud v horizontu existuje **`buy<0`**, váha roste s blízkostí prvního záporného slotu (horizont 36 h) a magnitudou ceny (ref 1 Kč/kWh, cap **0,95**). Bez záporného buy zůstává **0** — chování jako čistý DB faktor.
 
 **Kde se bere faktor (jediný kanonický zdroj):**
 

docs/planning-changelog.md

@@ -24,6 +24,22 @@ Formát: **datum (ISO)** · stručný důvod · soubory · chování / ověřen
 
 ---
 
+## 2026-06-06 — Dynamický terminal SoC factor při future neg buy (v65, Branch 5)
+
+**Problém:** Binární × **0,1** při **`future_neg_buy_discharge`** (v64) neškáloval s vzdáleností a záporností **`buy<0`**; **`planner_terminal_soc_value_factor = 0.9`** na home-01 držel baterii i když v horizontu bylo levnější nabíjení.
+
+**Změna (v65):**
+- **`terminal_neg_buy_weight`** (`w_neg`): `effective_factor = planner_terminal_soc_value_factor × (1 − w_neg)`; `w_neg` roste s blízkostí prvního **`buy<0`** (horizont 36 h) a magnitudou záporné ceny (ref 1 Kč/kWh).
+- Odstraněn pevný **`FUTURE_NEG_BUY_TERMINAL_SOC_FACTOR_MULT`**; váha platí vždy, když je v horizontu **`buy<0`**, ne jen při **`future_neg_buy_discharge`**.
+
+**Soubory:** `backend/services/planning_engine.py`, `backend/tests/test_planning_dispatch_milp.py`.
+
+**Ověření:**
+- `pytest backend/tests/test_planning_dispatch_milp.py -k "terminal_soc or terminal_neg_buy"`
+- MCP: `solver_params->'inputs'->>'terminal_neg_buy_weight'` > 0 před dnem s **`buy<0`**; `terminal_soc_factor_effective` < `planner_terminal_soc_value_factor`.
+
+---
+
 ## 2026-06-06 — Future neg-buy večerní export (v64, Branch 2)
 
 **Problém:** home-01 run 23784 při **`relaxed_neg_prep_window`**: `evening_push_hard_suppressed`, prázdné **`neg_evening_push_slots`**, **`pos_sell_pre_neg_buy_ts`** blokoval `ge_bat` ve večerní špičce, terminal SoC shadow price držel ~80 % SoC + import @ ~5 Kč.
@@ -32,7 +48,7 @@ Formát: **datum (ISO)** · stručný důvod · soubory · chování / ověřen
 - **`future_neg_buy_discharge`**: před dnem s **`buy<0`**, pokud FVE v **`sell<0`** pokryje deficit do prep rampy, zůstává neg-evening bundle (push + kotvy **`reserve_soc`**) i při **`relaxed_neg_prep_window`** (strict pre-neg PV export bundle se vypne).
 - **`evening_push_hard_suppressed`** jen při **`neg_sell_phases_fallback`**, ne při **`relaxed_neg_prep_window`**.
 - **`pos_sell_pre_neg_buy_ge_exempt_slots`**: večerní peak před **`buy<0`** nesmí dostat `ge=0`, pokud je vývoz ekonomicky výhodný.
-- **`terminal_soc_factor_effective`**: při **`future_neg_buy_discharge`** násobit **`planner_terminal_soc_value_factor`** × **0,1**.
+- **`terminal_soc_factor_effective`**: v64 binární × **0,1** při **`future_neg_buy_discharge`** — nahrazeno v65 dynamickým **`terminal_neg_buy_weight`** (viz výše).
 
 **Soubory:** `backend/services/planning_engine.py`, `backend/tests/test_planning_dispatch_milp.py`.