Initial commit
Made-with: Cursor
This commit is contained in:
Dusan Vojacek
147
CLAUDE.md
Normal file
147
CLAUDE.md
Normal file
@@ -0,0 +1,147 @@
|
||||
# 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
Block a user