Piwigo_Bratonien_Tools/CURRENT_STATUS.md

# Aktueller Entwicklungsstand

Stand: 17.08.2026

## Plugin

- Aktuelle Plugin-Version: **0.9.3.10**
- Aktueller Entwicklungsblock: **NC Connector – Verbindungsverwaltung / laufende Optimierung**
- NC Connector ist Feature 10 und noch nicht vollständig abgeschlossen.
- Solange dieser Optimierungsblock läuft, bleibt die Version im Bereich `0.9.3.x`.

## Aktueller GitHub-Stand

- Aktuelle Versionsanhebung: `0.9.3.10`
- Anlass: Nextcloud-Showcase-View im zugehörigen Provisioning wurde auf `folder` und `file` vereinheitlicht; damit entspricht die vom Connector genutzte Infrastruktur dem bereits vorhandenen Plugin-Stand.
- Zugehöriger Proxmox-Scripts-Commit: `440173936071240935fd38f4158d8030e9b2e546`

## Architektur NC Connector

- Nextcloud bleibt die einzige dauerhafte Quelle der Originalbilder.
- Piwigo erhält nur die für die Galerie benötigte Verzeichnis-/Symlink-Struktur und erzeugt daraus seine Derivate/Cache-Dateien.
- Der Connector arbeitet mit einem PostgreSQL-Leser und den Views `piwigo_showcase_sources` und `piwigo_showcase_activity`.
- Laufzeitdaten liegen unter `/var/lib/bratonien-tools/nc-connector/...`.
- Verbindungs-Konfigurationen liegen unter `/etc/bratonien-tools/nc-connector/connection-*.conf`.
- Shadow Tree: Verzeichnisse und Symlinks, keine Kopien der Originaldateien.

## Nextcloud-Freigabemodell

Für Showcase gelten zwei Fälle:

1. komplette Ordner werden geteilt;
2. einzelne Bilder werden direkt in das Nextcloud-Stammverzeichnis geteilt.

Die bisherige View filterte ausschließlich `item_type = 'folder'`. Dadurch wurden einzeln geteilte Bilder im Stammverzeichnis vom Connector nicht gesehen.

Der neue Stand erweitert den Connector auf `folder` und `file`:

- Ordner werden weiterhin als Verzeichnisbaum gespiegelt.
- Einzeldateien werden direkt als Symlink im Galerie-/Shadow-Root angelegt.
- Für einzelne Dateien wird **kein künstlicher Unterordner** erzeugt.

## Manifest / Shadow Tree

`runtime/lib/build_manifest.py` wurde auf die Unterscheidung `folder` / `file` erweitert.

Das Manifest führt dabei die Freigabeart mit, damit `runtime/lib/shadow_tree.py` unterscheiden kann:

- `folder` -> Verzeichnisstruktur spiegeln;
- `file` -> Symlink direkt im Galerie-Root.

Die SQL-View-Anpassung wurde so überarbeitet, dass die bestehende Spaltenreihenfolge bei einem Upgrade erhalten bleibt und `item_type` migrationssicher ergänzt werden kann.

## Piwigo-Synchronisation

### Bestehender Admin-Weg

Der produktive Fallback benutzt weiterhin den bestehenden Admin-Sync über `runtime/lib/piwigo-db-sync.pl`.

### API-Weg

Es existiert der eigene Webservice-Endpunkt:

`bratonien.nc.sync`

Aktueller Zustand:

- nur für Piwigo **16.4.0** freigegeben;
- aktuell nur **Simulation**;
- produktiver API-Sync (`simulate=false`) ist bewusst noch deaktiviert;
- API-Key-Authentifizierung wurde erfolgreich gegen Piwigo getestet;
- API-Simulation und originale Piwigo-Admin-Simulation lieferten in den bisherigen Vergleichstests dieselben Ergebnisse.

Der API-Weg soll später der bevorzugte Weg werden. Der klassische Admin-Weg bleibt als Fallback erhalten.

## Fallback-Zugangsdaten

Für den späteren Admin-Fallback gilt:

- bereits dauerhaft gespeicherte Admin-Zugangsdaten dürfen genutzt werden;
- wenn keine gespeichert sind, muss die UI die Eingabe für den Fallback anbieten;
- es muss ausdrücklich die Option **„nur vorübergehend verwenden“** geben;
- temporär eingegebene Zugangsdaten dürfen nicht stillschweigend gespeichert werden;
- dauerhafte Speicherung nur nach ausdrücklicher Auswahl und verschlüsselt.

## Bisherige Tests

Bestätigt:

- stabile Ordnerfreigaben funktionieren;
- Entfernen einer Ordnerfreigabe wurde korrekt als zu entfernende Kategorie erkannt;
- Wiederherstellung der Freigabe stellte den Shadow Tree wieder her;
- API-Simulation und originale Admin-Simulation waren bei den bisherigen Tests deckungsgleich;
- Piwigo selbst unterstützt Dateien direkt im Galerie-Root; die frühere Nichterkennung einzelner Bilder kam vom Nextcloud-View, nicht von Piwigo.

## Aktuell offener Test

Ein einzelnes Bild liegt bereits im Nextcloud-Stammverzeichnis und ist als einzelne Datei geteilt.

Der nächste Test soll die komplette neue Kette prüfen:

`Nextcloud-View -> Manifest -> Shadow Tree -> Piwigo-API-Simulation`

Erwartung:

- das Bild erscheint in der View als `item_type = file`;
- es erscheint im Manifest als Datei-Freigabe;
- es wird direkt im Galerie-/Shadow-Root als Symlink angelegt;
- die Piwigo-Simulation erkennt es anschließend als neues Element.

## Testmodus / Sicherheit

- Der produktive Timer bleibt während der kontrollierten Tests ausgeschaltet.
- Für Connector-Tests wird `PIWIGO_SYNC_OVERRIDE=0` verwendet, damit der Shadow Tree aktualisiert werden kann, ohne den produktiven Piwigo-Datenbank-Sync auszuführen.
- Der verwendete Piwigo-API-Key ist ausschließlich ein temporärer Entwicklungs-/Test-Key und wird nicht Bestandteil der produktiven Konfiguration.

## Bekannte offene Punkte

- finaler End-to-End-Test für einzeln geteilte Bilder im Stammverzeichnis;
- produktiven API-Sync erst nach erfolgreichen Paritätstests aktivieren;
- Admin-Fallback mit temporären bzw. optional dauerhaft gespeicherten Zugangsdaten fertigstellen;
- Activity-Gate-Statusmeldung unterscheidet aktuell nicht sauber zwischen „keine Änderungen“ und „Änderungen erkannt, aber noch im Debounce“;
- Remote-Nextcloud-Adapter ist noch nicht umgesetzt;
- UI und Restpunkte der Verbindungsverwaltung werden nach Abschluss der aktuellen technischen Tests weiter bereinigt.

## Repository-Fallback

Während der Entwicklung bleibt GitHub das führende Repository. Zusätzlich existiert auf dem privaten Gitea-System ein Pull-Mirror als Ausfall-/Fallback-Ebene.