admin/platform-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: fix Auftragskatalog default semantics in ADR-0010

Browse Source 
The catalog isn't a second pool independent of workspaces - a
workspace is just a preset selection from catalog-eligible Merkmale.
Clarifies that the present/absent default for a catalog-eligible
Merkmal with no explicit device_merkmale row must follow workspace
membership, not hardcode to absent; an explicit row always overrides
that default in either direction. The first implementation got this
wrong (hardcoded absent default), which would have silently removed
any already workspace-composed Merkmal the moment it got flagged
catalog-eligible. Fixed in provisioning-server/app.py in the same
pass.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Thomas Stallinger 2026-08-04 10:06:19 +02:00
parent 217f672ddd
commit 38c04cd83a
2 changed files with 3 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
adr/0010-auftragskatalog-geraeteweise-zuweisung.md
View File

@ -24,6 +24,8 @@ Die Ad-hoc-Zuweisung eines Merkmals zu einem einzelnen Gerät ist eine neue, von
Für jedes Gerät wird beim Check-in der vollständige Soll-Zustand aller katalogfähigen Merkmale (nicht nur die neu hinzugekommenen) an den Agenten übermittelt, je Merkmal mit explizitem Zustand `present` oder `absent`. Das ist rein aus dem aktuellen Auswahlstand ableitbar und erfordert keine serverseitige Historie. Damit ein Deselektieren real etwas zurückbaut, muss die zugehörige Ansible-Rolle einen `absent`-Zweig besitzen; das ist eine Erweiterung der Rollenkonvention aus `12-feature-blueprint-model.md`, keine Änderung an diesem Dokument selbst. Für jedes Gerät wird beim Check-in der vollständige Soll-Zustand aller katalogfähigen Merkmale (nicht nur die neu hinzugekommenen) an den Agenten übermittelt, je Merkmal mit explizitem Zustand `present` oder `absent`. Das ist rein aus dem aktuellen Auswahlstand ableitbar und erfordert keine serverseitige Historie. Damit ein Deselektieren real etwas zurückbaut, muss die zugehörige Ansible-Rolle einen `absent`-Zweig besitzen; das ist eine Erweiterung der Rollenkonvention aus `12-feature-blueprint-model.md`, keine Änderung an diesem Dokument selbst.
**Default ohne explizite Auftragszuweisung (nachträglich präzisiert, 04.08.2026):** Der Auftragskatalog ist kein von Workspaces unabhängiger zweiter Pool — ein Workspace ist fachlich nichts anderes als eine Vorauswahl aus katalogfähigen Merkmalen. Fehlt für ein Device eine explizite `device_merkmale`-Zeile zu einem katalogfähigen Merkmal, ist der Default deshalb dessen Workspace-Zugehörigkeit (`present`, wenn das Merkmal Teil des zugewiesenen Workspace ist, sonst `absent`), nicht pauschal `absent`. Eine vorhandene `device_merkmale`-Zeile überschreibt diesen Default immer, in beide Richtungen — auch ein workspace-komponiertes Merkmal lässt sich damit geräteweise abwählen, was hier bewusst kein Konflikt, sondern der Kern der ursprünglichen Abwählbarkeits-Anforderung ist. (In der ersten Umsetzung war der Default fälschlich hart auf `absent` gesetzt, unabhängig von der Workspace-Zugehörigkeit — dadurch hätte das bloße Markieren eines bereits workspace-komponierten Merkmals als katalogfähig es auf jedem betroffenen Gerät beim nächsten Check-in entfernt, ohne dass irgendjemand es abgewählt hätte. In `provisioning-server/app.py` korrigiert.)
Für die Nachvollziehbarkeit pro Gerät wird ein einziges, generisches, ausschließlich anhängendes Ereignisprotokoll (`device_merkmal_events`) eingeführt, statt mehrerer spezialisierter Log-Tabellen. Ein `event_type`-Feld unterscheidet sowohl Auswahländerungen (`selected`, `deselected`) als auch vom Agenten gemeldete Ausführungsergebnisse (`applied`, `apply_failed`, `removed`, `remove_failed`). Damit der Agent Ausführungsergebnisse überhaupt melden kann, braucht die Check-in-API einen neuen, additiven Report-Kanal; dessen genaue Form wird nicht in diesem ADR, sondern bei der Umsetzung in `08-provisioning-api.md` spezifiziert. Für die Nachvollziehbarkeit pro Gerät wird ein einziges, generisches, ausschließlich anhängendes Ereignisprotokoll (`device_merkmal_events`) eingeführt, statt mehrerer spezialisierter Log-Tabellen. Ein `event_type`-Feld unterscheidet sowohl Auswahländerungen (`selected`, `deselected`) als auch vom Agenten gemeldete Ausführungsergebnisse (`applied`, `apply_failed`, `removed`, `remove_failed`). Damit der Agent Ausführungsergebnisse überhaupt melden kann, braucht die Check-in-API einen neuen, additiven Report-Kanal; dessen genaue Form wird nicht in diesem ADR, sondern bei der Umsetzung in `08-provisioning-api.md` spezifiziert.
Workspace-komponierte Merkmale (nicht im Auftragskatalog) bleiben von dieser Änderung unberührt: sie werden weiterhin ausschließlich additiv über `--tags` angewendet, ohne `absent`-Zustand. Die Frage, ob sich eine Workspace-Zusammensetzung nachträglich für ein bereits provisioniertes Gerät ändern und zurückbauen lassen soll, ist ein separates, hier bewusst nicht adressiertes Problem. Workspace-komponierte Merkmale (nicht im Auftragskatalog) bleiben von dieser Änderung unberührt: sie werden weiterhin ausschließlich additiv über `--tags` angewendet, ohne `absent`-Zustand. Die Frage, ob sich eine Workspace-Zusammensetzung nachträglich für ein bereits provisioniertes Gerät ändern und zurückbauen lassen soll, ist ein separates, hier bewusst nicht adressiertes Problem.

