Entwicklung

EEDC Development Guide

Version 2.4.1 | Stand: Februar 2026

Voraussetzungen

Python 3.11+
Node.js 20+ (empfohlen via nvm; eedc/frontend/.nvmrc enthält 20)
Docker/Podman (für Container-Tests)

Schnellstart

1. Repository klonen

git clone https://github.com/supernova1963/eedc-homeassistant.git
cd eedc-homeassistant

2. Backend einrichten

cd eedc/backend

# Virtual Environment erstellen (einmalig)
python -m venv venv
source venv/bin/activate  # Linux/Mac
# oder: venv\Scripts\activate  # Windows

# Dependencies installieren
pip install -r requirements.txt

3. Frontend einrichten

cd eedc/frontend

# Dependencies installieren (einmalig)
npm install

4. Entwicklungsserver starten

Terminal 1 (Backend):

cd eedc && source backend/venv/bin/activate
uvicorn backend.main:app --reload --port 8099

Terminal 2 (Frontend):

cd eedc/frontend && npm run dev

URLs:

Frontend: http://localhost:3000 (Vite Dev Server, Proxy zu Backend)
API Docs: http://localhost:8099/api/docs
ReDoc: http://localhost:8099/api/redoc

Hinweis für macOS: Vite verwendet Port 3000 (nicht 5173). Falls npm run dev mit dem System-Node fehlschlägt, stelle sicher dass Node 20 aktiv ist: nvm use 20 oder absoluten Pfad nutzen.

Docker/Podman Build

cd eedc

# Image bauen
docker build -t eedc .
# oder: podman build -t eedc .

# Container starten
docker run -p 8099:8099 -v $(pwd)/data:/data eedc
# oder: podman run -p 8099:8099 -v $(pwd)/data:/data eedc

# Browser öffnen
open http://localhost:8099

Home Assistant Add-on Test

Für Tests in einer echten Home Assistant Umgebung:

Repository zu HA Add-on Repositories hinzufügen:
- Einstellungen → Add-ons → Add-on Store → ⋮ → Repositories
- URL: https://github.com/supernova1963/eedc-homeassistant
Add-on installieren und starten
Über Sidebar “eedc” öffnen

Versionierung

Bei neuen Releases müssen diese Dateien aktualisiert werden:

Datei	Feld
`eedc/backend/core/config.py`	`APP_VERSION`
`eedc/frontend/src/config/version.ts`	`APP_VERSION`
`eedc/config.yaml`	`version`
`eedc/run.sh`	Echo-Statement
`CHANGELOG.md`	Neuer Eintrag

Code-Konventionen

Python (Backend)

Formatierung mit black
Linting mit ruff
Type Hints verwenden
Docstrings für öffentliche Funktionen

TypeScript (Frontend)

ESLint Konfiguration beachten
Strikte TypeScript Einstellungen
Functional Components mit Hooks

Git Commits

feat(component): Add new feature
fix(component): Fix specific issue
refactor(component): Refactor without behavior change
docs: Update documentation
chore: Build, dependencies, etc.

Kritische Code-Patterns

SQLAlchemy JSON-Felder

SQLAlchemy erkennt Änderungen an JSON-Feldern nicht automatisch:

from sqlalchemy.orm.attributes import flag_modified

# Nach Änderung an JSON-Feldern IMMER flag_modified aufrufen!
obj.verbrauch_daten["key"] = value
flag_modified(obj, "verbrauch_daten")
db.commit()

0-Werte korrekt prüfen

# FALSCH - 0 wird als False gewertet
if val:
    ...

# RICHTIG
if val is not None:
    ...

Datenquellen-Trennung

Monatsdaten = Nur Zählerwerte (Einspeisung, Netzbezug)
InvestitionMonatsdaten = Alle Komponenten-Details

Legacy-Felder nicht verwenden:

Monatsdaten.pv_erzeugung_kwh ❌
Monatsdaten.batterie_* ❌

Projektstruktur

