Doku-Vollausbau: 62 Seiten (Projekt/Admin/Anwender/Referenz), Hook-Referenz mit Signaturen, Corporate-Screenshots, Coverage-Inventar

- Einstieg: Schnellstart + Neues Projekt aus Starter-Skill, Was-ist-Tibi mit Backend/Website-Trennung - Projekt: Sammlungen, Felder, Abfragen, Rechte, Hooks, Dateien, i18n, Suche, SSR, Pagebuilder, Jobs, Audit, Deploy, LLM, MCP - Hook-Referenz: 66 Symbole mit Signatur + Beispiel + Fehlerfall (5 Kapitel) - Admin: Ansichten, Editor, Medien, Exporte, Aktionen, Rechte, KI, Setup, Customizing - Anwender: 11 Anleitungen im professionellen Du-Ton, 30 Corporate-Screenshots - Referenz: Schemas, Token-Köpfe, Fehlerbilder, Shortcuts, OpenAPI-Platzhalter - ADR-0001 bis 0003, Coverage-Skript (282 Items) + Map, Plan-Dateien
2026-10-16 22:49:07 +00:00
1 parent acb1d32355
commit 1897bb50d9
@@ -0,0 +1,145 @@
+---
+title: 'Änderungen und Sicherung'
+description: 'Audit-Log lesen, Snapshots nutzen, Backup und Restore mit dem Betreiber abstimmen.'
+---
+
+import { Aside, Steps, Card, CardGrid } from '@astrojs/starlight/components';
+
+Wer hat was geändert — und wie kommst du zurück?
+Drei Ebenen: Das Audit-Log protokolliert Änderungen, Snapshots frieren Datenstände ein, Backups sichern alles für den Ernstfall.
+Suchbegriffe: Änderungshistorie, Verlauf, Wiederherstellen, Snapshot, Datensicherung.
+
+<CardGrid>
+  <Card title="Audit-Log">Protokolliert Änderungen — wer, wann, vorher/nachher.</Card>
+  <Card title="Snapshots">Frieren Datenstände im Ordner `snapshotPath` ein.</Card>
+  <Card title="Backups">Voll-Export als ZIP für Umzug und Ernstfall.</Card>
+</CardGrid>
+
+## Audit einschalten und lesen
+
+Audit ist zweistufig: Es läuft nur, wenn **Server und Projekt** es erlauben.
+
+```yaml title="api/config.yml — Projekt-Opt-in (Starter-Standard)"
+audit:
+  enabled: true
+```
+
+| Ebene | Schalter | Standard |
+|---|---|---|
+| Server | `audit.enabled`, TTL `audit.defaultTTL: 720h` (30 Tage, `"0"` = ewig) | Betreiber-Sache |
+| Projekt | `audit.enabled: true` | Starter: an |
+| Sammlung | `audit: { enabled, actions: [create, update, delete] }` | Standard-Aktionen: anlegen, ändern, löschen |
+| Action | `audit: { enabled, actions: [get, post] }` | Nur was du einschaltest |
+
+<Aside type="note">
+Ohne `audit.enabled: true` im Projekt bleibt das Log dunkel — auch wenn der Server es anbietet.
+Die Sammlung `ssr` (Cache) ist bewusst ausgenommen (`enabled: false`).
+</Aside>
+
+<Steps>
+
+1. Etwas ändern (z. B. Seitentitel per `PUT`).
+2. Im **tibi-admin** die Änderungshistorie des Eintrags öffnen — wer, wann, vorher/nachher.
+3. Alte Fassung per Wiederherstellen zurückschreiben (erst an Testdaten üben).
+4. Per API lesen geht mit `GET /api/v1/audit` (Recht `audit.read` nötig).
+
+</Steps>
+
+## Verlauf im Admin
+
+Du musst nicht per API lesen: Der Admin zeigt den Verlauf an zwei Stellen — pro Eintrag im Editor und global als „Audit-Log“ (`/admin/audit` bzw. `/projects/:id/audit`, mit Filtern für Projekt, Collection, Aktion und Benutzer, 25 Zeilen pro Seite).
+
+**Verlaufspanel pro Eintrag.** Im Editor lädt das Panel die letzten 50 Änderungen dieses Datensatzes, neueste zuerst. Jede Zeile zeigt Zeit, Aktion („erstellt“, „geändert“, „gelöscht“), Person und Quelle; bei „geändert“ steht zusätzlich, welche Felder betroffen sind. Ein Pfeil klappt die Zeile auf und zeigt den Vorher/Nachher-Vergleich. Bei „geändert“ und „gelöscht“ erscheint — nur mit Schreibrecht — der Schalter „Wiederherstellen“, der den alten Stand ins Formular übernimmt (danach noch speichern).
+
+**Diff-Ansicht.** Jeder Vergleich zeigt pro Feld eine Karte mit Status-Badge: „hinzugefügt“, „entfernt“ oder „geändert“. Geänderte Texte stehen als „Vorher“ und „Nachher“ nebeneinander, bei kurzen Texten sind einzelne Wörter markiert. Lange Werte sind eingeklappt und lassen sich per Pfeil ganz aufklappen; jeder Wert hat einen Kopieren-Schalter. Feldnamen kommen aus der Sammlungs-Definition, der technische Pfad steht daneben. Gibt es nichts zu zeigen, meldet die Ansicht „Keine Änderungen“.
+
+**Wiederherstellen-Dialog.** Der Dialog öffnet sich als seitliches Panel („Wiederherstellen“) und stellt „Aktuell“ (aus dem geöffneten Formular) und „Danach“ (aus dem Verlauf) gegenüber. Per Haken wählst du einzelne Felder aus — „Alle auswählen“ und „Keine“ helfen, der Zähler (z. B. 3 / 5) zeigt den Stand. Beachte den Hinweis „Media-Dateien werden nicht wiederhergestellt“. Bestätigen übernimmt die gewählten Felder ins Formular („Felder übernommen — bitte speichern“).
+
+**Seitenleisten-Verlauf.** Unter dem Editor zeigt eine kompakte Liste die letzten 10 Änderungen mit Zeit, Aktion und Person. Sie blendet sich bei leerem Verlauf komplett aus — kein Titel, kein Hinweistext. Ein Klick auf eine Zeile öffnet den vollen Vergleich, bei mehr als 10 Einträgen führt „Ältere Einträge“ zur Gesamtansicht. Nach dem Speichern lädt die Liste automatisch neu.
+
+## Snapshots
+
+Snapshots sind eingefrorene Datenstände im Ordner `snapshotPath` (`../snapshots` im Starter):
+
+```yaml title="api/config.yml — Snapshot-Profile des Starters"
+snapshotPath: ../snapshots
+snapshots:
+  - name: daily          # 12:00 Uhr, redaktionelle Daten + Medien, 14 Stück
+    schedule: "0 12 * * *"
+    collections: [content, navigation, tags, medialib, ssr]
+    includeMedia: true
+    retention: { maxCount: 14 }
+  - name: full-daily
+    schedule: "0 3 * * *"    # 03:00 Uhr, alles + Medien, 14 Stück
+    includeMedia: true
+    retention: { maxCount: 14 }
+  - name: full-weekly    # sonntags 05:00 Uhr, 12 Stück
+    schedule: "0 5 * * 0"
+    collections: []      # leer = alle Sammlungen
+    includeMedia: true
+    retention: { maxCount: 12 }
+  - name: full-monthly   # monatlich, Langzeitarchiv, 12 Stück
+    schedule: "0 6 1 * *"
+    collections: []
+    includeMedia: true
+    retention: { maxCount: 12 }
+```
+
+| Regel | Bedeutung |
+|---|---|
+| `collections: []` (leer) | Alle Sammlungen sichern |
+| Liste mit Namen | Nur diese sichern (Medien nur mit `includeMedia: true`, per Hardlink) |
+| `retention.maxCount` | Älteste fliegen automatisch raus |
+| Speicherung | `json` (BSON-Extended-JSON auf Platte, Standard); `db`/`both` sind Zukunft |
+
+<Aside type="caution" title="Typo im Starter: tags statt tag">
+Das `daily`-Profil oben ist vereinfacht aus der Starter-`config.yml` abgeschrieben (`description`/`enabled` weggelassen) — aber der Name `tags` darin steht wirklich so im Starter, obwohl die Sammlung `tag` heißt (siehe `api/collections/tag.yml`, `name: tag`). Übernimm die Liste nicht blind: prüfe jeden Namen gegen deine `api/collections/*.yml`, sonst sichert das Profil eine Sammlung, die es nicht gibt.
+</Aside>
+
+Im **tibi-admin** (`/projects/:id/snapshots`, drei Tabs):
+
+| Tab | Was du tust |
+|---|---|
+| Configs | Profile ansehen |
+| Entries | Auslösen (mit Fortschritt), herunterladen (ZIP), zurückspielen, löschen, aufräumen |
+| Stats | Belegung prüfen |
+
+Zum Zurückspielen braucht dein Token `AllowSnapshot: true`.
+Übe das Zurückspielen **nur mit Testdaten** — es überschreibt den Live-Stand.
+
+## Backup und Restore (mit Betreiber)
+
+Backups sind der Voll-Export für Umzug und Desaster-Fall — im Admin unter `/projects/:id/backup`:
+
+<Steps>
+
+1. Export-Tab: Sammlungen wählen (Kopf-Kästchen = alle), „Start backup“ klicken, Fortschritt abwarten, Datei mit Größenangabe laden.
+2. Bricht der Download ab: erst Analyse (`backup/analyze-download`), dann neu laden.
+3. Import-Tab: ZIP in die Zone ziehen, Analyse lesen, Restore bestätigen.
+4. Danach: [Reload und SSR-Cache](/projekt/deploy/) prüfen, Seite anonym aufrufen.
+
+</Steps>
+
+| Unterschied | Snapshot | Backup |
+|---|---|---|
+| Wofür | Schneller Rücksprung im Alltag | Umzug, Desaster, Weitergabe |
+| Wo | `snapshotPath` auf dem Server | ZIP-Datei bei dir |
+| Recht | `AllowSnapshot` | Projekt-Admin plus `AllowBackup` |
+| Fortschritt | Ja (Stream) | Ja (SSE-Stream) |
+
+<Aside type="caution">
+Backup und Restore immer mit dem Betreiber abstimmen: Restore überschreibt Daten, große Medien brauchen Zeit und Platz.
+Fortschritt läuft als Stream (`text/event-stream`) — bei Abbrüchen nichts doppelt starten, sondern Analyse neu holen.
+</Aside>
+
+## Fehler
+
+| Fehlerbild | Ursache | Lösung |
+|---|---|---|
+| Audit bleibt leer | `audit.enabled` im Projekt fehlt oder Server-Flag aus | Beide Schalter prüfen, Änderung erneut auslösen |
+| Alte Einträge verschwinden | TTL (`720h`) abgelaufen | Wichtige Stände als Snapshot sichern, TTL ggf. auf `"0"` |
+| Snapshot-Button fehlt | Token ohne `AllowSnapshot` | Betreiber um Recht bitten |
+| Backup-Button fehlt | Kein Projekt-Admin oder `AllowBackup` fehlt | Betreiber um Recht bitten |
+| Restore zeigt keine Wirkung | Cache alt | Reload plus `?clear=1` (siehe [Veröffentlichen](/projekt/deploy/)) |
+
+Verifiziert am e3f92eb 2026-10-14 (tibi-svelte-starter, config.yml audit- und snapshots-Blöcke), am 68b42785 2026-10-15 (tibi-server, audit-, backup- und snapshot-docs), am 2b091d89 2026-10-13 (tibi-admin-nova, test-pläne 43 und 44), am 2b091d89 2026-10-13 (tibi-admin-nova, AuditView, AuditHistoryPanel, AuditDiff, AuditRestoreDialog, AuditSidebarHistory).