Update current NC Connector development status

CURRENT_STATUS.md

@@ -4,43 +4,51 @@ Stand: 17.08.2026
 
 ## Plugin
 
-- Aktuelle Plugin-Version: **0.9.3.14**
+- Aktuelle Plugin-Version: **0.9.3.16**
 - 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.14`
+Der lokale NC Connector ist für den aktuellen Bratonien-Einsatz inzwischen End-to-End funktionsfähig.
-- Einzeldateifreigaben im Galerie-Root werden nicht mehr ausschließlich der klassischen Piwigo-Dateisynchronisation überlassen.
+
-- Neuer Webservice `bratonien.nc.syncOrphans` registriert direkte Root-Dateien als echte Piwigo-Orphans ohne Album-Zuordnung.
+Erfolgreich umgesetzt und getestet:
-- `runtime/lib/piwigo-db-sync.pl` führt weiterhin zuerst den normalen Piwigo-Dateisync für physische Alben aus und synchronisiert danach die Root-Orphans produktiv über den neuen Webservice.
+
-- Entfernte Root-Freigaben werden aus der Piwigo-Datenbank entfernt, ohne das Nextcloud-Original zu löschen.
+- Nextcloud-Freigaben vom Typ `folder` und `file` werden aus der Source-View gelesen.
-- Der bestehende Webservice `bratonien.nc.sync` bleibt weiterhin der read-only Paritätstest für den vollständigen klassischen Sync.
+- Das Manifest führt beide Freigabetypen korrekt.
-- Die in `0.9.3.12` ergänzte Share-Fingerprint-Prüfung des Activity-Gates bleibt aktiv.
+- Ordnerfreigaben werden als Verzeichnisbaum im Shadow Tree gespiegelt.
-- `runtime/sync.sh` bleibt mit älteren `connection-*.conf` kompatibel und verwendet bei fehlenden Werten automatisch `piwigo_showcase_activity` bzw. `piwigo_showcase_sources`.
+- Einzeldateifreigaben werden als Symlink direkt im Galerie-Root angelegt.
+- Einzeldateien werden anschließend als echte Piwigo-Orphans ohne Albumzuordnung registriert.
+- Entfernte Einzeldateifreigaben werden beim normalen Connector-Lauf aus dem Shadow Tree und aus Piwigo entfernt.
+- Das Nextcloud-Original bleibt bei allen Löschvorgängen unangetastet.
+- Der normale Connector-Lauf führt klassischen Piwigo-Dateisync und Orphan-Abgleich automatisch hintereinander aus.
+- 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.
 
 ## 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.
+- Piwigo erhält nur die für die Galerie 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`.
-- Shadow Tree: Verzeichnisse und Symlinks, keine Kopien der Originaldateien.
+- Der Shadow Tree enthält Verzeichnisse und Symlinks, keine Kopien der Originaldateien.
+- Alle aktivierten Verbindungen werden über `runtime/run-all.sh` gemeinsam verarbeitet.
 
 ## Nextcloud-Freigabemodell
 
-Für Showcase gelten zwei Fälle:
+Der Connector unterstützt zwei Fälle:
 
 1. komplette Ordner werden geteilt;
-2. einzelne Bilder werden direkt in das Nextcloud-Stammverzeichnis geteilt.
+2. einzelne Bilder werden direkt geteilt.
 
-Der Connector unterstützt `folder` und `file`:
+Verarbeitung:
 
-- Ordner werden weiterhin als Verzeichnisbaum gespiegelt.
+- `folder` -> Verzeichnisstruktur spiegeln und über Piwigos klassische Dateisynchronisierung als physische Albumstruktur einlesen;
-- Einzeldateien werden direkt als Symlink im Galerie-/Shadow-Root angelegt.
+- `file` -> Symlink direkt im Galerie-Root und anschließende Registrierung als Piwigo-Orphan.
-- Für einzelne Dateien wird **kein künstlicher Unterordner** erzeugt.
+
+Für einzelne Dateien wird kein künstlicher Unterordner erzeugt.
 
 ## Manifest / Shadow Tree
 
@@ -49,7 +57,9 @@ Der Connector unterstützt `folder` und `file`:
 - 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/Verzeichnis bestimmt. Das Manifest führt danach in beiden Fällen vier Spalten:
+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`
 
@@ -58,61 +68,84 @@ Bei einer Legacy-View wird der Typ nach Auflösung des Storage-Pfads über Datei
 - `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.
+
+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
 
 ### Physische Alben
 
-Der produktive Fallback benutzt weiterhin den bestehenden Admin-Sync über `runtime/lib/piwigo-db-sync.pl` für normale Verzeichnisse und 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.
+
+Connector-getriggerte Neuanlagen werden dabei mit privatem Standardstatus verarbeitet.
 
 ### Root-Dateien / Orphans
 
