diff --git a/docs/development/eos-consolidation.md b/docs/development/eos-consolidation.md index 1e663acf..dbb9869b 100644 --- a/docs/development/eos-consolidation.md +++ b/docs/development/eos-consolidation.md @@ -2,9 +2,13 @@ Status: in progress, not a completed optimizer port. Updated 2026-09-16. +Current PR-ready packages, dependency order and development guidance: +[PR workflow](pr-workflow.md). The first independent fix is ready locally on main; +the complete feature consolidation remains open. + ## Pinned sources -- Official main: `afb7bcb8bc84769ec2febd34e2dea1b1ad44ddbe`. +- Official main: `7ebe6d714be5a8e265c0b5e411de4ed609391f28` (refreshed after initial checkpoint). - Feature branch: `d2e2d58237339454dd8bb226f92677c5987f8b27`. - PR #1256: `6ebd343047b87819b57778359784a616452b5f76`, open, conflicts. - PR #1305: `6fb84765c4b6d2c032fdf83effcb2ea6597f18f9`, open, main target. @@ -142,7 +146,7 @@ pytest-asyncio, pytest-xprocess, pytest-cov and pypdf. The private backup contai Run from the integration worktree (not the original feature worktree): ```powershell -python -m pytest tests/test_typingmodels.py tests/test_config.py tests/test_configabc.py tests/test_configmigrate.py tests/test_configfile.py tests/test_pydantic.py tests/test_consolidation_config.py tests/test_genetichomeappliance.py tests/test_genetic0battery.py tests/test_genetic0inverterefficiency.py tests/test_genetic0simulation.py tests/test_battery.py tests/test_inverter.py tests/test_inverter_efficiency.py tests/test_geneticsimulation.py tests/test_geneticsimulation2.py tests/test_terminalvalue.py tests/test_tailvalue_physics.py tests/test_interpolator.py tests/test_measurement_channels.py tests/test_measurement_energy.py tests/test_measurement_household.py tests/test_battery_capacity.py tests/test_consolidation_file_restore.py tests/test_measurement.py tests/test_genetic0optimize.py tests/test_geneticoptimize.py tests/test_doc.py -q --tb=short +python -m pytest tests/test_typingmodels.py tests/test_config.py tests/test_configabc.py tests/test_configmigrate.py tests/test_configfile.py tests/test_pydantic.py tests/test_consolidation_config.py tests/test_genetichomeappliance.py tests/test_genetic0battery.py tests/test_genetic0inverterefficiency.py tests/test_genetic0simulation.py tests/test_battery.py tests/test_inverter.py tests/test_inverter_efficiency.py tests/test_geneticsimulation.py tests/test_geneticsimulation2.py tests/test_terminalvalue.py tests/test_tailvalue_physics.py tests/test_interpolator.py tests/test_measurement_channels.py tests/test_measurement_energy.py tests/test_measurement_household.py tests/test_battery_capacity.py tests/test_measurement_file_restore.py tests/test_measurement.py tests/test_genetic0optimize.py tests/test_geneticoptimize.py tests/test_doc.py -q --tb=short ``` Do not inherit EOS_DIR/EOS_CONFIG_DIR from documentation generation when running diff --git a/docs/development/pr-drafts/measurement-energy-quality-capacity.md b/docs/development/pr-drafts/measurement-energy-quality-capacity.md new file mode 100644 index 00000000..89c8b6b5 --- /dev/null +++ b/docs/development/pr-drafts/measurement-energy-quality-capacity.md @@ -0,0 +1,36 @@ +# feat(measurement): add typed energy, quality and capacity APIs + +Local branch: `feat/measurement-energy-quality-capacity`. +Review base: `feat/config-integration-base` (`d546f08`). +Eventual target: official main, after its configuration prerequisites land. +Status: tested local package, NOT yet an independent main-target PR. + +## Proposed PR body + +Add typed measurement channels with explicit units and timestamp semantics, sample +quality, energy integration, household energy balances and battery capacity estimates. +Adapt persistence and REST access to main's asynchronous storage. Battery estimates +use keyed device identities and remain separate from the configured active capacity; +storing an estimate requires an explicit request and preserves runtime config updates. + +Expose `/v1/measurement/samples`, `/v1/measurement/energy`, +`/v1/measurement/household` and `/v1/measurement/battery-capacity/{device_id}`. +Regenerate the configuration and OpenAPI contracts. Use synthetic data only. + +Validation: 453 configuration/measurement/device simulation tests and 5 documentation +tests pass. A further 74 measurement/capacity tests pass after carrying over fixture +isolation. Ruff passes for measurement source and the measurement REST module. +Local Windows/Python 3.11.9 validation; full pinned CI remains required. + +Depends on the device maps/converters in #1256, runtime configuration in #1305 and +local fixes for stable device IDs, LCOS migration and charge-rate compatibility. +Includes the independently prepared JSON restore fix; it should land separately first. +No new GENETIC orchestration or battery/inverter physics is included in this branch. + +## Submission gate + +Do not open this whole branch against main now: its ancestry still includes the +unmerged configuration PRs. Preserve those contributors' existing PRs and credit. +Once prerequisites are merged, rebuild/rebase the measurement package onto that +main, inspect the resulting diff and rerun relevant tests before publication. +The comparison to `feat/config-integration-base` isolates today's measurement work. diff --git a/docs/development/pr-drafts/measurement-json-reload.md b/docs/development/pr-drafts/measurement-json-reload.md new file mode 100644 index 00000000..8dbd2471 --- /dev/null +++ b/docs/development/pr-drafts/measurement-json-reload.md @@ -0,0 +1,35 @@ +# fix(measurement): restore JSON records into the existing singleton + +Target: `Akkudoktor-EOS/EOS:main`. +Local branch: `fix/measurement-json-reload`. +Local head: `dba0c9c` (based on main `7ebe6d7`). +Status: locally ready for review; not pushed or published. + +## Proposed PR body + +When measurement persistence falls back to JSON, loading a saved file reports success +but does not restore its records: validating a second `Measurement` returns the +existing singleton. Parse and validate the individual records before inserting them +into that singleton. Invalid files now return `False` instead of reporting success. + +Regression coverage checks round trips, timestamp preservation, repeated loading, +merging with existing timestamps, malformed files without partial validation writes, +and database-provider precedence. Four regression cases fail on unchanged main. +With the fix, all 49 measurement tests pass. + +Validation: `python -m pytest tests/test_measurement_file_restore.py tests/test_measurement.py -q`; +Ruff check and format check of the changed source; `git diff --check`. +Run locally on Windows/Python 3.11.9. The repository's Linux/Python 3.13 pinned CI +and complete test suite have not run for this branch yet. + +No settings or API schema changes. This fix is independent of #1256, #1305 and the +GENETIC port. + +## Exact review scope + +- `src/akkudoktoreos/measurement/measurement.py` +- `tests/test_measurement_file_restore.py` + +Only these two files differ from the pinned main. Do not publish the integration +branch as part of this PR. After explicit publication approval, push this named +branch and open a PR against main; inspect CI before any merge. diff --git a/docs/development/pr-workflow.md b/docs/development/pr-workflow.md new file mode 100644 index 00000000..a98be4c3 --- /dev/null +++ b/docs/development/pr-workflow.md @@ -0,0 +1,96 @@ +# EOS: Arbeitsstand und Weg zu kleinen PRs + +Stand: 16.09.2026. Offizielles main: `7ebe6d7`. + +## Was jetzt möglich ist + +Ein unabhängiger, lokal getesteter PR ist vorbereitet: `fix/measurement-json-reload` +auf aktuellem main. Sein Worktree ist `../EOS-pr-measurement-json`; er enthält nur +zwei geänderte Dateien. Der PR-Text steht in +[measurement-json-reload.md](pr-drafts/measurement-json-reload.md). + +Das ist ein konkreter Einstieg in den PR-Workflow. Die vollständige Übernahme aller +Funktionen aus dem alten Feature-Branch ist noch NICHT abgeschlossen. + +## Branches und ihre Aufgaben + +| Branch | Zweck | Freigabezustand | +| --- | --- | --- | +| `fix/measurement-json-reload` | Kleiner JSON-Ladefehler direkt auf main | Lokal geprüft, Veröffentlichung ausstehend | +| `feat/config-integration-base` | Zusammengeführte #1256/#1305 plus Integrationskorrekturen | Lokale Abhängigkeitsbasis; kein konkurrierender Sammel-PR | +| `feat/measurement-energy-quality-capacity` | Messdatenfunktionen ohne neue Optimiererphysik | Getestet; wartet für main auf Konfigurationsbasis | +| `integration/eos-consolidation-20260916` | Zusammenführung und Prüfung aller Portierungspakete | Unvollständig; kein Gesamt-PR und kein HA-Release | +| `feat/direct-marketing-battery-grid-export` | Ursprüngliche Entwicklung mit lokalen Änderungen | Unverändert erhalten und gesichert | + +Der Worktree `../EOS-pr-measurement` gehört zum Messdatenpaket. +`../EOS-integration-20260916` bleibt der zeitlich begrenzte Portierungsarbeitsplatz. +`../EOS-reference-20260916` bleibt der unveränderte Vergleichsstand für Basisfehler. +Ein Worktree ist nur ein Arbeitsverzeichnis; Gegenstand eines PRs ist der Branch. + +## Umgesetzt und geprüft + +- Geräte-Maps, Algorithmuskonvertierung und Laufzeitkonfiguration aus #1256/#1305. +- Korrekturen für stabile Geräte-IDs, LCOS-Migration und Ladeleistungslisten. +- Messkanäle, Qualität, Energieintegration, Haushaltsbilanz und Kapazitätsschätzung, + einschließlich asynchroner Speicherung und REST-Schnittstellen. +- Im Integrationsbranch außerdem Viertelstunden-Gerätephysik, begrenzter + Batterieexport und Wirkungsgrade; Restwert-/Prognose-Nachlauf-Bausteine. +- GENETIC0 bleibt separat. Sein `/optimize`-Endpunkt beweist keine vollständige + Portierung des neuen GENETIC. + +## Noch offen + +1. Neues GENETIC vollständig auf main-Strukturen anpassen: Viertelstundenplanung, + Exportzustände, adaptive Evolution und zeitlich korrekter Warmstart. +2. Flexible Lastprofile/EV-Fristen mit den Mehrfachzyklen und Zeitfenstern aus + #1256 verbinden. Beide vorhandenen Funktionssätze müssen erhalten bleiben. +3. Horizont, Prognoselücken, Nachlauf und Restwert mit Optimierer und Ergebnissen + verdrahten; bisher sind nur die Bausteine übernommen. +4. Tarifschutz aus #1224/#1304 und seine Regressionstests auf den neuen + asynchronen Vorbereitungsweg übertragen. +5. Lokale kalibrierte PV-Prognose, algorithmusspezifische PDF-Ausgabe und die lokale + Konfigurationslern-Anfrage integrieren. +6. Gesamtabnahme einschließlich API-Weg des neuen GENETIC und gepinnter CI. + Danach erst Übergabe eines festen EOS-Commits an HA und Release-Arbeiten. + +## PR-Reihenfolge + +1. Den unabhängigen JSON-Fix nach Veröffentlichungsfreigabe gegen main einreichen. +2. #1256/#1305 über ihre vorhandenen PRs zusammenführen; lokale Korrekturen dort + zuordnen. Keine pauschale Veröffentlichung der kombinierten Integrationsbasis. +3. Das isolierte Messdatenpaket auf diesen main-Stand setzen, Diff prüfen und + nochmals testen; dann als eigenen PR einreichen. +4. Optimierer, Tarifschutz, PV und Ausgabe jeweils als abgegrenzte Pakete fertigstellen. + Abhängige PRs ausdrücklich als solche behandeln. + +Für jede neue unabhängige Änderung: aktuellen `refs/remotes/origin/main` holen, +einen Themenbranch mit eigenem Worktree starten, lokal testen, den Diff prüfen, +dann PR gegen main. Nach Review und grüner CI mergen. Alte Worktrees erst nach +abgeschlossener Übernahme und Prüfung lokaler Änderungen aufräumen. + +Wegen der vorhandenen gleichnamigen lokalen Branch-Referenz ausdrücklich +`refs/remotes/origin/main` verwenden. Keine neuen unabhängigen Funktionen auf den +alten großen Feature-Branch oder die Integrationsbasis stapeln. + +## Kann die laufende Entwicklung schon umziehen? + +Unabhängige Fehlerkorrekturen und neue Funktionen können ab jetzt in Themenbranches +auf main erfolgen. Für Entwicklung, die den vollständigen neuen GENETIC oder die +noch fehlenden Funktionen benötigt, ist der Integrationsstand noch nicht abgenommen. +Die ursprüngliche Arbeitskopie bleibt erhalten; nichts wurde deployt oder veröffentlicht. + +## HA-Übergabe + +Noch keinen neuen Gesamtstand pinnen oder deployen. Die geplante Schnittstelle nutzt +Geräte-Maps mit stabilen IDs, `levelized_cost_of_storage_amt_kwh`, asynchrone +Messdatenzugriffe und getrennte GENETIC/GENETIC0-Pfade. Details stehen in +[eos-ha-handoff.md](eos-ha-handoff.md). HA-Dateien wurden nicht verändert. + +## Nachweise und Grenzen + +Der JSON-PR: 49 bestandene Tests, Ruff und Formatprüfung. +Das isolierte Messdatenpaket: 453 bestandene Tests plus 5 Dokumentationstests; +74 Tests nach Übernahme der Fixture-Isolation nochmals erfolgreich. +XML-Protokolle liegen in der privaten Sicherung `eos-20260916-120324`. +Linux/Python 3.13, alle gepinnten Abhängigkeiten und die vollständige CI sind damit +nicht bestätigt. Die PRs sind lokal vorbereitet, noch nicht auf GitHub veröffentlicht.