Piwigo_Bratonien_Tools/CURRENT_STATUS.md

# Aktueller Entwicklungsstand

Stand: 18.08.2026

## Plugin

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

## Nicht verhandelbare Migrationsregel

Der bestehende lokale NC Connector bleibt vollständig erhalten, bis der neue WebDAV-Weg End-to-End funktioniert.

Bestehende Quellenmodi:

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

Sie werden nicht automatisch migriert, deaktiviert oder auf den neuen Weg umgestellt.

Der neue Weg entsteht zusätzlich als eigener Modus:

- `webdav-placeholder`

## Ziel des neuen Wegs

Benötigt werden sollen nur:

- normale Piwigo-Installation;
- bereits vorhandene Linux-/PHP-Umgebung;
- Nextcloud-Adresse;
- Nextcloud-Benutzer bzw. App-Passwort;
- WebDAV-Zugriff auf die Inhalte dieses Benutzers.

Nicht vorausgesetzt werden dürfen:

- PostgreSQL-Zugriff auf Nextcloud;
- `occ`-Adminzugriff;
- Rootzugriff des Betreibers;
- Storage-IDs oder Backend-Pfade;
- zusätzliche Host-Mounts;
- FUSE;
- davfs;
- rclone;
- zusätzliche Connector-Systempakete.

Originalbilder werden nicht dauerhaft nach Piwigo kopiert.

## Architektur des WebDAV-Parallelwegs

1. Ausgewählte Nextcloud-Verzeichnisse werden über WebDAV/PROPFIND gelesen.
2. Das Plugin 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 bestehende Shadow Tree bleibt die physische Piwigo-Quelle.
5. Der Shadow Tree bildet die reale Ordner- und Dateinamensstruktur ab, seine Bildziele zeigen jedoch auf Platzhalter statt auf Originale.
6. Ein separates Mapping verbindet Shadow-Tree-Pfad, Connection-ID, Nextcloud-Datei-ID und WebDAV-Pfad.
7. Piwigo soll Album und Bild über diese Struktur registrieren.
8. Wenn echte Bilddaten benötigt werden, wird das Original bei Bedarf über WebDAV gelesen.
9. Piwigo-Derivate werden normal lokal unter `_data/i/` gecacht.
10. Das Original bleibt ausschließlich in Nextcloud.

## Bereits vorhandene Bausteine

### `runtime/lib/build_webdav_placeholder_source.py`

- liest WebDAV rekursiv;
- lädt keine Originalbilder herunter;
- erzeugt eine lokale Platzhalterquelle;
- erzeugt Manifest und WebDAV-Mapping;
- verwendet einen nur wenige Dutzend Byte großen Platzhalter.

### 0.9.5.6 – Verbindungsschicht

Der Parallelweg wurde als eigener Connection-Typ im Plugin angelegt.

- `include/nc_connector_webdav.inc.php`
- Backend-Aktion `nc_connector_create_webdav_parallel`
- `source_mode=webdav-placeholder`
- `adapter=remote`
- ausgewählte WebDAV-Wurzeln werden verbindungseigen gespeichert;
- Nextcloud-Basis-URL und Benutzer werden verbindungseigen gespeichert;
- Secret v3 enthält `nextcloud_user` und `nextcloud_password` rückwärtskompatibel zu älteren Secrets.

## 0.9.5.7 – parallele Runtime angelegt

Der neue Weg besitzt jetzt eine eigene Runtime neben dem bestehenden produktiven Connector.

Neu:

- `runtime/reconcile-webdav.php`
- `runtime/sync-webdav.sh`
- `runtime/run-all.sh` verarbeitet lokale und WebDAV-Verbindungen getrennt.

Wesentliche Regeln:

