docs: refresh current development status

CURRENT_STATUS.md

@@ -2,11 +2,13 @@
 
 ## Version
 
-**Bratonien Tools 0.9.6.2**
+**Bratonien Tools 0.9.6.8.19**
+
+Zielplattform der produktiven NC-Connector-Synchronisierung ist derzeit **Piwigo 16.4.0**.
 
 ## NC Connector
 
-Der NC Connector besitzt nur noch einen produktiven Verbindungsweg: **Nextcloud per WebDAV**.
+Der NC Connector besitzt einen produktiven Verbindungsweg: **Nextcloud per WebDAV**.
 
 ### Verbindungsmodell
 
@@ -14,30 +16,87 @@ Der NC Connector besitzt nur noch einen produktiven Verbindungsweg: **Nextcloud
 - `source_mode=webdav-placeholder`
 - Nextcloud-Adresse, Benutzer und Passwort/App-Passwort werden pro Verbindung verschlüsselt gespeichert.
 - Piwigo-API und Benutzername/Passwort-Fallback werden ebenfalls pro Verbindung gespeichert.
-- Der Assistent zeigt ausschließlich die Verzeichnisse, auf die der angemeldete Nextcloud-Benutzer per WebDAV zugreifen kann.
-- Mehrere Verzeichnisse können pro Verbindung ausgewählt werden.
+- Der Assistent zeigt ausschließlich Verzeichnisse, auf die der angemeldete Nextcloud-Benutzer per WebDAV zugreifen kann.
+- Ein leerer `webdav_path` ist ein gültiger Root und bedeutet den Dateibereich des authentifizierten Nextcloud-Benutzers.
+
+### Root-Verhalten
+
+Bei `webdav_path=""` wird die technische Nextcloud-Benutzerebene nicht als Piwigo-Album angelegt.
+
+Direkte Unterordner des Nextcloud-Benutzerroots werden als Top-Level-Piwigo-Alben gespiegelt. Direkt im Root liegende Einzelbilder verbleiben auf Root-Ebene des verbindungseigenen Shadow Trees und werden durch die bestehende Orphan-Logik behandelt.
+
+Es gibt keine fest verdrahteten Album-Namen.
 
 ### Laufzeit
 
-Der gemeinsame Runner verarbeitet ausschließlich WebDAV-Verbindungen:
+Der gemeinsame Runner verarbeitet WebDAV-Verbindungen in dieser Reihenfolge:
 
 1. `runtime/reconcile-webdav.php`
-2. `runtime/cleanup-webdav-piwigo.php`
-3. `runtime/sync-webdav.sh` für jede vorhandene WebDAV-Konfiguration
+2. `runtime/repair-webdav-orphans.php`
+3. `runtime/cleanup-webdav-piwigo.php`
+4. `runtime/sync-webdav.sh` für jede vorhandene WebDAV-Konfiguration
 
 Die verbindungsspezifischen Runtime-Konfigurationen liegen unter `/etc/bratonien-tools/nc-connector/`. Zustandsdaten liegen unter `/var/lib/bratonien-tools/nc-connector/connection-ID`.
 
-### Shadow Tree und Piwigo
+Der Reconcile- und Shell-Pfad unterstützt den leeren WebDAV-Root ausdrücklich und gibt ihn als `--root ""` an den Platzhalter-Builder weiter.
 
-`runtime/lib/build_webdav_placeholder_source.py` bildet die ausgewählten Nextcloud-Inhalte als lokale Platzhalterquelle ab. `runtime/lib/shadow_tree.py` erzeugt daraus die Dateisystemstruktur, die Piwigo als physische Site sieht.
+### Platzhalterquelle und Shadow Tree
 
-Jede WebDAV-Verbindung besitzt ihre eigene Piwigo-Site. `runtime/lib/piwigo-sync.php` übergibt genau diese Site an `bratonien.nc.syncProductive` und `bratonien.nc.syncOrphans`. Es gibt keinen zusätzlichen Sync auf Site 1.
+`runtime/lib/build_webdav_placeholder_source.py` bildet die Nextcloud-Inhalte als lokale Platzhalterquelle ab. Für Bilder existieren physische 1×1-Platzhalterdateien; die Originale werden dabei nicht dauerhaft heruntergeladen.
 
