vojacekd/ems
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
897b95f72891573196488797da51de846ad7b92b
ems/CLAUDE.md
Dusan Vojacek 8b4af663d8 Initial commit 
Made-with: Cursor
2026-03-20 13:27:44 +01:00

8.8 KiB
Raw Blame History

CLAUDE.md – EMS Platform (Cursor Agent)

Čti před každou implementační změnou. Stručná orientace; detail v docs/ a SQL v db/.

1. Co to je

Multi-site Energy Management System: optimalizuje FVE, baterii a flexibilní zátěž (EV, TČ) podle spotových cen OTE CZ a předpovědí; výstupy řídí zařízení (Modbus) a informuje Loxone jako exekutora. Referenční lokalita v seedu: home-01 (Deye, baterie, 2× EV Teltonika, Samsung TČ).

2. Technologický stack

Vrstva Technologie
DB PostgreSQL 16 + TimescaleDB
Migrace Flyway (db/migration, db/routines, db/views)
API PostgREST (REST ze schématu ems) + FastAPI (logika, joby – plán v docs)
Frontend React + TypeScript + Vite (očekáváno u kořene / Docker)
Pole / zařízení Modbus TCP (pymodbus), HTTP (Loxone, případně API vozidel)
Solver PuLP + HiGHS (HiGHS_CMD)
Runtime Docker Compose

3. Adresářová struktura

Cesta Účel
CLAUDE.md, .env.example, docker-compose.yml Kořen: pravidla, env šablona, compose
docs/ Produktová a technická specifikace (overview, architektura, datový model, integrace)
docs/04-modules/ Modulové specifikace (ceny, forecast, spotřeba, TČ, telemetrie, řízení, plánování, režimy, EV)
docs/loxone-integration.md Loxone watchdog, heartbeat, role exekutora
docs/06-open-questions.md Nedokončené rozhodnutí – doplňovat místo hádání
db/migration/ Flyway versioned migrace V00x__*.sql (schéma, seed, alter)
db/routines/ Repeatable SQL: funkce ems.fn_*
db/views/ Repeatable SQL: view ems.vw_*
backend/services/ Python služby (v repozitáři zatím hlavně plánování)

4. Pravidla – NIKDY neporušovat

  1. 15min logika pro plán/ceny/baseline/audit/forecast intervaly. Časové řady v těchto doménách = 15min sloty. Telemetrie zařízení je 1min (hypertables) – agregace do 15min přes SQL/job, ne ukládat „hodinové“ řádky jako primární plánovací záznam.

  2. Všechny doménové záznamy vázat na site_id (telemetrie, plány, audit, konfigurace aktiv, session, …). Výjimka: market_interval_price je globální pro zdroj/trh; vazba na site je přes konfiguraci a view.

  3. Raw ceny ≠ efektivní ceny. ems.market_interval_price = bez marží. Efektivní nákup/prodej jen přes ems.vw_site_effective_price (join na platnou site_market_config).

  4. Loxone = exekutor + autonomní fallback, ne optimalizátor. Logika a plán v EMS. Watchdog v Loxone nesmí záviset na čtení DB (site_heartbeat je jen pro EMS UI/diagnostiku).

  5. FVE pole B (controllable = false, typicky ongrid GEN) – žádný curtailment. Curtailment jen pole A (Deye). Solver smí omezovat jen pv_a; pole B má zelený bonus (site_market_config.green_bonus_*, audit pv_b_production_wh / green_bonus_czk).

  6. Záporná prodejní cena → grid_export == 0 v LP (hard constraint).

  7. Záporná nákupní cena → omezit import na realistický horní strop (viz solve_dispatch v planning_engine.py – nesmí „nekonečný“ import).

  8. PuLP + HiGHS pro dispatch; žádný návrat k greedy fn_plan_day jako primárnímu řešení (SQL wrapper může zůstat pro uložení výsledků – dle docs).

  9. Deye Modbus: čtení i zápis (setpointy). RS485→Waveshare→TCP, knihovna pymodbus.

  10. Přepínání provozního režimu přes DB API / ems.fn_set_mode – držet konzistenci s operating_mode_def a Loxone loxone_mode_value.

5. Schéma ems – tabulky (jedna věta)