- `runtime/reconcile.php` für die bestehenden lokalen Modi bleibt unverändert.
- `runtime/sync.sh` für die bestehenden lokalen Modi bleibt unverändert.
- WebDAV-Verbindungen erhalten eigene Runtime-Dateien `webdav-connection-ID.*`.
- Es werden keine PostgreSQL-/View-/Storage-Mapping-Werte für WebDAV verlangt.
- Nextcloud-Zugang wird aus dem verschlüsselten Connection-Secret in eine Runtime-Passwortdatei mit restriktiven Rechten geschrieben.
- WebDAV-Wurzeln werden getrennt als Runtime-Konfiguration gespeichert.
- Der Platzhalter-Builder erzeugt die lokale Platzhalterquelle, Manifest und WebDAV-Mapping.
- Das Manifest wird anschließend durch den bestehenden `shadow_tree.py` verarbeitet.
- Der parallele Shadow Tree liegt absichtlich unter `galleries/bratonien-webdav-ID` und kann deshalb den bestehenden Galeriebaum nicht ersetzen oder überschreiben.
- Die Platzhalterquelle liegt unter Piwigo `_data/bratonien-tools/nc-webdav-source/connection-ID`, damit Piwigo den Symlink-Zielen später folgen kann.
- **Piwigo-Synchronisierung ist in dieser Stufe hart auf `PIWIGO_SYNC_ENABLED=0` gesetzt.** Die Runtime darf aktuell nur den parallelen Shadow Tree bauen. Die Registrierung in Piwigo wird erst nach Sichtprüfung bewusst freigeschaltet.

Damit existieren lokaler Produktivweg und WebDAV-Testweg jetzt gleichzeitig, ohne dass ein Umzug stattgefunden hat.

## Bestehender produktiver Weg

Unverändert:

- PostgreSQL-/View-/Storage-Mapping-Logik;
- lokale Symlinks auf bereits vorhandene Originalpfade;
- `runtime/reconcile.php` für bestehende lokale Adapter;
- `runtime/sync.sh` mit `legacy-view`, `user-shares` und `selected-fileids`;
- API-first-Piwigo-Sync;
- gemeinsame Runtime für aktive bestehende Verbindungen.

## Gemessene WebDAV-Performance

Testbild: 16.091.204 Byte.

Intern:

- 1,829 s
- 8.796.915 Byte/s

Extern:

- 1,865 s
- 8.627.524 Byte/s

Die externe Verbindung war im Test nur ungefähr 2 % langsamer. Der Ansatz bleibt deshalb für bedarfsweisen Originalzugriff geeignet, solange Piwigo-Derivate lokal gecacht werden.

## Löschverhalten seit 0.9.5.5

Das Löschen einer Connector-Verbindung darf nicht an Dateirechten Root-eigener Runtime-Dateien scheitern.

- Datenbankeintrag wird entfernt;
- verwaiste Runtime-Dateien werden vor einem späteren Sync bereinigt;
- andere Verbindungen bleiben unangetastet;
- Nextcloud-Originale und vorhandene Piwigo-Bilder werden nicht gelöscht.

## Nächster Testschritt

Die parallele Runtime ist jetzt vorbereitet. Der nächste Schritt ist bewusst klein und kontrolliert:

1. Plugin auf 0.9.5.7 aktualisieren.
2. Eine kleine neue WebDAV-Testverbindung mit einem überschaubaren Verzeichnis anlegen.
3. Gemeinsamen Runner einmal ausführen lassen.
4. Prüfen, ob unter `galleries/bratonien-webdav-ID` ausschließlich die erwartete Ordnerstruktur und Platzhalter-Symlinks entstehen.
5. WebDAV-Mapping und Manifest im Connection-State prüfen.
6. Bestehende produktive Galerie und bestehende Verbindungen dabei auf Unverändertheit prüfen.

Erst wenn dieser Test sauber ist, wird `PIWIGO_SYNC_ENABLED` für WebDAV separat freigeschaltet und die Piwigo-Registrierung getestet.

## Danach – noch nicht umsetzen

Erst wenn die Registrierung mit Platzhaltern funktioniert:

- echte Bilddaten über WebDAV anfordern;
- Piwigo-Derivate aus echten Originalen erzeugen;
- normalen Derivat-Cache weiterverwenden;
- ETag-basierte Änderungserkennung ergänzen;
- Fehlerfälle und Parallelität testen.

## Voraussetzung vor irgendeinem Umzug

Erfolgreich getestet sein müssen mindestens:

- Verbindungsanlage;
- WebDAV-Verzeichnisauswahl;
- Shadow Tree;
- Piwigo-Registrierung;
- echte Bildausgabe;
- Derivat-Cache;
- Änderungserkennung;
- Löschen/Deaktivieren;
- Fehlerbehandlung;
- Verhalten bei vielen noch ungecachten Bildern.

Erst danach kann eine freiwillige Migration bestehender Verbindungen überhaupt diskutiert werden.