Piwigo_Bratonien_Tools/CURRENT_STATUS.md

# Aktueller Entwicklungsstand

Stand: 18.08.2026

## Plugin

- Aktuelle Plugin-Version: **0.9.5.5**
- Aktueller Entwicklungsblock: **NC Connector – WebDAV-basierter Quellenweg bei vollständigem Erhalt des bestehenden produktiven Wegs**
- GitHub ist das führende Repository.
- Das private Gitea-System bleibt Mirror/Fallback.

## Produktiver Stand

Der bestehende lokale NC Connector bleibt vollständig erhalten und ist weiterhin der produktive Referenzweg.

Aktuell vorhandene Quellenmodi:

- `legacy-view`
- `user-shares`
- `selected-fileids`

Diese Modi dürfen durch die neue WebDAV-Entwicklung weder automatisch migriert noch deaktiviert, überschrieben oder in ihrer Laufzeitlogik verändert werden.

Der bestehende Connector kann weiterhin:

- Nextcloud-Quellen in einen Shadow Tree überführen;
- Ordner als physische Piwigo-Alben synchronisieren;
- Root-Dateien als Orphans registrieren;
- entfernte Quellen aus Piwigo entfernen, ohne Nextcloud-Originale zu löschen;
- neue Connector-Alben privat anlegen;
- Piwigo API-first synchronisieren und bei Bedarf auf einen verbindungseigenen Login-Fallback zurückfallen;
- mehrere aktive Verbindungen über die gemeinsame Runtime verarbeiten.

## 0.9.5.4

- Neuer experimenteller Builder `runtime/lib/build_webdav_placeholder_source.py` hinzugefügt.
- Der Builder liest eine Nextcloud-Quelle rekursiv über WebDAV und erzeugt eine lokale Platzhalterstruktur sowie ein Mapping.
- Es werden keine Originalbilder heruntergeladen.
- Platzhalter sind extrem klein; der derzeitige Builder verwendet ein 1x1-GIF mit wenigen Dutzend Byte.
- Der bestehende produktive Sync wurde dafür nicht umgeschaltet.

## 0.9.5.5

Das Löschen von Connector-Verbindungen wurde gegen unterschiedliche Dateibesitzer zwischen Webserver und Runtime abgesichert.

Vorher konnte das Löschen scheitern, wenn PHP keinen Tombstone im Connector-Statusverzeichnis anlegen durfte. Jetzt gilt:

- das Löschen der Verbindung darf nicht von Schreibrechten auf Runtime-Dateien abhängen;
- die Verbindung wird aus der Piwigo-Datenbank entfernt;
- verwaiste Runtime-Dateien werden beim nächsten Connector-Lauf vor der Synchronisierung bereinigt;
- andere bestehende Verbindungen bleiben unangetastet.

## Architektur – unverändert produktiver Weg

- Nextcloud ist Quelle der Originalbilder.
- Piwigo verwendet einen Shadow Tree unter dem Galeriepfad.
- Der bisherige Weg arbeitet mit lokalen, bereits vorhandenen Speicherpfaden und Symlinks auf die Originale.
- PostgreSQL-/View-/Storage-Mapping-Logik bleibt für bestehende Verbindungen erhalten.
- Runtime-Konfigurationen: `/etc/bratonien-tools/nc-connector/connection-*.conf`
- State: `/var/lib/bratonien-tools/nc-connector/connection-ID`
- Öffentlicher Admin-Status: Piwigo `_data/bratonien-tools/nc-connector-status/`
- Runner: `runtime/run-all.sh`
- Einzelverbindung: `runtime/sync.sh`
- Shadow Tree: `runtime/lib/shadow_tree.py`

## Neuer WebDAV-Weg – Zielbild

Der neue Weg soll als zusätzlicher eigener Quellenmodus entstehen, zum Beispiel:

- `webdav-placeholder`

Er wird ausdrücklich **neben** den bestehenden Modi entwickelt.

### Rahmenbedingungen

Der neue Weg darf nur Dinge voraussetzen, die bei einer normalen Piwigo-Installation und der bereits erforderlichen Linux-/PHP-Umgebung vorhanden sind.

Nicht als Voraussetzung zulässig:

- Rootzugriff des Betreibers;
- zusätzliche Host-Mounts;
- FUSE;
- davfs;
- rclone;
- zusätzliche Systempakete nur für den Connector;
- PostgreSQL-Zugriff auf die Nextcloud-Datenbank;
- `occ`-Adminzugriff;
- Wissen über Nextcloud-Storage-IDs oder Backend-Pfade.

