Document API-first NC connector auth in 0.9.3.17

CURRENT_STATUS.md

@@ -4,32 +4,40 @@ Stand: 17.08.2026
 
 ## Plugin
 
-- Aktuelle Plugin-Version: **0.9.3.16**
+- Aktuelle Plugin-Version: **0.9.3.17**
 - 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
 
-Der lokale NC Connector ist für den aktuellen Bratonien-Einsatz inzwischen End-to-End funktionsfähig.
+Der lokale NC Connector ist für den aktuellen Bratonien-Einsatz im bisherigen Login-Weg End-to-End funktionsfähig. Mit `0.9.3.17` beginnt der Umbau auf API-first für die Piwigo-Synchronisierung.
 
-Erfolgreich umgesetzt und getestet:
+Bereits erfolgreich umgesetzt und getestet:
 
 - Nextcloud-Freigaben vom Typ `folder` und `file` werden aus der Source-View gelesen.
-- Das Manifest führt beide Freigabetypen korrekt.
 - Ordnerfreigaben werden als Verzeichnisbaum im Shadow Tree gespiegelt.
-- Einzeldateifreigaben werden als Symlink direkt im Galerie-Root angelegt.
+- Einzeldateifreigaben werden als Symlink direkt im Galerie-Root angelegt und als echte Piwigo-Orphans ohne Albumzuordnung registriert.
-- Einzeldateien werden anschließend als echte Piwigo-Orphans ohne Albumzuordnung registriert.
+- Entfernte Einzeldateifreigaben werden beim normalen Connector-Lauf aus Shadow Tree und Piwigo entfernt.
-- Entfernte Einzeldateifreigaben werden beim normalen Connector-Lauf aus dem Shadow Tree und aus Piwigo entfernt.
+- Das Nextcloud-Original bleibt bei Löschvorgängen unangetastet.
-- Das Nextcloud-Original bleibt bei allen Löschvorgängen unangetastet.
+- Connector-getriggerte neue physische Alben werden standardmäßig privat angelegt.
-- Der normale Connector-Lauf führt klassischen Piwigo-Dateisync und Orphan-Abgleich automatisch hintereinander aus.
+- Der gemeinsame systemd-Timer `bratonien-nc-connector.timer` läuft produktiv.
-- Der gemeinsame systemd-Timer `bratonien-nc-connector.timer` kann wieder produktiv verwendet werden.
+
-- Connector-getriggerte neue physische Alben werden standardmäßig privat angelegt, damit neu importierte Inhalte nicht ungeordnet öffentlich erscheinen.
+Neu in `0.9.3.17`:
+
+- die Piwigo-API ist als bevorzugter Synchronisierungsweg vorgesehen;
+- ein erfolgreich geprüfter API-Key wird verschlüsselt in der Piwigo-Konfiguration gespeichert;
+- produktive API-Synchronisierung ist ausdrücklich an die freigegebene Piwigo-Version **16.4.0** gebunden;
+- neuer Webservice `bratonien.nc.syncProductive` delegiert den freigegebenen produktiven Dateisync an Piwigos Core-Synchronisierung;
+- `runtime/lib/piwigo-sync.php` versucht zuerst die API und fällt nur bei nicht nutzbarer API auf Benutzername/Passwort zurück;
+- der bisherige Benutzername/Passwort-Zugang kann als verschlüsselter Fallback gespeichert oder gelöscht werden;
+- ein Benutzername/Passwort-Fallback kann außerdem einmalig manuell ausgeführt werden, ohne die Zugangsdaten zu speichern;
+- neue lokale Verbindungen werden intern als `api-first` angelegt; ein dauerhaft gespeicherter Login-Fallback ist technisch nicht mehr zwingend, sofern ein API-Zugang vorhanden ist.
 
 ## 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 und Cache-Dateien.