Tabulka Popis
site Lokalita (časová zóna, GPS, aktivita).
site_endpoint Endpointy: Modbus, Loxone HTTP, atd.
site_market_config Marže, režimy cenění, zelený bonus; časová platnost.
site_grid_connection Limity import/export, no_export, rezervovaný výkon.
site_override Manuální přepisy nad plánem (JSON + platnost).
site_operating_mode Aktuální provozní režim na site (1 řádek/site).
site_operating_mode_log Historie přepnutí režimů.
site_heartbeat Poslední EMS heartbeat pro dashboard (ne pro Loxone watchdog).
operating_mode_def Číselník režimů (baterie/síť/EV/TČ, hodnota pro Loxone).
asset_inverter Střídač (výkony, endpoint, zda řiditelný).
asset_battery Baterie vázaná na střídač (SoC limity, účinnosti, degradace).
asset_pv_array FVE pole (Wp, orientace, curtailable vs ne).
asset_ev_charger Nabíječka EV (výkony, fáze, endpoint).
asset_heat_pump TČ (výkon, COP ref, limity běhu, TUV parametry).
asset_vehicle Vozidlo (kapacita, max AC výkon, default target SoC/deadline).
market_interval_price Raw spot OTE (15min), bez marží.
telemetry_inverter 1min telemetrie střídače (Timescale).
telemetry_ev_charger 1min telemetrie nabíječky (Timescale).
telemetry_heat_pump 1min telemetrie TČ (Timescale).
forecast_pv_run Metadata běhu predikce FVE.
forecast_pv_interval Predikovaný výkon FVE po 15min (Timescale).
forecast_weather_interval Počasí 15min pro site (Timescale).
forecast_correction_log Log korekcí forecastu vs skutečnost při rolling replanu.
planning_run Jeden běh plánovače (daily/rolling/manual, stav, parametry solveru).
planning_interval Výstup solveru po 15min (baterie, síť, EV, TČ, curtailment A).
audit_interval Skutečnost vs plán po 15min (náklady, odchylky, bonus pole B).
consumption_baseline_interval Bazální spotřeba actual/forecast 15min (Timescale).
ev_session Nabíjecí session na WB (deadline, energie, náklady).

View / funkce (nejsou tabulky): vw_site_effective_price, vw_latest_telemetry, vw_audit_summary, vw_operating_mode; fn_effective_price, fn_cop_estimate, fn_fill_audit_interval, fn_set_mode.

6. Periodické úlohy backendu (APScheduler / smyčky)

Specifikace z docs/02-architecture.md, modulových docs a komentářů v planning_engine.py. V gitu je zatím rozpracovaný backend – joby mají být v backend/app/main.py (zatím často chybí).

Úloha Frekvence Poznámka
telemetry_collector každých 60 s Smyčka polling Modbus (Deye, EV×2, TČ) – viz docs/04-modules/telemetry.md
price_importer 14:00 denně + 00:05 kontrola docs/04-modules/market-prices.md (časy CET v dokumentaci)
forecast_service 14:30 + 06:00 denně docs/04-modules/forecast.md
run_daily_plan 15:00 denně backend/services/planning_engine.py (horizont 36 h)
run_rolling_replan každých 15 min (*/15) planning_engine.py – přepočet od aktuálního slotu
control_exporter každých 15 min (slot boundary) docs/04-modules/control.md
audit_filler / fn_fill_audit_interval každých 15 min docs/02-architecture.md, DB fn_fill_audit_interval

7. Kde hledat co

Chci… Kam
Pochopit systém end-to-end docs/01-overview.md, docs/02-architecture.md
Tabulky, vazby, jednotky docs/03-data-model.md
OTE ceny, marže, efektivní cena docs/04-modules/market-prices.md, db/views/R__vw_site_effective_price.sql
FVE forecast, počasí docs/04-modules/forecast.md
Bazální spotřeba docs/04-modules/consumption.md
TČ, COP, TUV docs/04-modules/heat-pump.md, db/routines/R__fn_cop_estimate.sql
Modbus, telemetrie, agregace docs/04-modules/telemetry.md
Export setpointů, Loxone HTTP docs/04-modules/control.md, docs/loxone-integration.md
LP solver, rolling replan, korekce FVE docs/04-modules/planning.md, backend/services/planning_engine.py
Provozní režimy AUTO / SELF_SUSTAIN / … docs/04-modules/operating-modes.md, db/migration/V004__operating_modes.sql, R__fn_set_mode.sql
EV, session, deadline charging docs/04-modules/ev-charging.md, db/migration/V006__vehicles.sql
Curtailment A, zelený bonus B db/migration/V005__planning_curtailment.sql
Rolling plán, forecast log db/migration/V007__rolling_replanning.sql
Audit 15min db/routines/R__fn_fill_audit_interval.sql, docs/04-modules/telemetry.md
Nové sloupce / tabulky nový db/migration/V00x__*.sql + případně db/routines / db/views
Nespecifikované chování docs/06-open-questions.md (přidat otázku, neimpl. naslepo)

Konvence (krátce)

  • Python: snake_case, type hints, Pydantic pro API modely.
  • SQL: snake_case, explicitní FK; Flyway pořadí V###__ / repeatable R__.
  • Výkon W, energie Wh, ceny Kč/kWh; čas v DB TIMESTAMPTZ (UTC).
Reference in New Issue View Git Blame Copy Permalink