Benötigt werden sollen nur:

- Nextcloud-Adresse;
- normaler Nextcloud-Benutzer bzw. App-Passwort;
- WebDAV-Zugriff auf genau die Inhalte, die dieser Benutzer sehen darf;
- Piwigo selbst und das Plugin.

### Grundidee

WebDAV wird nicht in einen Linux-Dateipfad umgewandelt.

Stattdessen:

1. Das Plugin liest die ausgewählten Nextcloud-Verzeichnisse per WebDAV/PROPFIND.
2. Es erfasst Ordner, Dateinamen, Datei-ID, MIME-Typ, Größe, ETag und WebDAV-Pfad.
3. Für jedes Bild wird nur ein winziger lokaler Platzhalter bereitgestellt.
4. Der Shadow Tree behält seine Rolle als Piwigo-Quelle und enthält die reale Ordner-/Dateinamensstruktur.
5. Die Shadow-Tree-Einträge verweisen auf Platzhalter statt auf das Nextcloud-Original.
6. Ein separates Mapping verknüpft Shadow-Tree-Pfad mit Nextcloud-Verbindung, Datei-ID und WebDAV-Pfad.
7. Piwigo soll die Bilder dadurch zunächst als vorhandene physische Einträge erkennen können.
8. Für echte Bilddaten muss das Plugin bei Bedarf das Original über WebDAV lesen.

### Anzeige und Derivate

Ziel ist nicht, Originale dauerhaft nach Piwigo zu kopieren.

Vorgesehener Ablauf:

- Piwigo kennt Album und Bild über Shadow Tree/Platzhalter.
- Wenn ein Piwigo-Derivat noch fehlt, wird das Original einmal über WebDAV gelesen.
- Piwigo erzeugt daraus sein normales lokales Derivat in `_data/i/`.
- Weitere Aufrufe verwenden den vorhandenen Piwigo-Derivat-Cache.
- Das Nextcloud-Original bleibt ausschließlich in Nextcloud.
- Beim tatsächlichen Abruf eines Originals muss die Quelle erneut über WebDAV gelesen werden.

## Gemessene WebDAV-Performance

Realer Test vom Piwigo-System auf ein Nextcloud-Bild mit 16.091.204 Byte:

Interne Nextcloud-Adresse:

- Zeit: **1,829 s**
- Geschwindigkeit: **8.796.915 Byte/s**

Externe Nextcloud-Adresse:

- Zeit: **1,865 s**
- Geschwindigkeit: **8.627.524 Byte/s**

Die externe Verbindung war damit in diesem Test nur ungefähr 2 % langsamer als die interne Verbindung.

Folgerung für den Plan:

- WebDAV ist für bedarfsweisen Zugriff auf Originale performant genug, um den Ansatz weiterzuverfolgen.
- Entscheidend ist, dass Piwigo-Derivate normal lokal gecacht werden und WebDAV nicht bei jedem Thumbnail-Aufruf erneut angesprochen wird.

## Bereits vorhandener WebDAV-Baustein

`runtime/lib/build_webdav_placeholder_source.py`

Aufgabe:

- WebDAV rekursiv lesen;
- keine Originalbilder herunterladen;
- lokale Platzhalterquelle erzeugen;
- Manifest und WebDAV-Mapping erzeugen.

Dieser Builder ist aktuell nur ein Baustein. Er ist noch nicht als vollständiger Connection-Modus in Wizard, Secret-Speicherung, Reconcile und Runtime integriert.

## Noch notwendige Umsetzung für `webdav-placeholder`

### 1. Verbindungstyp rückwärtskompatibel ergänzen

- neuer eigener `SOURCE_MODE`;
- bestehende drei Modi bleiben unverändert;
- keine automatische Migration alter Verbindungen.

### 2. Nextcloud-Zugang verbindungseigen speichern

Der aktuelle Wizard benutzt Nextcloud-Zugangsdaten bereits für WebDAV-Verzeichnisabfragen, speichert sie aber nicht in einer Form, die die spätere Runtime für WebDAV verwenden kann.

Das Secret-Format muss rückwärtskompatibel erweitert werden um:

- `nextcloud_user`
- `nextcloud_password`

Bestehende Secrets müssen weiterhin lesbar bleiben.

### 3. Wizard-Abschluss für WebDAV-Verbindungen

Eine neue WebDAV-Verbindung darf keine PostgreSQL- oder Storage-Mount-Pflicht haben.

Gespeichert werden müssen mindestens:

- Connection-Name;
- Nextcloud-Basis-URL;
- Nextcloud-Benutzer;
- verschlüsseltes Nextcloud-Passwort/App-Passwort;
- ausgewählte WebDAV-Wurzeln;
- Piwigo-Galeriepfad;
- Piwigo-Authentifizierung für den Sync, sofern benötigt;
- `source_mode=webdav-placeholder`.

### 4. Reconcile und Runtime

`runtime/reconcile.php` muss WebDAV-Verbindungen gesondert behandeln:

- keine PostgreSQL-Konfiguration verlangen;
- keine Storage-Mappings verlangen;
- WebDAV-Zugang sicher in eine verbindungseigene Runtime-Datei überführen;
- bestehende lokale Verbindungstypen unverändert lassen.

`runtime/sync.sh` muss einen eigenen Zweig für `webdav-placeholder` erhalten.

### 5. Shadow Tree

Der bestehende Shadow Tree bleibt erhalten.

Der neue Builder muss nur eine Quelle erzeugen, die vom bestehenden `shadow_tree.py` verarbeitet werden kann. Ein kompletter Umbau des Shadow Trees ist nicht vorgesehen.

### 6. Piwigo-Erkennung testen

Erster PoC:

- kleine neue WebDAV-Testverbindung anlegen;
- einen kleinen ausgewählten Ordner verwenden;
- Platzhalterquelle bauen;
- bestehenden Shadow Tree erzeugen;
- Piwigo synchronisieren;
- prüfen, ob Albumstruktur und Bilder korrekt registriert werden.

Der bestehende produktive Connector bleibt währenddessen aktiv und unverändert.

### 7. Echte Bilddaten statt Platzhalter ausliefern

Erst wenn Piwigo die Platzhalterstruktur korrekt registriert, wird der zweite Teil umgesetzt:

- Piwigo-Anforderung einem WebDAV-Mapping zuordnen;
- echtes Original bei Bedarf über WebDAV lesen;
- Piwigo-Derivate aus der echten Quelle erzeugen;
- normale Piwigo-Derivate weiterverwenden;
- keine dauerhafte Originalkopie in Piwigo.

### 8. Lastverhalten absichern

Vor einer produktiven Umstellung muss geprüft werden:

- Verhalten bei vielen gleichzeitig noch ungecachten Bildern;
- parallele WebDAV-Abfragen;
- Derivat-Erzeugung;
- Fehlerfall bei nicht erreichbarer Nextcloud;
- geänderte oder gelöschte Remote-Dateien;
- Cache-Invalidierung bei geändertem ETag.

## Migrationsregel

Der bisherige Weg bleibt so lange vollständig erhalten, bis der WebDAV-Weg funktional vollständig ist.

Es gibt bis dahin keine automatische Migration bestehender Verbindungen.

Erst nach erfolgreichem End-to-End-Test von:

- Verbindungsanlage;
- Verzeichnisauswahl;
- Shadow Tree;
- Piwigo-Registrierung;
- echter Bildausgabe;
- Derivat-Cache;
- Änderungserkennung;
- Löschen/Deaktivieren;
- Fehlerbehandlung

kann über eine freiwillige Migration bestehender Verbindungen entschieden werden.

## Sicherheit und Datenhaltung

- Nextcloud-Originale werden nicht gelöscht.
- Nextcloud-Originale werden im neuen WebDAV-Weg nicht dauerhaft nach Piwigo kopiert.
- Lokale Piwigo-Derivate sind ausdrücklich erlaubt und Teil des normalen Piwigo-Caches.
- Connector-Zugangsdaten werden verschlüsselt gespeichert.
- Wizard-Secrets bleiben serverseitig.
- Bestehende Verbindungen bleiben während der Entwicklung unangetastet.
- Mutierende Admin-Aktionen verwenden Post/Redirect/Get.
- Self-Updates sind an einen konkreten Commit und SHA-256 gebunden.

## Nächster konkreter Entwicklungsschritt

Rückwärtskompatible Verbindungsschicht für `webdav-placeholder` bauen:

1. Secret-Format um verbindungseigenen Nextcloud-Zugang erweitern.
2. neuen Source-Modus in Datenmodell/Reconcile/Runtime ergänzen.
3. Wizard so erweitern, dass eine WebDAV-Verbindung ohne PostgreSQL und ohne Storage-Mapping abgeschlossen werden kann.
4. danach eine neue Testverbindung anlegen und den Platzhalter-PoC durch den bestehenden Shadow Tree und Piwigo-Sync schicken.