-Der Shadow Tree dient ausschließlich dazu, Piwigo die Alben und Bilder als Dateisystemstruktur bereitzustellen. Albumlogik, Dateisynchronisierung und die daraus folgenden Piwigo-Datensätze bleiben Aufgabe von Piwigo.
+`runtime/lib/shadow_tree.py` erzeugt atomar die Dateisystemstruktur, die Piwigo als physische Site sieht. Shadow-Verzeichnisse werden so angelegt, dass der Webserver die für die On-Demand-Materialisierung nötigen Dateisystemoperationen ausführen kann.
+
+Jede WebDAV-Verbindung besitzt ihre eigene Piwigo-Site. Es gibt keinen zusätzlichen Sync auf Site 1.
+
+### Piwigo-Synchronisierung
+
+`runtime/lib/piwigo-sync.php` bevorzugt `bratonien.nc.syncProductive` für Piwigo 16.4.0. Wenn für die Verbindung keine Piwigo-API eingerichtet ist, wird der gespeicherte Administrator-/Webmaster-Benutzername/Passwort-Fallback verwendet und Piwigos nativer `site_update` ausgeführt.
+
+Danach wird `bratonien.nc.syncOrphans` für die konkrete WebDAV-Site ausgeführt.
+
+Der Shadow Tree stellt Piwigo ausschließlich die physische Album-/Bildstruktur bereit. Albumdatensätze, Bilddatensätze, Bild-Kategorie-Verknüpfungen und Piwigo-Derivate bleiben Aufgabe von Piwigo.
+
+### On-Demand-Materialisierung vor `i.php`
+
+Die produktive WebDAV-Derivaterzeugung sitzt vor Piwigos `i.php`.
+
+`include/webdav_materialize_runtime.inc.php` löst aus dem Piwigo-Bildpfad die konkrete Verbindung, den ausgewählten Nextcloud-Root und den relativen WebDAV-Pfad auf.
+
+Für ein noch nicht vorhandenes Derivat läuft `webdav-derivative.php`:
+
+1. Zugriffsprüfung für das Piwigo-Bild;
+2. Download des Originals aus Nextcloud in eine temporäre Datei;
+3. temporäres Bereitstellen des Originals am exakten von Piwigo erwarteten Quellpfad;
+4. Aufruf des nativen Piwigo-`i.php`;
+5. Piwigo erzeugt sein normales Derivat;
+6. Wiederherstellung des Shadow-/Platzhalterzustands;
+7. Auslieferung des Piwigo-Derivats.
+
+Das Original verbleibt in Nextcloud. Es gibt keine dauerhafte vollständige Originalkopie in Piwigo.
+
+### Orphan-Logik
+
+Direkt im WebDAV-Site-Root liegende Bilder werden nicht künstlich in ein Album gezwungen. Sie werden durch `bratonien.nc.syncOrphans` als Piwigo-Orphans synchronisiert.
+
+`runtime/repair-webdav-orphans.php` läuft vor den verbindungsspezifischen Syncs und repariert historische WebDAV-Orphan-Zustände.
+
+### Private Top-Level-Alben
+
+Da die technische Nextcloud-Benutzerebene nicht mehr als Elternalbum existiert, können WebDAV-Unterordner echte private Top-Level-Piwigo-Alben sein. Beim Connector-Fallback-Sync sorgt `bratonien_tools_preserve_connector_top_level_access()` dafür, dass der verwendete Piwigo-Administrator auf diese privaten Top-Level-Alben zugreifen kann. Nach Änderungen wird der Benutzer-Cache invalidiert.
+
+Die allgemeine bestehende Funktion `bratonien_tools_preserve_private_album_access()` in `include/album_shares.inc.php` bleibt davon getrennt.
+
+### Administrations-Dashboard
+
+Piwigo 16.4.0 zeigt die Album-Kachel im Standardtemplate nur bei `NB_ALBUMS > 1` an. Dadurch verschwand die Kachel nach dem korrekten Entfernen der künstlichen Nextcloud-Benutzerebene, sobald nur noch ein echtes Album vorhanden war.
+
+Bratonien Tools setzt für die Verwaltungsübersicht einen Template-Prefilter und ändert ausschließlich diese Anzeigebedingung auf `NB_ALBUMS > 0`. Die Albumzahl selbst stammt weiterhin unverändert aus Piwigos `get_pwg_general_statitics()`.
 
 ### Bildauslieferung
 
