add requirements file

docs/requirementes/raw-requirements.md

@@ -0,0 +1,189 @@
+# UVI – Anforderungen (Pilot)
+
+> Anforderungsdokument. Source of Truth = diese Notion-Seite. Tickets in Linear referenzieren die hier vergebenen IDs.
+> 
+
+> **Methodische Grundlage:** UBA-Leitfaden „Verständliche monatliche Heizinformation als Schlüssel zur Verbrauchsreduktion" (CLIMATE CHANGE 69/2021), Umweltbundesamt 2021.
+> 
+
+---
+
+# 1. Goal State
+
+Ein Mieter kann sich jederzeit in das Dashboard seiner Wohneinheit einloggen und seine monatliche Heizinformation einsehen, gestaltet **vollständig nach dem UBA-Leitfaden**. Die Heizinformation umfasst sechs Module:
+
+1. **Verbrauchsentwicklung** für Heizung und Warmwasser mit 13-Monats-Verlauf, Tendenz-Indikator gegenüber Vorjahresmonat und Witterungs-Kontext (Heizgradtage)
+2. **In-House-Vergleich** des spezifischen Verbrauchs (kWh/m² Gebäudenutzfläche) mit anderen Wohneinheiten desselben Hauses
+3. **Bandtacho-Einordnung** des Hauses in die Gebäudeeffizienzklassen A⁺ bis H
+4. **Spartipp des Monats** für Heizen (in der Heizperiode) bzw. Warmwasser (außerhalb)
+5. **Kostenschätzung** für den aktuellen Monat und Jahr-zu-Datum
+6. **CO2-Emissionen** des Haushalts mit alltagsnahem Vergleichswert
+
+Die Heizinformation erfüllt § 6a Abs. 2 HeizkostenV. Der gesetzlich geforderte Durchschnittsnutzer-Vergleich (§ 6a Abs. 2 Nr. 3) wird durch die Kombination aus Modul 2 und Modul 3 abgedeckt — wie vom UBA-Leitfaden empfohlen.
+
+## In Scope
+
+- Alle sechs Module gemäß UBA-Leitfaden
+- Mieter-Dashboard mit Magic-Link-Login pro Wohneinheit
+- Datenempfang von Gateways
+- Read-Only Admin-Dashboard, gruppiert nach Gebäudeadresse
+- Unterscheidung Heizperiode / außerhalb Heizperiode
+- Integration externer Referenzdaten: DWD Heizgradtage, GEG-Anlagen 9 und 10
+
+## Out of Scope (für UVI)
+
+- Jährliche Heizkostenabrechnung (eigenes Epic)
+- Vermieter-/Hausverwaltungs-Sicht
+- Witterungsbereinigung der Verbräuche (gehört zur Jahresabrechnung)
+- Self-Service-UI für Geräte-zu-Wohneinheit-Zuordnung (post-Pilot)
+- API-Keys pro Wohneinheit (Future)
+- Optionale UBA-Leitfaden-Erweiterungen: Lage der Wohnung, energetischer Zustand, Pro-Kopf-Vergleichswerte, tägliche Verbrauchsinformationen, Gamification
+- „Energieanalyse aus dem Verbrauch" (DIN TS 12831-1, DIN V 18599)
+
+## Phasenmodell
+
+| Phase | Geräte-Zuordnung | Admin-Dashboard | Mieter-Dashboard |
+| --- | --- | --- | --- |
+| **Pilot** | Manuell direkt in der Datenbank | Read-Only Übersicht aller Wohneinheiten, gruppiert nach Gebäudeadresse | Vollständig (alle 6 Module) |
+| **Post-Pilot** | UI/Mechanismus *(TBD)* | Erweitert um Zuordnungs-Funktionen | Vollständig + ggf. optionale Erweiterungen |
+
+---
+
+# 2. Anforderungen
+
+## 2.1 Compliance — § 6a HeizkostenV
+
+| ID | Anforderung | Quelle | Erfüllung |
+| --- | --- | --- | --- |
+| UVI-COMP-01 | Verbrauch des Mieters im letzten Monat in kWh wird bereitgestellt | § 6a Abs. 2 Nr. 1 | Modul 1 |
+| UVI-COMP-02 | Vergleich mit dem Verbrauch des Vormonats desselben Mieters | § 6a Abs. 2 Nr. 2 | Modul 1 (visuell im 13-Monats-Verlauf) |
+| UVI-COMP-03 | Vergleich mit dem entsprechenden Monat des Vorjahres desselben Mieters | § 6a Abs. 2 Nr. 2 | Modul 1 (Tendenz-Indikator + Witterungskontext) |
+| UVI-COMP-04 | Vergleich mit Durchschnittsnutzer derselben Nutzerkategorie | § 6a Abs. 2 Nr. 3 | Modul 2 (In-House) + Modul 3 (Bandtacho) |
+| UVI-COMP-05 | Bereitstellung mindestens monatlich | § 6a Abs. 1 Nr. 2 | — |
+
+## 2.2 Funktional
+
+Spalte „Modul" referenziert die Module des UBA-Leitfadens (1–6).
+
+| ID | Anforderung | Modul |
+| --- | --- | --- |
+| UVI-FUN-01 | Empfang von Verbrauchsdaten von Gateways | — |
+| UVI-FUN-02 | *(Platzhalter)* Geräte-zu-Wohneinheit-Zuordnung — Pilot manuell in DB; Mechanismus post-Pilot | — |
+| UVI-FUN-03 | Mieter-Login pro Wohneinheit (Magic Link) | — |
+| UVI-FUN-04 | Anzeige des aktuellen Monatsverbrauchs in kWh, getrennt für Heizung und Warmwasser. **Anteil ist nicht nach verbrauchs-/flächenabhängigem Schlüssel gewichtet** (Unterschied zur Jahresabrechnung). | 1 |
+| UVI-FUN-05 | Verlaufsdiagramm der monatlichen Verbräuche der letzten 13 Monate, getrennt für Heizung und Warmwasser; Vorjahresmonat zusätzlich beziffert | 1 |
+| UVI-FUN-06 | Tendenz-Indikator zum Vorjahresmonat: gesunken (grüner Pfeil), gestiegen (roter Pfeil), gleich (grauer Pfeil). „Gleich" wenn auf Zehnerstelle gerundete kWh identisch sind. | 1 |
+| UVI-FUN-07 | Witterungs-Kontext als Fußnote: Heizgradtage-Differenz Vorjahresmonat ↔ aktueller Monat in % | 1 |
+| UVI-FUN-08 | In-House-Vergleich: Sparpotenzial-Pfeil zeigt Spektrum der spezifischen Gesamtverbräuche (Heizung+Warmwasser) aller Wohneinheiten des Hauses in kWh/m² Gebäudenutzfläche | 2 |
+| UVI-FUN-09 | Bei kleinen Häusern (≤ 4 Wohneinheiten) wird zur Wahrung der Anonymität statt des Einzelwerts der Mittelwert der drei sparsamsten Haushalte ausgewiesen | 2 |
+| UVI-FUN-10 | Bandtacho-Einordnung des Hauses in Effizienzklassen A⁺ bis H, basierend auf monatlichen Schwellenwerten (Tabelle 1 UBA-Leitfaden, abgeleitet aus Anlage 10 GEG) | 3 |
+| UVI-FUN-11 | Anzeige eines Spartipps des Monats (Heizen/Lüften in der Heizperiode, Warmwasser außerhalb), inkl. Link zu weiterführenden Beratungsangeboten | 4 |
+| UVI-FUN-12 | Kostenschätzung für aktuellen Monat und Jahr-zu-Datum, berechnet aus Endenergieverbrauch × aktueller Energiepreis pro Brennstoffart | 5 |
+| UVI-FUN-13 | Anzeige der monatlichen CO2-Emissionen in kg, berechnet mit Emissionsfaktor aus Anlage 9 GEG; ergänzt um alltagsnahen Vergleichswert | 6 |
+| UVI-FUN-14 | Außerhalb der Heizperiode: Bandtacho entfällt; Sparpotenzial-Pfeil zeigt nur Warmwasser-Spektrum (rot→blau); Heizungs-Verlaufsdiagramm bleibt sichtbar mit aktuellem Wert 0 kWh | — |
+| UVI-FUN-15 | Fehlende Daten werden im UI klar als „nicht verfügbar" gekennzeichnet (keine stille 0) | — |
+| UVI-FUN-16 | Verbrauchsdaten der letzten 13 Monate sind im Dashboard einsehbar | — |
+| UVI-FUN-17 | Admin-Dashboard zeigt UVI-Daten aller Wohneinheiten als Read-Only-Übersicht, gruppiert nach Gebäudeadresse | — |
+| UVI-FUN-18 | Admin-Login getrennt vom Mieter-Login (Magic Link) | — |
+
+## 2.3 Nicht-funktional
+
+| ID | Anforderung |
+| --- | --- |
+| UVI-NFR-01 | Datenresolution: mindestens monatlich |
+| UVI-NFR-02 | DSGVO-konforme Speicherung und Verarbeitung |
+| UVI-NFR-03 | Strikte Mandantentrennung: kein wohneinheitsübergreifender Datenzugriff für Mieter |
+| UVI-NFR-04 | Datenübertragung von Gateway zum System verschlüsselt (TLS) |
+| UVI-NFR-05 | Daten der UVI sind spätestens am 5. Werktag des Folgemonats im Dashboard sichtbar |
+| UVI-NFR-06 | Verfügbarkeit Dashboard: *(zu definieren – Vorschlag: 99 % im Monatsmittel)* |
+| UVI-NFR-07 | Admin-Authentifizierung getrennt vom Mieter-Login; Admin-Zugriff protokolliert |
+| UVI-NFR-08 | Authentifizierung erfolgt für Mieter und Admin **ausschließlich via Magic Link** (passwortlos) |
+| UVI-NFR-09 | Anonymitätsschutz im In-House-Vergleich (siehe UVI-FUN-09) |
+
+## 2.4 Daten / Domäne
+
+| ID | Anforderung |
+| --- | --- |
+| UVI-DAT-01 | Entität *Wohneinheit* mit eindeutiger ID und **Wohnfläche in m²** |
+| UVI-DAT-02 | *(Platzhalter)* Entität *Gateway/Sensor* und Verknüpfung zu Wohneinheit — Granularität noch offen |
+| UVI-DAT-03 | Entität *Messwert* mit Zeitstempel, Wert in kWh, Typ (Heizung/Warmwasser), Geräte-Referenz |
+| UVI-DAT-04 | Entität *Mieter* mit Zuordnung zu Wohneinheit; Nutzungs-Zeiträume zur Erkennung von Mieterwechseln |
+| UVI-DAT-05 | Entität *Gebäude* mit Adresse, **Brennstoffart**, optional Faktor Wohnfläche → Gebäudenutzfläche (Default 1,2) |
+| UVI-DAT-06 | Aggregate werden **on-the-fly aus Roh-Messwerten berechnet**; keine Persistierung von Aggregaten |
+| UVI-DAT-07 | Referenzdaten: **Bandtacho-Schwellenwerte** der Gebäudeeffizienzklassen aus Anlage 10 GEG, monatlich aufgeteilt gemäß Tabelle 1 UBA-Leitfaden |
+| UVI-DAT-08 | Referenzdaten: **CO2-Emissionsfaktoren** pro Brennstoffart aus Anlage 9 GEG |
+| UVI-DAT-09 | Referenzdaten: **Energiepreise** pro Brennstoffart, regelmäßig aktualisierbar |
+| UVI-DAT-10 | Referenzdaten: **Heizgradtage** pro Monat aus DWD Open Data nach VDI 3807 |
+| UVI-DAT-11 | **Spartipps-Bibliothek**: kategorisiert nach Heizen / Warmwasser, mit optionalen Links |
+
+## 2.5 Methodische Festlegungen
+
+| ID | Anforderung |
+| --- | --- |
+| UVI-MET-01 | Die UVI folgt dem **UBA-Leitfaden** (CLIMATE CHANGE 69/2021) als kanonische Vorlage. Abweichungen werden explizit begründet. |
+| UVI-MET-02 | Der Durchschnittsnutzer-Vergleich gemäß § 6a Abs. 2 Nr. 3 wird durch **Kombination aus In-House-Vergleich (Modul 2) und Bandtacho-Einordnung (Modul 3)** erfüllt. Eine externe Vergleichswertquelle (z.B. BMWK-Bekanntmachung) wird **nicht** zusätzlich verwendet. |
+| UVI-MET-03 | Spezifische Verbräuche werden auf die **Gebäudenutzfläche** bezogen (= Wohnfläche × 1,2, falls keine direkte Angabe vorliegt). |
+
+---
+
+# 3. Mapping Notion ↔ Tickets
+
+- Anforderungen (UVI-COMP-*, UVI-FUN-*, UVI-NFR-*, UVI-DAT-*, UVI-MET-*) bleiben Single Source of Truth in Notion**.
+- User Stories werden in Linear angelegt; Stories enthalten in der Beschreibung die `Erfüllt:`-Zeile als Backlink in Notion.
+- Definition of Done eines Tickets = die Akzeptanzkriterien der Story.
+
+---
+
+# 4. Offene Punkte (zu klären)
+
+- **Geräte-zu-Wohneinheit-Zuordnung (post-Pilot):** Granularität, Pflege, UI vs. Bulk-Import, Validierung. Pilot manuell in DB.
+- **Energiepreis-Pflege (Modul 5):** Wer pflegt die Preise, in welcher Frequenz, aus welcher Quelle?
+- **Mieter-Mail-Erfassung:** Wer hinterlegt die E-Mail-Adresse des Mieters?
+- **Spartipps-Quelle:** Eigene Kuratierung vs. Verlinken auf [verbraucherzentrale.de](http://verbraucherzentrale.de) / co2online?
+- **Datenaufbewahrung:** Wie lange werden Roh-Messwerte gespeichert?
+- **Wetterstationszuordnung pro Gebäude:** Automatisch nach Postleitzahl oder manuell?
+- **Verfügbarkeits-SLA:** Konkreter Wert für UVI-NFR-06.
+- **Sprache/Mehrsprachigkeit:** Nur DE oder auch EN?
+- **Brennstoff-Mix bei Fernwärme:** § 6a Abs. 3 — gehört zur Jahresabrechnung, könnte aber Datenmodell beeinflussen.
+
+## Geklärt seit Beginn
+
+- ✅ Authentifizierung: Magic Link (passwortlos) für Mieter und Admin
+- ✅ Aggregation: on-the-fly, keine Persistierung von Aggregaten
+- ✅ Methodik: Vollständig nach UBA-Leitfaden — alle 6 Module im Pilot
+- ✅ Durchschnittsnutzer-Vergleich: über In-House + Bandtacho (nicht über externe Vergleichswert-Datenbank)
+
+---
+
+# Anhang A — Methodische Grundlage
+
+## A.1 Warum UBA-Leitfaden statt BMWK-Bekanntmachung?
+
+Eine frühere Version dieses Dokuments hatte die BMWK-Bekanntmachung „Regeln für Energieverbrauchswerte im Wohngebäudebestand" (BAnz AT 16.04.2021 B1) als Quelle vorgesehen. Diese Entscheidung wurde nach Auswertung des UBA-Leitfadens revidiert.
+
+Begründung:
+
+1. **Zweck der Quellen unterscheidet sich:** Die BMWK-Bekanntmachung ist für **Energieausweise nach GEG** konzipiert. Der UBA-Leitfaden adressiert exakt unseren Use Case: **monatliche Heizinformation** nach § 6a HeizkostenV.
+2. **Praktische Argumentation des UBA-Leitfadens (S. 23):** Ein gebäudeübergreifender Vergleich anonymisierter Verbräuche setzt voraus, dass die Gebäude einen ähnlichen energetischen Standard haben. Diese Information liegt Messdienstleistern typischerweise nicht vor.
+3. **Der Leitfaden liefert konkrete Vergleichswerte** (Tabelle 1, S. 26) und ein vollständiges Gestaltungsmuster.
+4. **Methodischer Ansatz:** § 6a Abs. 2 Nr. 3 wird erfüllt durch In-House-Vergleich (Modul 2) + Bandtacho (Modul 3).
+
+## A.2 Edge Case: Mieterwechsel
+
+Bei einem Mieterwechsel ist der Vergleich zum Vormonat oder Vorjahresmonat nach § 6a Abs. 2 Nr. 2 nicht möglich. In diesem Fall bleibt nur Modul 2 als verpflichtende Information. Datenmodell: Nutzungs-Zeiträume pro Wohneinheit müssen erfasst sein (UVI-DAT-04).
+
+## A.3 Sanktion bei Nicht-Erfüllung
+
+§ 7 HeizkostenV: Wird die UVI nicht oder unvollständig mitgeteilt, hat der Mieter ein Kürzungsrecht von **3 %** auf den Kostenanteil.
+
+## A.4 Quellen
+
+- **UBA-Leitfaden:** „Verständliche monatliche Heizinformation als Schlüssel zur Verbrauchsreduktion" (CLIMATE CHANGE 69/2021), Umweltbundesamt 2021, Brischke et al. (ifeu)
+- **HeizkostenV § 6a** — Inhalte der UVI
+- **HeizkostenV § 7** — Kürzungsrecht
+- **EU-Richtlinie 2012/27/EU** Anhang VIIa, in der Fassung der RL 2018/2002 (EED)
+- **GEG Anlage 9** — CO2-Emissionsfaktoren
+- **GEG Anlage 10** — Schwellenwerte der Gebäudeeffizienzklassen
+- **VDI 3807** — Heizgradtage und Verbrauchskennwerte (Backup-Referenz)
+- **DWD Open Data** — [opendata.dwd.de/.../hdd_3807/recent/](http://opendata.dwd.de/.../hdd_3807/recent/)
+- **UBA-CO2-Rechner** — [uba.co2-rechner.de](http://uba.co2-rechner.de)