+- Piwigo erhält nur die benötigte Verzeichnis-/Symlink-Struktur und erzeugt daraus seine Derivate und 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`.
@@ -38,113 +46,75 @@ Erfolgreich umgesetzt und getestet:
 
 ## Nextcloud-Freigabemodell
 
-Der Connector unterstützt zwei Fälle:
+Der Connector unterstützt komplette Ordner und einzelne Bilder.
 
-1. komplette Ordner werden geteilt;
+- `folder` -> Verzeichnisstruktur spiegeln und über Piwigos Dateisynchronisierung als physische Albumstruktur einlesen;
-2. einzelne Bilder werden direkt geteilt.
-
-Verarbeitung:
-
-- `folder` -> Verzeichnisstruktur spiegeln und über Piwigos klassische Dateisynchronisierung als physische Albumstruktur einlesen;
 - `file` -> Symlink direkt im Galerie-Root und anschließende Registrierung als Piwigo-Orphan.
 
 Für einzelne Dateien wird kein künstlicher Unterordner erzeugt.
 
-## Manifest / Shadow Tree
-
-`runtime/lib/build_manifest.py` unterstützt zwei View-Schemata:
-
-- modern: `share_id, item_type, display_name, storage_id, source_path`;
-- legacy: `share_id, display_name, storage_id, source_path`.
-
-Bei einer Legacy-View wird der Typ nach Auflösung des Storage-Pfads über Datei oder Verzeichnis bestimmt.
-
-Das Manifest führt danach in beiden Fällen:
-
-`share_id, item_type, display_name, source_path`
-
-`runtime/lib/shadow_tree.py` verarbeitet daraus:
-
-- `folder` -> Verzeichnisstruktur spiegeln;
-- `file` -> Symlink direkt im Galerie-Root.
-
 ## Activity-Gate
 
-Das Activity-Gate berücksichtigt neben dem Nextcloud-Aktivitätsstand auch die Signatur der aktuell sichtbaren Freigaben.
+Das Activity-Gate berücksichtigt neben dem Nextcloud-Aktivitätsstand auch die Signatur der aktuell sichtbaren Freigaben. Weiterhin vorhanden sind Quiet-Time, maximale Wartezeit, periodischer Full-Sync und verbindungsspezifischer State.
-
-Damit werden Strukturänderungen an den Shares auch dann erkannt, wenn sie nicht zuverlässig durch einen reinen Maximalwert der Nextcloud-Aktivität abgebildet werden.
-
-Weiterhin vorhanden:
-
-- Quiet-Time;
-- maximale Wartezeit;
-- periodischer Full-Sync;
-- Verbindungsspezifischer State.
 
 ## Piwigo-Synchronisation
 
+### API-first
+
+Der normale Runtime-Lauf verwendet ab `0.9.3.17` folgende Priorität:
+
+1. gespeicherter Piwigo-API-Key;
+2. bei API-Fehler, fehlender Freigabe für die installierte Piwigo-Version oder nicht vorhandener API: gespeicherter Benutzername/Passwort-Fallback;
+3. ohne nutzbaren API- und Fallback-Zugang wird der Piwigo-Sync mit einer klaren Fehlermeldung abgebrochen.
+
+Nach einem Piwigo-Update wird die produktive API nicht automatisch für die neue Version freigeschaltet. Erst nach einem Kompatibilitätstest wird die Versionsfreigabe im Plugin angehoben. Bis dahin bleibt nur der Login-Fallback zulässig.
+
 ### Physische Alben
 
-`runtime/lib/piwigo-db-sync.pl` meldet sich an Piwigo an und löst die normale Dateisynchronisierung für die physischen Albumverzeichnisse aus.
+`bratonien.nc.syncProductive` ist aktuell nur für Piwigo **16.4.0** freigegeben. Der Endpoint läuft als Administrator-Webservice und verwendet für den eigentlichen Dateisync Piwigos Core-Synchronisierung. Neue Connector-Alben werden dabei privat angelegt.
-
-Connector-getriggerte Neuanlagen werden dabei mit privatem Standardstatus verarbeitet.
 
 ### Root-Dateien / Orphans
 
-Piwigos klassische Dateisynchronisation kann Dateien direkt unter dem Galerie-Root nicht als neues Element einem physischen Album zuordnen.
+`bratonien.nc.syncOrphans` verarbeitet direkte Dateien im Galerie-Root separat. Neue Root-Dateien werden als Piwigo-Orphans ohne Albumzuordnung registriert. Entfernte Root-Dateien werden nur aus Piwigo entfernt; das Nextcloud-Original bleibt unberührt.
 
-Deshalb verarbeitet `bratonien.nc.syncOrphans` diese Dateien separat.
+## Erfolgreiche Live-Tests bis 0.9.3.16
-
-Für neue Root-Dateien:
-
-- wird ein normaler Eintrag in `piwigo_images` angelegt;
-- `storage_category_id` bleibt `NULL`;
-- es wird kein Eintrag in `piwigo_image_category` erzeugt;
-- Metadaten und Piwigo-Aktivität werden über vorhandene Piwigo-Funktionen aktualisiert;
-- die Datei erscheint im Batch Manager unter `With no album / Orphans`.
-
-Für entfernte Root-Dateien wird nur der Piwigo-Datenbankeintrag entfernt. Das Nextcloud-Original bleibt unberührt.
-
-### API-Weg
-
-Es existieren zwei eigene Webservice-Endpunkte:
-
-- `bratonien.nc.sync` – vollständiger read-only Paritätstest des klassischen Piwigo-Syncs;
-- `bratonien.nc.syncOrphans` – dedizierte Root-Orphan-Synchronisation mit Simulation und produktivem Modus.
-
-Beide Wege sind aktuell für Piwigo **16.4.0** freigegeben.
-
-## Erfolgreiche Live-Tests
 
 Bestätigt wurden:
 
-- Ordnerfreigaben werden korrekt eingelesen.
+- Ordnerfreigaben werden korrekt eingelesen;
-- Eine einzelne Nextcloud-Dateifreigabe wurde im Manifest als `file` erkannt.
+- Einzeldateifreigaben werden als `file` erkannt und im Galerie-Root verlinkt;
-- Der zugehörige Symlink wurde direkt im Galerie-Root erzeugt.
+- Orphan-Anlage und Orphan-Löschung funktionieren;
-- Die Orphan-Simulation erkannte die Datei als `new_orphans = 1` ohne Datenbankschreibzugriff.
+- physische neue Connector-Alben werden privat angelegt;
-- Der produktive Lauf registrierte die Datei als echtes Piwigo-Orphan.
+- der automatische Timer kann regulär laufen.
-- Die Piwigo-Fotoanzahl stieg dabei entsprechend an.
+
-- Nach Entfernen der Nextcloud-Freigabe meldete der normale Connector-Lauf `files = 0` und `Piwigo-Orphans synchronisiert: +0 / -1`.
+## Offener Test für 0.9.3.17
-- Der Root-Symlink wurde entfernt.
+
-- Ein anschließender Orphan-Abgleich fand keine Restdatei mehr.
+Vor Abschluss des API-first-Blocks muss noch live geprüft werden:
-- Der automatische Timer kann wieder regulär laufen.
+
+1. Plugin-Update auf `0.9.3.17`;
+2. API-Key im NC Connector prüfen und speichern;
+3. produktiver Lauf verwendet `bratonien.nc.syncProductive` erfolgreich;
+4. Ordner- und Orphan-Sync bleiben unverändert korrekt;
+5. gespeicherter Login-Fallback übernimmt bei absichtlich nicht nutzbarer API;
+6. einmaliger Fallback funktioniert ohne Speicherung;
+7. gelöschter Fallback wird vom Runtime-Lauf nicht mehr verwendet.
 
 ## Sicherheit / Betriebsmodell
 
 - Nextcloud bleibt Eigentümer der Originaldateien.
 - Der Connector löscht keine Originaldateien aus den Storage-Mounts.
-- Zugangsdaten werden nicht in das Repository geschrieben.
+- API- und Login-Zugangsdaten werden verschlüsselt gespeichert und nicht in das Repository geschrieben.
-- Aktive Verbindungen verwenden getrennte Konfigurations-, Secret- und State-Dateien.
+- Die API hat Vorrang, ist aber streng versionsgebunden.
-- Der Piwigo-Sync wird nur für aktivierte Connector-Verbindungen ausgeführt.
+- Benutzername/Passwort ist nur Fallback und kann dauerhaft, einmalig oder gar nicht verwendet werden.
-- Neue Connector-Alben werden privat angelegt, bevor sie regulär einsortiert oder freigegeben werden.
+- Neue Connector-Alben werden privat angelegt.
 
 ## Bekannte offene Punkte
 
-Der lokale Connector-Grundbetrieb ist abgeschlossen. Offen bleiben vor allem die nächsten Ausbauschritte:
+Der NC Connector bleibt im Entwicklungsblock `0.9.3.x`. Nach erfolgreichem API-first-Livetest folgen insbesondere:
 
+- Bereinigung und Vereinfachung der Verbindungsverwaltung im Admin-UI;
 - Remote-Nextcloud-Adapter;
-- weitere Bereinigung und Vereinfachung der Verbindungsverwaltung im Admin-UI;
+- Entscheidung über verbleibende Legacy-/Migrationshilfen;
-- endgültige Entscheidung, welche Legacy-/Migrationshilfen nach stabiler Betriebsphase noch im Plugin verbleiben sollen;
 - weitere Komfortfunktionen für Status, Diagnose und Administration.
 
 ## Repository-Fallback