-Die Dateien im Shadow Tree sind Platzhalter. `include/webdav_image_runtime.inc.php` erkennt die WebDAV-Zuordnung und ersetzt die Bildquelle bei der Auslieferung durch den zugehörigen Nextcloud-Inhalt. `webdav-image.php` streamt die Bilddaten serverseitig, ohne Nextcloud-Zugangsdaten an den Browser weiterzugeben.
+Fehlende Piwigo-Derivate werden durch den On-Demand-Gate erzeugt. Bereits vorhandene Derivate werden direkt aus Piwigos eigenem Derivat-Cache ausgeliefert.
+
+Für direkte Originalanforderungen existiert weiterhin die serverseitige WebDAV-Originalauslieferung. Nextcloud-Zugangsdaten werden dem Browser nicht offengelegt.
 
 ### Löschen
 
@@ -45,18 +104,37 @@ Eine WebDAV-Verbindung kann unabhängig von ihrer Reihenfolge gelöscht werden.
 
 ### Diagnose
 
-Der Status wird pro Verbindung geführt. Fehler enthalten Zeitpunkt, betroffene Verbindung, Prozesszustand und technische Details. Die Administration zeigt keine lokalen Datenbank-, Storage- oder Mount-Einstellungen mehr an.
+Der WebDAV-Derivative-Gate schreibt Request-bezogene `[BRAT-WD ...]`-Diagnoseeinträge. Der Verbindungsstatus wird pro Verbindung geführt. Runtime-Probleme lassen sich zusätzlich über `bratonien-nc-connector.service` nachvollziehen.
 
-## Entfernte Connector-Komponenten
+## Aktuell relevante Dateien
 
-Nicht mehr Bestandteil des Plugins sind lokale Nextcloud-Datenbankanbindungen, PostgreSQL-Reader, Source-/Activity-Views, Storage-Mappings, Host-Mounts, lokale Reconcile-/Sync-Skripte, Cutover-/Migrationswerkzeuge und der frühere Simulations-Webservice `bratonien.nc.sync`.
+- `main.inc.php` – Plugin-Hooks, Connector-Sync-Hilfen, Dashboard-Prefilter
+- `include/webdav_materialize_runtime.inc.php` – WebDAV-Quellauflösung und Materialisierung
+- `webdav-derivative.php` – On-Demand-Gate vor Piwigos `i.php`
+- `webdav-image.php` – direkte WebDAV-Originalauslieferung
+- `include/nc_productive_ws.inc.php` – direkter Piwigo-Core-Sync für 16.4.0
+- `include/nc_orphan_ws.inc.php` – Root-Orphan-Synchronisierung
+- `runtime/reconcile-webdav.php` – Runtime-Reconcile einschließlich leerem WebDAV-Root
+- `runtime/repair-webdav-orphans.php` – Orphan-Reparatur
+- `runtime/cleanup-webdav-piwigo.php` – Bereinigung verwaister Piwigo-Sites
+- `runtime/sync-webdav.sh` – verbindungsspezifischer Sync
+- `runtime/run-all.sh` – gemeinsamer Runner
+- `runtime/lib/build_webdav_placeholder_source.py` – WebDAV-Scan und Platzhalterquelle
+- `runtime/lib/shadow_tree.py` – atomarer Shadow Tree
+- `runtime/lib/piwigo-sync.php` – Piwigo-API/Fallback-Sync
+
+## Nicht mehr das produktive WebDAV-Modell
+
+Nicht mehr maßgeblich für die produktive WebDAV-Derivaterzeugung ist das frühere Modell, bei dem Bild-URLs einfach auf einen separaten WebDAV-Bildstream umgebogen wurden oder der Connector selbst einen parallelen vollständigen Derivatbestand verwalten sollte.
+
+Maßgeblich ist: **physischer Platzhalter + On-Demand-Original + natives Piwigo-`i.php` + Wiederherstellung des Platzhalters**.
 
 ## Prüfpflicht vor Merge
 
-Jede Änderung wird vor dem Merge mindestens mit folgenden GitHub-Actions-Prüfungen validiert:
+Die GitHub-Actions-Konfiguration prüft mindestens:
 
 - PHP-Syntax für 8.2, 8.3, 8.4 und 8.5
-- Prüfung auf doppelte globale `bratonien_tools_*`-Funktionen
+- doppelte globale `bratonien_tools_*`-Funktionen
 - JavaScript-Syntax
 - Python-Syntax/Compile
 - Shell-Syntax mit `bash -n`