2
architecture/09-data-model-v1.md
View File

@ -296,7 +296,7 @@ Constraints:
## Auftragszuweisung ## Auftragszuweisung
Eine Auftragszuweisung beschreibt, ob ein katalogfähiges Merkmal (`im_auftragskatalog = true`) für ein einzelnes Device aktuell ausgewählt ist — unabhängig von dessen Workspace-Zugehörigkeit über die Bereitstellungsvorlage (siehe ADR-0010). Eine Auftragszuweisung beschreibt, ob ein katalogfähiges Merkmal (`im_auftragskatalog = true`) für ein einzelnes Device aktuell ausgewählt ist — als Zeile unabhängig von der Workspace-Zugehörigkeit über die Bereitstellungsvorlage geführt (eigene Tabelle, siehe ADR-0010), aber nicht unabhängig in der Bedeutung: **fehlt** die Zeile, gilt als Default die Workspace-Zugehörigkeit (`present`, wenn das Merkmal Teil des zugewiesenen Workspace ist, sonst `absent`) — der Auftragskatalog ist kein zweiter, von Workspaces losgelöster Pool, sondern dieselben Merkmale, aus denen auch Workspaces zusammengesetzt werden. Eine vorhandene Zeile überschreibt diesen Default immer, in beide Richtungen.
Anders als bei einem Assignment ist das Vorhandensein einer Zeile nicht gleichbedeutend mit „aktiv": Ab- und erneutes Zuwählen ändern das `aktiv`-Flag, statt die Zeile zu löschen und neu anzulegen, damit die Historie über das Ereignisprotokoll (Auftragsereignis) nachvollziehbar bleibt. Anders als bei einem Assignment ist das Vorhandensein einer Zeile nicht gleichbedeutend mit „aktiv": Ab- und erneutes Zuwählen ändern das `aktiv`-Flag, statt die Zeile zu löschen und neu anzulegen, damit die Historie über das Ereignisprotokoll (Auftragsereignis) nachvollziehbar bleibt.