Initial import from bf-network-r6.opencode — opencode migration

docs/transaktionen/README.md

@@ -0,0 +1,47 @@
+# Transaktionen — Teständerungen mit Ablaufdatum
+
+Hier liegen die Akten offener und geschlossener **Config-Transaktionen**. Werkzeug:
+[`nautobot/gc-transaktion.py`](../../nautobot/gc-transaktion.py).
+
+## Wozu
+
+Eine Änderung, die am Gerät steht, aber nicht in der SoT, ist **Drift** — und Drift sieht bisher immer
+gleich aus, egal ob er ein Versehen ist oder ein laufender Versuch. Wer testen wollte, hatte die Wahl
+zwischen „Compliance kaputt" und „gar nicht testen".
+
+Eine Transaktion macht die Absicht sichtbar, ohne die Governance aufzuweichen: **der Change geht
+weiterhin ausschließlich über Golden Config** (`gc-manual-plan.py`), und die Compliance meldet den
+Drift weiterhin. Neu ist nur, dass `status` ihn **zuordnen** kann.
+
+| SQL | hier |
+|---|---|
+| `BEGIN` | Snapshot des Scope-Abschnitts + Akte mit Gerät, Scope, Grund und **Ablaufdatum** |
+| *uncommitted* | Change ist am Gerät wirksam und im Testumfeld sichtbar, aber nicht in der SoT |
+| `COMMIT` | Template/Config-Context nachziehen → Compliance grün → Akte schließen |
+| `ROLLBACK` | Rückbau-**Vorschlag** aus dem Snapshot, prüfen, deployen, Akte schließen |
+
+## Drei Regeln, die das Werkzeug erzwingt
+
+1. **`--expires` ist Pflicht.** Eine offene Transaktion ohne Frist ist undokumentierter Drift mit
+   besserem Gewissen. `status` markiert überfällige Akten.
+2. **Der Scope ist eine ComplianceRule**, kein Freibrief. Driftet etwas *außerhalb* des Scopes, meldet
+   `status` das ausdrücklich als **nicht abgedeckt**.
+3. **Eine offene Transaktion je Gerät** — sonst ist beim Rollback nicht mehr entscheidbar, wohin zurück.
+
+## Zwei bewusste Grenzen
+
+- **Der Rollback pusht nicht selbst.** Er schreibt einen Vorschlag aus dem Snapshot; `add`-Zeilen aus
+  einem `/export` legen neu an, statt zu ändern, und brauchen meist ein `set [find …]`. Ein Rückbau,
+  den niemand gelesen hat, ist genau die Sorte Automatik, die hier schon zweimal teuer war.
+- **Der Snapshot enthält nur den Scope-Abschnitt.** Ein voller `/export` enthält Firewall, Adressen,
+  Benutzerliste und Skriptquellen — nichts davon wird für den Rückbau gebraucht, und diese Akten liegen
+  im Git. Für den Ernstfall gibt es das binäre `/system backup` auf dem Gerät (`--device-backup`).
+
+## Dateien je Transaktion
+
+| Datei | Inhalt |
+|---|---|
+| `<change-id>.json` | die Akte: Gerät, Scope, Grund, Fristen, Status |
+| `<change-id>.snapshot.rsc` | der Scope-Abschnitt **vor** der Änderung |
+| `<change-id>.commands.rsc` | was deployt wurde |
+| `<change-id>.rollback.rsc` | erst nach `rollback` — der Vorschlag zum Prüfen |