Piwigo_Bratonien_Tools/CURRENT_STATUS.md

# Aktueller Entwicklungsstand

Stand: 18.08.2026

## Plugin

- Aktuelle Plugin-Version: **0.9.5.6**
- 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 begonnen

Der Parallelweg ist jetzt erstmals als eigener Connection-Typ im Plugin angelegt.

Neu:

- `include/nc_connector_webdav.inc.php`
- Backend-Aktion `nc_connector_create_webdav_parallel`
- neue Verbindungen dieses Typs erhalten `source_mode=webdav-placeholder`;
- sie werden als `adapter=remote` und zunächst **deaktiviert** gespeichert;
- bestehende Verbindungen werden dabei nicht verändert;
- ausgewählte WebDAV-Wurzeln werden verbindungseigen gespeichert;
- Nextcloud-Basis-URL und Benutzer werden verbindungseigen gespeichert.

Das Secret-Format wurde rückwärtskompatibel auf Version 3 erweitert um:

- `nextcloud_user`
- `nextcloud_password`

Bestehende v1/v2-Inhalte bleiben lesbar. Neue lokale Wizard-Verbindungen können die Nextcloud-Zugangsdaten ebenfalls mitführen, ohne ihren bisherigen Quellenmodus zu ändern.

Die verbindungseigene Fallback-Verwaltung wurde so angepasst, dass vorhandene WebDAV-Zugangsdaten bei späteren Secret-Änderungen erhalten bleiben. Für `webdav-placeholder` ist kein `db_password` erforderlich.

## 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.

Die neue WebDAV-Verbindung wird aktuell absichtlich noch nicht von dieser Runtime aktiviert.

## 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ächste Bauphase

Der neue Verbindungstyp existiert jetzt parallel. Als Nächstes wird ausschließlich seine Runtime gebaut, ohne die bestehenden drei Modi umzuschreiben.

Reihenfolge:

1. `runtime/reconcile.php` um einen getrennten Zweig für `adapter=remote` + `source_mode=webdav-placeholder` erweitern.
2. Für diesen Zweig **keine** PostgreSQL- und Storage-Mapping-Prüfung durchführen.
3. Nextcloud-Zugang aus dem verschlüsselten Connection-Secret in eine verbindungseigene, nur für die Runtime lesbare Credential-Datei überführen.
4. WebDAV-Wurzeln mit `webdav_path`, `display_name` und optionaler `fileid` als eigene Runtime-Konfiguration schreiben.
5. `runtime/sync.sh` um einen strikt getrennten `webdav-placeholder`-Zweig erweitern.
6. Dort `build_webdav_placeholder_source.py` aufrufen.
7. Das erzeugte Manifest durch den bestehenden `shadow_tree.py` schicken.
8. Erst dann eine **neue** kleine WebDAV-Testverbindung aktivieren und prüfen, ob Piwigo Albumstruktur und Bilddatensätze korrekt registriert.
9. Bestehende Verbindungen laufen während dieses Tests unverändert weiter.

## 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.