eedc-homeassistant/
├── README.md                    # Projekt-Übersicht
├── CHANGELOG.md                 # Versionshistorie
├── CLAUDE.md                    # KI-Entwicklungskontext
│
├── docs/
│   ├── BENUTZERHANDBUCH.md      # Endbenutzer-Anleitung
│   ├── ARCHITEKTUR.md           # Technische Dokumentation
│   ├── DEVELOPMENT.md           # Diese Datei
│   └── archive/                 # Archivierte Dokumente
│
└── eedc/                        # Die Anwendung
    ├── config.yaml              # HA Add-on Konfiguration
    ├── Dockerfile               # Multi-Stage Build
    ├── run.sh                   # Container Startscript
    │
    ├── backend/
    │   ├── main.py              # FastAPI Entry Point
    │   ├── requirements.txt
    │   ├── api/routes/          # API Endpoints
    │   │   ├── cockpit.py       # Dashboard-Aggregation
    │   │   ├── aussichten.py    # Prognosen (NEU)
    │   │   └── ...              # monatsdaten, investitionen, etc.
    │   ├── core/                # Config, DB, Calculations
    │   ├── models/              # SQLAlchemy Models
    │   └── services/
    │       ├── wetter_service.py        # Multi-Provider Wetterdaten
    │       ├── brightsky_service.py     # DWD-Daten via Bright Sky API
    │       ├── solar_forecast_service.py # Open-Meteo Solar GTI
    │       ├── prognose_service.py      # Prognose-Berechnungen
    │       ├── pdf_service.py           # PDF-Export
    │       ├── mqtt_client.py           # HA Export + MQTT Auto-Discovery
    │       ├── ha_mqtt_sync.py          # MQTT Sync Service
    │       ├── ha_statistics_service.py # HA-DB Statistik-Abfragen (v2.0.0)
    │       ├── vorschlag_service.py     # Intelligente Vorschläge
    │       ├── community_service.py     # Community-Datenaufbereitung (v2.0.3)
    │       └── scheduler.py             # APScheduler für Cron-Jobs
    │
    └── frontend/
        ├── package.json
        ├── vite.config.ts
        ├── src/
        │   ├── api/             # API Client
        │   │   ├── cockpit.ts   # Cockpit/Dashboard
        │   │   └── aussichten.ts # Prognosen
        │   ├── components/      # UI Components
        │   ├── pages/           # Seiten
        │   │   ├── Dashboard.tsx             # Cockpit (Hero-Leiste, Energie-Fluss, Ring-Gauges, Sparkline)
        │   │   ├── Auswertung.tsx            # Analysen (6 Tabs)
        │   │   ├── CommunityVergleich.tsx    # Community (Hauptmenüpunkt, 6 Tabs)
        │   │   ├── Aussichten.tsx            # Prognosen (4 Tabs)
        │   │   ├── PVAnlageDashboard.tsx     # PV String-Vergleich (SOLL-IST)
        │   │   ├── SensorMappingWizard.tsx   # Sensor-Mapping
        │   │   ├── MonatsabschlussWizard.tsx # Monatsabschluss
        │   │   ├── HAStatistikImport.tsx     # HA-Statistik Bulk-Import (v2.0.0)
        │   │   └── aussichten/               # Tab-Komponenten
        │   │       ├── KurzfristTab.tsx
        │   │       ├── LangfristTab.tsx
        │   │       ├── TrendTab.tsx
        │   │       └── FinanzenTab.tsx
        │   ├── hooks/           # React Hooks
        │   └── config/          # Version, etc.
        └── dist/                # Production Build

Datenbank

Typ: SQLite
Pfad: /data/eedc.db
Schema: Wird beim ersten Start automatisch erstellt

Für Schema-Änderungen:

Model in backend/models/ anpassen
Backend neu starten (Schema wird automatisch aktualisiert)

Hinweis für bestehende Installationen (z.B. nach Update auf beta.6):

SQLAlchemy fügt neue Spalten nicht automatisch zu bestehenden Tabellen hinzu. Bei neuen Spalten manuell ausführen:

-- Beispiel für beta.6 Stammdaten-Erweiterung:
ALTER TABLE anlagen ADD COLUMN mastr_id VARCHAR(20);
ALTER TABLE anlagen ADD COLUMN versorger_daten JSON;

Die parameter JSON-Spalte in investitionen wird automatisch erweitert (kein ALTER TABLE nötig).

Tests

# Backend Tests
cd eedc/backend
pytest

# Frontend Tests (noch nicht implementiert)
cd eedc/frontend
npm test

API Dokumentation

Nach dem Start des Backends verfügbar unter:

Format	URL
Swagger UI	http://localhost:8099/api/docs
ReDoc	http://localhost:8099/api/redoc
OpenAPI JSON	http://localhost:8099/api/openapi.json

Wichtige API-Routen

