docs: ADR-0017 Gruppen-Mitgliedschaft aus der Kundenportal-Geräteliste

Dokumentiert die Session-Arbeit vom 19.08.2026: Checkbox-Diff-Verwaltung
der Gruppen-Mitgliedschaft direkt in /geraete, als Gegenstück zur
bestehenden Verwaltung von der Gruppen-Seite aus. Keine neue anode-API,
wiederverwendet die bereits generische Gruppen-API aus ADR-0012.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

adr/0017-gruppen-mitgliedschaft-aus-geraeteliste.md

@@ -0,0 +1,28 @@
+# ADR-0017: Gruppen-Mitgliedschaft direkt aus der Kundenportal-Geräteliste verwaltbar
+
+**Status:** Beschlossen
+**Datum:** 19.08.2026
+
+## Kontext
+
+Nach dem Gruppen-Selfservice-Nachtrag zu ADR-0012 konnten Kund:innen Gruppen bereits vollständig selbst verwalten (`/gruppen`), einschließlich der Geräte-Mitgliedschaft — aber ausschließlich in einer Richtung: von der Gruppen-Detailseite aus (`/gruppen/{id}`), über eine Checkliste aller Geräte der Organisation. Wer stattdessen von einem einzelnen Gerät ausgehend dessen Gruppenzugehörigkeit ändern wollte (der naheliegendere Weg, wenn ein einzelnes neues Gerät ankommt oder ein bestehendes umgruppiert wird), musste den Umweg über die Gruppen-Seite nehmen — es gab keinen Rückweg von der Geräteliste (`/geraete`) aus, obwohl Organisationseinheiten dort bereits genau diese Symmetrie hatten (`/struktur` für die volle Baum-Verwaltung, aber auch „In OE verschieben" direkt aus der Geräteliste, siehe ADR-0012).
+
+## Entscheidung
+
+`/geraete` bekommt das Gruppen-Pendant zur bestehenden OE-Verschieben-Aktion: eine neue Spalte zeigt die aktuelle Gruppen-Mitgliedschaft eines Geräts, und das bestehende Aktionen-Dropdown bekommt eine Checkbox-Liste aller Gruppen der Organisation mit einem „Gruppen aktualisieren"-Button.
+
+**Kein neuer anode-Endpunkt.** Die Mitgliedschafts-API war durch ADR-0012 bereits vollständig generisch (`POST`/`DELETE /api/v1/devices/{device_id}/gruppen/{gruppe_id}`, `GET .../gruppen` für die aktuelle Mitgliedschaft eines Geräts) — dieselbe API, die die Gruppen-Detailseite schon nutzt, nur aus umgekehrter Blickrichtung aufgerufen. `fetch_gruppen()` aus `routers/gruppen.py` wird direkt importiert statt dupliziert.
+
+**Checkbox-Diff statt Einzel-Toggle-Buttons.** Die neue Route (`POST /geraete/{device_id}/gruppen`) erhält die vollständige gewünschte Mitgliedschaftsmenge als Checkbox-Auswahl (mehrere `gruppen_ids`-Werte in einem Formular), lädt serverseitig die aktuelle Mitgliedschaft nach, und berechnet die Differenz (`ausgewählt − aktuell` → hinzufügen, `aktuell − ausgewählt` → entfernen). Das erspart pro Gruppe ein eigenes Formular/einen eigenen Button in einer potenziell mehrgruppigen Liste und bildet den tatsächlichen Anwendungsfall („dieses Gerät soll jetzt in genau diesen Gruppen sein") direkter ab als N einzelne An/Aus-Schalter.
+
+**N+1-Abfragemuster bewusst beibehalten**, nicht neu eingeführt: `geraete_liste()` fragt für jedes angezeigte Gerät einzeln dessen aktuelle Gruppen-Mitgliedschaft ab (kein Bulk-Endpunkt „Gruppen für alle Geräte einer Organisation" existiert). Das spiegelt exakt das bestehende Muster in `admin_kunden.py:gruppe_detail()`, nur in umgekehrter Richtung (dort: alle Geräte einer Gruppe, hier: alle Gruppen eines Geräts). Bei der aktuellen Kundenzahl/Gerätezahl unproblematisch; sollte sich das ändern, wäre ein Bulk-Endpunkt eine spätere, unabhängige Optimierung an beiden Stellen gleichzeitig, keine Neuerfindung.
+
+## Konsequenzen
+
+Zwei gleichwertige Bearbeitungswege für dieselbe Beziehung (Geräteliste → Gruppen wählen, Gruppen-Detailseite → Geräte wählen) — beide rufen dieselbe anode-API auf, kein Konfliktpotenzial zwischen ihnen, da es keinen lokalen Zwischenzustand gibt (jede Aktion liest den aktuellen Stand frisch und schreibt direkt).
+
+`remove_device_from_gruppe` auf anode prüft keine Organisationszugehörigkeit (anders als `add_device_to_gruppe`) — das bleibt unverändert unproblematisch, weil `find_device_in_organization()` in Kundenplattform bereits sicherstellt, dass das Gerät der eigenen Organisation gehört; eine Lösch-Anfrage für eine `gruppe_id` aus einer fremden Organisation trifft dort schlicht keine passende Zeile und ist ein wirkungsloser No-op, kein Sicherheitsproblem.
+
+Live end-to-end auf anode verifiziert (nicht nur die API-Antwort geprüft): Checkbox-Zustand vor/nach Zuweisung, Datenbankzeile in `device_gruppen` nach Hinzufügen vorhanden und nach Entfernen (leere Auswahl) wieder weg, Anzeige-Spalte spiegelt den aktuellen Stand.
+
+Details zum Datenmodell und zur ursprünglichen Konfliktregel („mehr gewinnt" bei widersprüchlichen Gruppen-Merkmalen): ADR-0012.