4d7ef85406
Brainstorming-Ergebnis der AI-Dev-Method (Phase 0/Design): - HACS-Custom-Integration what_to_wear, Open-Source, standalone in Kunden-HA - Kleiderschrank-Inventar (Sub-Entries), Regeln→Anforderungen→Matcher, optionaler LLM-Ton (BYO-Key) - Wetter v1 aus HA-Wetter-Entität; Open-Meteo/LagerLens/CRUD-Karte = v1.1 - LEDGER inkl. Kritiker-Konsultation (gpt-5.6-luna-pro) zur Wetterquelle Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
157 lines
10 KiB
Markdown
157 lines
10 KiB
Markdown
# What to Wear (WTW) — Design-Spec v1
|
||
|
||
- **Datum:** 2026-07-11
|
||
- **Status:** Entwurf zur Review (Brainstorming-Ergebnis; Keim für den BMAD-PRD)
|
||
- **Methode:** AI-Dev-Method (BMAD + adversariale Reviewer-Linsen + KI-Zweitkritiker)
|
||
- **Domain / Name:** `what_to_wear` — „What to Wear (WTW)"
|
||
|
||
---
|
||
|
||
## 1. Intent (ein Satz)
|
||
Eine **quelloffene Home-Assistant-Integration**, die dem Nutzer abends sagt, **welche konkreten
|
||
Kleidungsstücke aus seinem Kleiderschrank** er für morgen rauslegen soll — deterministisch aus der
|
||
Wetterprognose abgeleitet, optional sprachlich schön formuliert, ausgespielt über Dashboard / Push / Ansage.
|
||
|
||
## 2. Problem & Zielgruppe
|
||
- **Problem:** Morgens Zeitdruck und Fehlgriffe bei der Kleidung; abends fehlt der schnelle Überblick,
|
||
was das Wetter *morgen* konkret verlangt (Regen, Frost, Wind, UV) — und was davon man überhaupt besitzt.
|
||
- **Zielgruppe:** Home-Assistant-Nutzer (DACH + international), die abends Kleidung vorbereiten —
|
||
Pendler, Eltern (Kind anziehen), Menschen mit festem Morgenritual.
|
||
- **Vertriebskontext:** Open-Source-HACS-Produkt (Reichweite/Reputation), später Upsell über einen
|
||
optionalen LagerLens-Connector (KI-Foto-Katalogisierung der Kleidung).
|
||
|
||
## 3. Umfang v1 — bewusste Nicht-Ziele (v1.1+)
|
||
**In v1:**
|
||
- HACS-Custom-Integration `what_to_wear`, Config-Flow, Options-Flow.
|
||
- Kleiderschrank-Inventar **nativ** über HA-Sub-Entries (echte Stücke mit Eigenschaften).
|
||
- `WeatherProvider`-Interface mit **einer** Implementierung: HA-Wetter-Entität.
|
||
- Pipeline: Normalizer → Regel-Engine → Matcher → (optional) LLM-Ton.
|
||
- Ausgabe: **Empfehlungs-Sensor** + Service/Event; **read-only Lovelace-Karte**; **2 Blueprints** (Push, TTS).
|
||
- Optionaler **LLM-Ton** (Bring-your-own-Key, default AUS).
|
||
- i18n **de + en**.
|
||
|
||
**Bewusst vertagt (v1.1+):**
|
||
- LagerLens-Connector als zweite Kleiderschrank-Quelle.
|
||
- Open-Meteo als zweiter `WeatherProvider`.
|
||
- Schöne CRUD-Verwaltungskarte für den Kleiderschrank (v1: native HA-UI genügt).
|
||
- Mehrere Personen/Profile; Aktivitäts-/Kalenderkontext (Termine, „heute Sport"); Wäsche-/Verfügbarkeitsstatus.
|
||
|
||
## 4. Produktform & Distribution
|
||
- Standard-HA-`custom_component` (Python, async), HACS-installierbar; MVP-Struktur:
|
||
```
|
||
custom_components/what_to_wear/ __init__.py, manifest.json, config_flow.py, coordinator.py,
|
||
sensor.py, services.yaml, strings.json, translations/{de,en}.json,
|
||
weather/ (provider-interface + ha_entity impl),
|
||
logic/ (normalize.py, rules.py, matcher.py, phraser.py)
|
||
blueprints/automation/what_to_wear/ notify_push.yaml, announce_tts.yaml
|
||
www/what-to-wear-card.js (read-only Lovelace-Karte)
|
||
```
|
||
- **Lizenz:** Vorschlag **MIT** (offene Kleinentscheidung).
|
||
- **Min-HA-Version:** Vorschlag **2024.12+** (für `weather.get_forecasts` mit `return_response=True`
|
||
und Config-Sub-Entries) — in der Architektur-Phase gegen die tatsächlich benötigten APIs verifizieren.
|
||
- Repo: **lokal** (git `master`), Remote später.
|
||
|
||
## 5. Architektur — Pipeline & Komponenten
|
||
```
|
||
WeatherProvider ─▶ ForecastNormalizer ─▶ RulesEngine ─▶ WardrobeMatcher ─▶ (opt.) LLMPhraser
|
||
│
|
||
RecommendationSensor ◀───────────────────────────────────┘
|
||
│
|
||
(User-Automation via Blueprint) ─▶ Push / TTS / Lovelace-Karte
|
||
```
|
||
- **WeatherProvider** (Interface `async get_tomorrow_forecast() -> RawForecast`): v1-Impl liest die vom
|
||
Nutzer gewählte `weather.*`-Entität via `weather.get_forecasts` (daily + hourly, `return_response=True`).
|
||
- **ForecastNormalizer:** RawForecast → **NormalizedForecast** für *morgen* (lokale TZ), interne **SI-Einheiten**,
|
||
je Feld ein „vorhanden?"-Flag. Aggregiert stündlich → Tageswerte nach lokalem Datum.
|
||
- **RulesEngine:** NormalizedForecast → Liste **Requirement** (Eigenschaft + Grund + Priorität).
|
||
- **WardrobeMatcher:** Requirements × Kleiderschrank → gewählte Stücke + Begründung + **Lücken** („keine Regenjacke").
|
||
- **LLMPhraser** (optional): formt nur den Text; bei Aus/Fehler → deterministischer Regeltext.
|
||
- **DataUpdateCoordinator:** hält das morgige Ergebnis aktuell; Benachrichtigung triggert der Nutzer per Blueprint.
|
||
|
||
### Invarianten-Spine (Keim für die Architektur-Phase)
|
||
- **INV-1 (Nie stumm):** Die Empfehlung fällt nie aus. Bei Teil-Ausfall (LLM, fehlendes Wetterfeld, leerer
|
||
Schrank) liefert der deterministische Kern trotzdem eine Empfehlung und **benennt die Lücke**.
|
||
- **INV-2 (Morgen lokal):** „Morgen" ist stets das lokale Kalenderdatum in `hass.config.time_zone` (DST-fest).
|
||
- **INV-3 (SI intern):** Interne Berechnung nur im SI-Normmodell; Quelle/Einheit/Missingness bleiben am Datum
|
||
erhalten; Werte werden **nie** aus Feldname oder Größenordnung geraten.
|
||
- **INV-4 (Geheimnisse):** LLM-Key (später LagerLens-Token) nie im Klartext in Logs/State/Attributen; nur im
|
||
HA-Config-Storage.
|
||
- **INV-5 (Keine stille Netzlast):** v1 spricht nur mit HA selbst. Externe Provider (v1.1) nur opt-in, mit
|
||
Coordinator/Timeout/Backoff/Attribution; kein stiller Provider-Wechsel.
|
||
- **INV-6 (Trennung):** Normalize / Rules / Matcher sind strikt getrennt und je einzeln testbar.
|
||
|
||
## 6. Datenmodell
|
||
- **Kleidungsstück (Sub-Entry):** `name`, `kategorie` (z. B. Jacke/Pullover/Hose/Schuhe/Accessoire/Kopf/Hand),
|
||
`waerme` 1–5, `wasserdicht` bool, `winddicht` bool, `formalitaet` (leger/business), `saison`/Temp-Range
|
||
(optional), `foto` (optional), `aktiv` bool.
|
||
- **NormalizedForecast (morgen):** `temp_min`, `temp_max`, `temp_gefuehlt_min/max` (°C), `regen_wkt` (%),
|
||
`regen_menge` (mm), `wind` / `boeen` (km/h), `uv_index`, `zustand` (klar/bewölkt/Regen/Schnee/Gewitter) —
|
||
**jeweils mit `vorhanden`-Flag** + Herkunft/Zeitstempel.
|
||
- **Requirement:** `eigenschaft` (z. B. `wasserdichte_aussenschicht`, `waerme_min:4`, `sonnenschutz`,
|
||
`handschuhe`, `muetze`), `grund` (menschlesbar), `prioritaet` (muss/soll/kann).
|
||
- **Recommendation:** `kurztext` (Sensor-State), `stuecke[]`, `requirements[]`, `luecken[]`, `kennwerte`, `quelle`.
|
||
|
||
## 7. Regel-Engine (illustrative Schwellwerte — final in PRD/Architektur)
|
||
> Beispielhaft, konfigurierbar; **nicht** endgültig. Kälteempfinden-Offset verschiebt Temperaturschwellen.
|
||
- `temp_gefuehlt_max < 0 °C` → `waerme_min:5`, `muetze`, `handschuhe`, `schal`.
|
||
- `0–8 °C` → `waerme_min:4`; `8–15 °C` → `waerme_min:3`; `15–22 °C` → `waerme_min:2`; `> 22 °C` → `waerme_min:1`, ggf. `sonnenschutz`.
|
||
- `regen_wkt ≥ 40 %` **oder** `regen_menge ≥ 1 mm` → `wasserdichte_aussenschicht`, `feste_schuhe`.
|
||
- `boeen ≥ 40 km/h` → `winddicht`.
|
||
- `uv_index ≥ 6` → `sonnenschutz` (Brille/Kopfbedeckung).
|
||
- `zustand = Schnee` → `waerme_min:4`, `wasserdicht`, `profilsohle`.
|
||
|
||
## 8. Matcher
|
||
- Wählt je Requirement das am besten passende **aktive** Stück (Priorität muss > soll > kann; bei Gleichstand
|
||
nächstpassende Wärme/Formalität).
|
||
- Fehlt ein Stück für ein `muss`/`soll`-Requirement → **Lücke** in `luecken[]` (z. B. „Für morgen wäre eine
|
||
Regenjacke ideal — keine im Schrank hinterlegt.").
|
||
- Ergebnis ist erklärbar: jedes Stück trägt seinen Grund (welches Requirement es erfüllt).
|
||
|
||
## 9. LLM-Ton (optional, Bring-your-own-Key)
|
||
- Default **AUS**. Nutzer trägt eigenen Key (OpenAI/Anthropic) im Options-Flow ein → nur im Config-Storage.
|
||
- Eingabe an das LLM: die **strukturierte** Recommendation (Stücke + Gründe + Kennwerte) + Zielsprache.
|
||
Aufgabe: nur **umformulieren**, keine neuen Fakten, keine geänderte Stückauswahl.
|
||
- **Fehler/Timeout/kein Key → deterministischer Regeltext** (INV-1). LLM ändert nie die Auswahl.
|
||
|
||
## 10. Ausgabe: Sensor / Service / Karte / Blueprints
|
||
- **Sensor** `sensor.what_to_wear`: `state` = Kurzempfehlung; `attributes` = `stuecke`, `requirements`,
|
||
`luecken`, `kennwerte`, `quelle`, `stand`.
|
||
- **Service/Event** `what_to_wear.recommend` (manuelles Neuberechnen; feuert Event mit dem Ergebnis).
|
||
- **Lovelace-Karte** (read-only): zeigt morgige Empfehlung + Stücke + Lücken dauerhaft.
|
||
- **Blueprints:** `notify_push` (Nutzer wählt notify-Ziel + Uhrzeit), `announce_tts` (Nutzer wählt
|
||
media_player + Auslöser). Import ist ein geführter HA-Klick-Flow → laienfreundlich, ohne notify-Logik
|
||
in der Integration.
|
||
|
||
## 11. Konfiguration
|
||
- **Config-Flow (Ersteinrichtung):** Wetter-Entität wählen (Entity-Selector, Pflicht; Fehler wenn keine da),
|
||
Sprache (Default = HA-Sprache), Kälteempfinden-Offset.
|
||
- **Options-Flow:** Schwellwerte/Offsets, optionaler LLM-Key + Provider (default aus).
|
||
- **Sub-Entries:** Kleidungsstücke anlegen/bearbeiten/löschen in der nativen HA-UI.
|
||
|
||
## 12. Fehlerbehandlung & Edge Cases (aus dem Kritiker-Review)
|
||
- Keine geeignete `weather.*`-Entität → klarer Config-Fehler, kein Raten (INV-1/Config).
|
||
- Wetterfeld fehlt → Regel greift **degradiert** + Hinweis; „fehlend" ≠ „0" (INV-3).
|
||
- „Morgen"/DST strikt in lokaler TZ (INV-2).
|
||
- LLM-Fehler/Timeout/kein Key → Fallback auf Regeltext (INV-1).
|
||
- Leerer/lückenhafter Schrank → Anforderung + Lücke nennen statt schweigen (INV-1).
|
||
- Einheiten (°C/°F, km/h/mph, mm/inch) bewusst konvertieren; Open-Meteo-Wettercode ↔ HA-`condition` per Mapping-Tabelle (v1.1).
|
||
|
||
## 13. i18n
|
||
- HA-Translations für UI (`de`, `en`); Empfehlungstext folgt der HA-Sprache; Regeltext-Bausteine je Sprache.
|
||
|
||
## 14. Tests & echte Verifikation (Methoden-Pflicht)
|
||
- **Unit:** Normalizer/Rules/Matcher mit Wetter-Fixtures (Regen, Frost, Hitze, DST-Tag, fehlende Felder, leerer Schrank).
|
||
- **Integration:** `pytest-homeassistant-custom-component` (Config-Flow, Sensor, Service).
|
||
- **Echte E2E:** Wegwerf-HA-Docker-Instanz — Integration installieren → Wetter-Entität + Beispielschrank →
|
||
Sensor prüfen → Blueprint-Push real auslösen. Negativfälle (keine Wetter-Entität, LLM-Key falsch).
|
||
- **TDD:** Test rot → Code → grün → volle Suite → Commit (ein Commit pro Story). qwen/Cloud-Review nach jeder Story.
|
||
|
||
## 15. Offene Punkte / Annahmen (in PRD/Architektur klären)
|
||
- Lizenz (Vorschlag MIT). Min-HA-Version (Vorschlag 2024.12+, gegen APIs verifizieren).
|
||
- Ob v1 die Sub-Entry-CRUD-UX von HA praktisch trägt (sonst früher CRUD-Karte).
|
||
- Genaue Schwellwerte/Regeln (Kap. 7 illustrativ).
|
||
- Foto-Speicherung bei nativem Kleiderschrank (Pfad/Umfang) — v1 optional/minimal.
|
||
|
||
## 16. Roadmap v1.1+
|
||
LagerLens-Connector (Foto-Katalog) · Open-Meteo-Provider · CRUD-Verwaltungskarte · Mehrpersonen-Profile ·
|
||
Aktivitäts-/Kalenderkontext · Wäsche-/Verfügbarkeitsstatus.
|