docs: document flood_alert_level values and placeholder filtering

Add observed values and expected Alarmstufe levels to README and OpenAPI schema.

README.md

@@ -117,12 +117,25 @@ Beispielantwort:
 | `title` | string oder `null` | Originaltitel des RSS-Eintrags |
 | `water_level_cm` | number oder `null` | Wasserstand in Zentimetern |
 | `flow_m3s` | number oder `null` | Durchfluss in Kubikmetern pro Sekunde |
-| `flood_alert_level` | string oder `null` | Meldestufe als Text |
+| `flood_alert_level` | string oder `null` | Meldestufe als Text, siehe unten |
 | `source` | string | URL des verwendeten RSS-Feeds |
 | `fetched_at` | string | Zeitpunkt des Abrufs durch die API als UTC-Zeitstempel |
 
 Ein Messwert ist `null`, wenn er im jeweiligen RSS-Eintrag fehlt oder nicht erkannt werden kann. Zeitstempel werden, wenn möglich, aus der Uhrzeit im RSS-Titel gebildet; andernfalls verwendet die API das Datumsfeld des Feeds. Sommer- und Winterzeit werden als Offset berücksichtigt.
 
+Einträge ohne Wasserstand und ohne Durchfluss (Platzhalter der Quelle für noch nicht verfügbare Messwerte, Meldestufe „Keine aktuellen Daten verfügbar“) werden herausgefiltert. `latest` ist daher der neueste Eintrag mit mindestens einem Messwert und kann vom neuesten Eintrag der Quelle abweichen.
+
+### Werte von `flood_alert_level`
+
+| Wert | Bedeutung |
+| --- | --- |
+| `Niedrigwasser` | Niedrigwasser |
+| `Kein Hochwasser` | Hochwassermeldepegel, Richtwerte nicht erreicht |
+| `Kein Hochwassermeldepegel` | Pegel ohne Hochwassermeldefunktion |
+| `Alarmstufe 1` bis `Alarmstufe 4` | Richtwert der jeweiligen Alarmstufe überschritten (1 Meldedienst, 2 Kontrolldienst, 3 Wachdienst, 4 Hochwasserabwehr) |
+
+Die ersten drei Werte wurden in den Feeds aller Pegel beobachtet. Die Alarmstufen stammen aus der Legende der HWIMS-Übersichtsseite; ihre genaue Schreibweise im RSS-Feed ist nicht verifiziert, da sie bei der Prüfung nicht aufgetreten sind. Clients sollten unbekannte Werte tolerieren.
+
 ## Fehlerantworten
 
 Fehler der API enthalten ein JSON-Objekt mit dem Feld `detail`.
@@ -131,7 +144,7 @@ Fehler der API enthalten ein JSON-Objekt mit dem Feld `detail`.
 | --- | --- | --- |
 | `400` | `limit` ist kleiner oder gleich null | `Ungültiger limit-Parameter` |
 | `400` | Pegel-ID hat nicht mindestens sechs Ziffern | `Ungültige Pegel-ID` |
-| `404` | Feed enthält keine Einträge für die Pegel-ID | `Keine Daten gefunden` |
+| `404` | Feed enthält keine Einträge mit Messwerten für die Pegel-ID | `Keine Daten gefunden` |
 | `422` | Query-Parameter kann nicht als Zahl interpretiert werden | FastAPI-Validierungsfehler |
 | `502` | Stationsübersicht nicht erreichbar und kein Cache vorhanden | `Upstream-Discovery nicht verfügbar` |
 

api/app.py

@@ -1,6 +1,6 @@
 from fastapi import FastAPI, HTTPException
 from fastapi.responses import JSONResponse, RedirectResponse
-from pydantic import BaseModel
+from pydantic import BaseModel, Field
 import feedparser
 import re
 import html
@@ -54,7 +54,24 @@ class PegelEntry(BaseModel):
     title: str | None
     water_level_cm: float | None
     flow_m3s: float | None
-    flood_alert_level: str | None
+    flood_alert_level: str | None = Field(
+        description=(
+            "Meldestufe als Text. Beobachtete Werte: `Niedrigwasser`, `Kein Hochwasser`, "
+            "`Kein Hochwassermeldepegel` (Pegel ohne Hochwassermeldefunktion). Bei "
+            "Hochwasser sind laut HWIMS-Legende `Alarmstufe 1` bis `Alarmstufe 4` zu "
+            "erwarten; deren genaue Schreibweise im Feed ist nicht verifiziert. "
+            "Clients sollten unbekannte Werte tolerieren."
+        ),
+        examples=[
+            "Niedrigwasser",
+            "Kein Hochwasser",
+            "Kein Hochwassermeldepegel",
+            "Alarmstufe 1",
+            "Alarmstufe 2",
+            "Alarmstufe 3",
+            "Alarmstufe 4",
+        ],
+    )
 
 class PegelResponse(BaseModel):
     station_id: str