-Piwigos klassische Dateisynchronisation kann Dateien direkt unter `galleries/` nicht als neues Element einem physischen Album zuordnen. Deshalb verarbeitet `bratonien.nc.syncOrphans` ausschließlich direkte Dateien im konfigurierten Galerie-Root.
+Piwigos klassische Dateisynchronisation kann Dateien direkt unter dem Galerie-Root nicht als neues Element einem physischen Album zuordnen.
+
+Deshalb verarbeitet `bratonien.nc.syncOrphans` diese Dateien separat.
 
 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 die vorhandenen Piwigo-Funktionen aktualisiert;
+- Metadaten und Piwigo-Aktivität werden über vorhandene Piwigo-Funktionen aktualisiert;
-- die Datei erscheint damit im Batch Manager unter `With no album / Orphans`.
+- 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 jetzt zwei eigene Webservice-Endpunkte:
+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 ausschließlich für Piwigo **16.4.0** freigegeben.
+Beide Wege sind aktuell für Piwigo **16.4.0** freigegeben.
 
-## Aktuell offener Test
+## Erfolgreiche Live-Tests
 
-Die Einzeldateifreigabe `DSC1461-Enhanced-NR (1).jpg` wird bereits korrekt als `file` aus Nextcloud gelesen und als Symlink direkt im Galerie-Root angelegt.
+Bestätigt wurden:
 
-Nach Installation von `0.9.3.14` muss geprüft werden:
+- Ordnerfreigaben werden korrekt eingelesen.
+- Eine einzelne Nextcloud-Dateifreigabe wurde im Manifest als `file` erkannt.
+- Der zugehörige Symlink wurde direkt im Galerie-Root erzeugt.
+- Die Orphan-Simulation erkannte die Datei als `new_orphans = 1` ohne Datenbankschreibzugriff.
+- Der produktive Lauf registrierte die Datei als echtes Piwigo-Orphan.
+- 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`.
+- Der Root-Symlink wurde entfernt.
+- Ein anschließender Orphan-Abgleich fand keine Restdatei mehr.
+- Der automatische Timer kann wieder regulär laufen.
 
-1. Simulation von `bratonien.nc.syncOrphans` meldet `new_orphans = 1`;
+## Sicherheit / Betriebsmodell
-2. normaler Connector-Lauf registriert das Bild produktiv;
-3. danach meldet die Orphan-Simulation `new_orphans = 0` und `registered_orphans = 1`;
-4. das Bild erscheint im Piwigo Batch Manager unter `With no album / Orphans`;
-5. das Entfernen der Nextcloud-Freigabe entfernt später nur den Piwigo-Eintrag, nicht das Original.
 
-## Testmodus / Sicherheit
+- Nextcloud bleibt Eigentümer der Originaldateien.
-
+- Der Connector löscht keine Originaldateien aus den Storage-Mounts.
-- Der produktive Timer bleibt während der kontrollierten Tests ausgeschaltet.
+- Zugangsdaten werden nicht in das Repository geschrieben.
-- Für reine Shadow-Tree-Tests kann `PIWIGO_SYNC_OVERRIDE=0` verwendet werden.
+- Aktive Verbindungen verwenden getrennte Konfigurations-, Secret- und State-Dateien.
-- Der verwendete Piwigo-API-Key ist ausschließlich ein temporärer Entwicklungs-/Test-Key und wird nicht Bestandteil der produktiven Konfiguration.
+- Der Piwigo-Sync wird nur für aktivierte Connector-Verbindungen ausgeführt.
+- Neue Connector-Alben werden privat angelegt, bevor sie regulär einsortiert oder freigegeben werden.
 
 ## Bekannte offene Punkte
 
-- finaler End-to-End-Test der neuen Orphan-Synchronisation;
+Der lokale Connector-Grundbetrieb ist abgeschlossen. Offen bleiben vor allem die nächsten Ausbauschritte:
-- danach Löschtest einer Einzeldateifreigabe;
+
-- produktiven vollständigen API-Sync erst nach erfolgreichen Paritätstests aktivieren;
+- Remote-Nextcloud-Adapter;
-- Admin-Fallback mit temporären bzw. optional dauerhaft gespeicherten Zugangsdaten fertigstellen;
+- weitere Bereinigung und Vereinfachung der Verbindungsverwaltung im Admin-UI;
-- Remote-Nextcloud-Adapter ist noch nicht umgesetzt;
+- endgültige Entscheidung, welche Legacy-/Migrationshilfen nach stabiler Betriebsphase noch im Plugin verbleiben sollen;
-- UI und Restpunkte der Verbindungsverwaltung werden nach Abschluss der aktuellen technischen Tests weiter bereinigt.
+- weitere Komfortfunktionen für Status, Diagnose und Administration.
 
 ## Repository-Fallback