Modul	Endpoints	Beschreibung
Cockpit	`/api/cockpit/*`	Dashboard-Aggregation, KPIs
Aussichten	`/api/aussichten/*`	Prognosen (Kurzfrist, Langfrist, Trend, Finanzen)
Monatsdaten	`/api/monatsdaten/*`	CRUD + Berechnungen
Investitionen	`/api/investitionen/*`	Komponenten, ROI
Import/Export	`/api/import/*`	CSV Import/Export, JSON-Export, PDF-Export
Wetter	`/api/wetter/*`	Open-Meteo, Bright Sky, PVGIS TMY
Strompreise	`/api/strompreise/*`	Tarife CRUD, Spezialtarife (v2.4.0)
HA Statistics	`/api/ha-statistics/*`	HA-DB Langzeitstatistiken (v2.0.0)
Sensor-Mapping	`/api/sensor-mapping/*`	HA Sensor-Zuordnung (v1.1.0)
Monatsabschluss	`/api/monatsabschluss/*`	Monatsabschluss-Wizard (v1.1.0)
Scheduler	`/api/scheduler/*`	Cron-Jobs, Monatswechsel (v1.1.0)
Community	`/api/community/*`	Community-Teilen & Benchmark (v2.0.3)

Aussichten API

GET /api/aussichten/kurzfristig/{anlage_id}     # 7-Tage Wetter-Prognose
GET /api/aussichten/langfristig/{anlage_id}     # 12-Monats PVGIS-Prognose
GET /api/aussichten/trend/{anlage_id}           # Historische Trend-Analyse
GET /api/aussichten/finanzen/{anlage_id}        # Amortisations-Prognose

Sensor-Mapping API (NEU v1.1.0)

GET    /api/sensor-mapping/{anlage_id}                    # Aktuelles Mapping abrufen
GET    /api/sensor-mapping/{anlage_id}/available-sensors   # Verfügbare HA-Sensoren
POST   /api/sensor-mapping/{anlage_id}                    # Mapping speichern
DELETE /api/sensor-mapping/{anlage_id}                    # Mapping löschen
GET    /api/sensor-mapping/{anlage_id}/status             # Kurzstatus
POST   /api/sensor-mapping/{anlage_id}/init-start-values  # MQTT-Startwerte init

Monatsabschluss API (NEU v1.1.0)

GET  /api/monatsabschluss/{anlage_id}/{jahr}/{monat}    # Status + Vorschläge
POST /api/monatsabschluss/{anlage_id}/{jahr}/{monat}    # Abschluss durchführen
GET  /api/monatsabschluss/naechster/{anlage_id}         # Nächster offener Monat
GET  /api/monatsabschluss/historie/{anlage_id}          # Letzte Abschlüsse

Import/Export API (erweitert in beta.8)

POST /api/import/csv/{anlage_id}                # CSV Import (mit Plausibilitätsprüfung)
GET  /api/import/export/{anlage_id}/full        # Vollständiger JSON-Export
GET  /api/import/template/{anlage_id}           # CSV Template herunterladen

HA Statistics API (NEU v2.0.0)

GET  /api/ha-statistics/status                              # Prüft ob HA-DB verfügbar
GET  /api/ha-statistics/monatswerte/{anlage_id}/{jahr}/{monat}  # Einzelner Monat
GET  /api/ha-statistics/verfuegbare-monate/{anlage_id}      # Alle Monate mit Daten
GET  /api/ha-statistics/alle-monatswerte/{anlage_id}        # Bulk: Alle Monatswerte
GET  /api/ha-statistics/import-vorschau/{anlage_id}         # Import-Vorschau mit Konflikten
POST /api/ha-statistics/import/{anlage_id}                  # Import mit Überschreib-Schutz

Strompreise API (erweitert v2.4.0)

GET  /api/strompreise/{anlage_id}                           # Alle Tarife der Anlage
POST /api/strompreise/{anlage_id}                           # Tarif anlegen
GET  /api/strompreise/aktuell/{anlage_id}/{verwendung}      # Aktueller Preis (mit Fallback)

Scheduler API (NEU v1.1.0)

GET  /api/scheduler                                         # Scheduler-Status
POST /api/scheduler/monthly-snapshot                        # Manueller Monatswechsel

Weiterführende Dokumentation

Architektur - Detaillierte technische Dokumentation
Benutzerhandbuch - Für Endbenutzer
CLAUDE.md - KI-Entwicklungskontext

Letzte Aktualisierung: Februar 2026