From bab54eccb9dc89e90bf591a0181cbbd854ba97fa Mon Sep 17 00:00:00 2001 From: Terranom674 Date: Thu, 3 Sep 2026 18:29:41 +0200 Subject: [PATCH] Document cache worker handoff after architecture dead end --- docs/HANDOFF_2026-09-03_CACHE_WORKER.md | 111 ++++++++++++++++++++++++ 1 file changed, 111 insertions(+) create mode 100644 docs/HANDOFF_2026-09-03_CACHE_WORKER.md diff --git a/docs/HANDOFF_2026-09-03_CACHE_WORKER.md b/docs/HANDOFF_2026-09-03_CACHE_WORKER.md new file mode 100644 index 0000000..cdfde13 --- /dev/null +++ b/docs/HANDOFF_2026-09-03_CACHE_WORKER.md @@ -0,0 +1,111 @@ +# HANDOFF – Piwigo / WebDAV Cache-Worker – 2026-09-03 + +## Warum hier gestoppt wurde + +Die aktuelle Cache-Worker-Entwicklung ist in einen Architektur-/Debugging-Kreis geraten. Der beobachtete produktive Zustand ist eindeutig falsch: Nach dem Leeren des Bildcaches meldet der manuelle Cache-Aufbau praktisch sofort "fertig", obwohl der eigentliche Piwigo-Bildcache nicht aufgebaut wurde. Weitere Patchversuche an Anzeige, Statusaggregation oder Legacy-Worker-Zählung würden den Fehler nur weiter überdecken. + +Ab hier **nicht weiterpatchen**, bevor der reale Ausführungspfad von Button bis Piwigo-Derivaterzeugung vollständig nachvollzogen ist. + +## Gesicherte Architekturvorgaben + +- Nextcloud ist die autoritative Quelle der Originalbilder. +- Piwigo arbeitet produktiv mit einem Shadow-Tree und 1x1-Placeholdern. +- Der Worker darf Piwigo nicht nachbauen und selbst keine Derivate rendern. +- Richtiger Ablauf: Worker erkennt Arbeit -> Original temporär materialisieren -> Piwigo nativen Derivatpfad aufrufen -> Ergebnis prüfen -> Original wieder entfernen / Placeholder restaurieren. +- Piwigo allein bestimmt Dimensionen, Crop, Sharpening, Wasserzeichen, Qualität, Format und Cachepfad. +- On-Demand bleibt Fallback. +- Materialisierung erfolgt batchweise, Standard 10 Originale pro Batch. +- Stage 1 vor Stage 2; neue Sync-Arbeit darf Stage 2 zwischen Batches priorisieren. +- Connector/Shadow-Tree bleibt Wahrheit darüber, welche Quellen existieren. + +## Neuer Quellenindex – Konzept weiterhin sinnvoll + +Die Trennung des Worker-Entscheidungszustands vom Piwigo-Cache ist weiterhin sinnvoll: + +- eigener kleiner Quellenindex je WebDAV-Verbindung +- Identität primär über `fileid`, Fallback Root/Pfad +- Vergleich über `etag`, Dateigröße, MIME/Format, Pfad, Breite/Höhe +- Quelle neu/geändert -> Worker darf Piwigo beauftragen +- Quelle unverändert -> normaler periodischer Lauf tut nichts +- gelöschte Quelle -> beim Abgleich aus Worker-Index entfernen; eigentliche Quellenentfernung bleibt Connector/Shadow-Tree-Aufgabe +- manueller Full-Rebuild darf den Quellenindex bewusst ignorieren und alle aktuellen Quellen erneut an Piwigo reichen + +Datei dafür aktuell: +`include/webdav_source_index.inc.php` + +## Aktueller problematischer Stand + +### Version + +Aktuell zuletzt auf `0.9.7.1.16` erhöht. + +### Relevante Dateien + +- `runtime/lib/webdav-cache-warmup.php` +- `runtime/webdav-warmup-dispatch.php` +- `include/webdav_source_index.inc.php` +- `include/webdav_warmup_settings.inc.php` +- `main-cache-build.php` +- `main-cache-status.php` +- `tools/image_cache.inc.php` +- `template/admin.tpl` +- `include/tool_registry.inc.php` + +### Letzte Architekturänderungen + +1. Legacy `main-cache-build.php` zählt WebDAV-Bilder nicht mehr als normale lokale Cachearbeit. +2. Eigener WebDAV-Quellenindex wurde eingeführt. +3. Warmup-Auswahl wurde auf diesen Quellenindex umgestellt. +4. Kombinierter Admin-Button startet lokalen Piwigo-Teil plus WebDAV-Rebuild. +5. Statusanzeige wurde zusammengeführt. +6. Bei reiner WebDAV-Installation sollte der lokale Legacy-Worker gar nicht mehr gestartet werden. + +Trotzdem beobachtet der Nutzer nach Cache-Leeren weiterhin einen praktisch sofort fertigen Aufbau. Das beweist: **Der tatsächliche WebDAV-Rebuild-Pfad erzeugt die erwarteten Piwigo-Derivate nicht bzw. läuft nicht so, wie die Architektur es annimmt.** + +## Wichtige letzte Commits + +- `ac6353b050cdf30db79ab20716e66e6a6c841abb` – eigener WebDAV-Quellenindex +- `6783974c7dfab9d11a0f1e43419de84e92141fd5` – Warmup auf Quellenindex umgestellt +- `9f80c4aa974da01d606292c479487bce13b403fa` – Quelle erst nach beiden Stufen vollständig +- `030d0c1be7ef8cafdab3f3d46e01ec90d5fd3bdc` – kombinierte Statusanzeige +- `e831301650ee2a80c969e6c9b783d37a3c4f593d` – Syntaxkorrektur Status +- `479cdbc4734605db3861908286426c76468d12a3` – Quellenindex-Baseline blockiert Aktivierung nicht mehr +- `116b710d5d35311eeae261e5ae3cf405c5f51ce3` – Legacy-Worker bei reiner WebDAV-Installation nicht mehr starten +- `81e0a9e185a14c08230b4f8fa0f36809c5b2b9a7` – Version 0.9.7.1.16 + +## NICHT weiter tun + +- Keine weiteren UI-/Statuspatches, bevor der echte Workerpfad bewiesen ist. +- Nicht wieder Cache-Dateiexistenz als Quelle für "neu/geändert" verwenden. +- Nicht den Placeholder selbst rendern. +- Nicht den Legacy-Full-Cache-Builder für WebDAV reaktivieren. +- Nicht weiter an Symptomen wie 45-Sekunden-Stall, "übersprungen" oder Prozentanzeige herumoptimieren. + +## Nächster Einstieg – zwingend + +Der nächste Chat/Entwickler soll **zuerst den tatsächlichen Rebuild-Ausführungspfad beweisen**: + +1. Admin-Handler `image_cache_build` verfolgen. +2. `bratonien_tools_start_combined_image_cache_build()` verfolgen. +3. Start des `runtime/webdav-warmup-dispatch.php --mode=rebuild` beweisen. +4. Verifizieren, dass Dispatcher die aktive WebDAV-Verbindung findet. +5. Verifizieren, dass `runtime/lib/webdav-cache-warmup.php --mode=rebuild` wirklich gestartet wird. +6. Verifizieren, wie viele Quellen `bratonien_tools_cache_warmup_scan()` tatsächlich liefert. +7. Verifizieren, wie viele Varianten Stage 1 und Stage 2 pro Bild tatsächlich liefern. +8. Erst an **einem einzigen Bild** nachweisen: + - Original wird aus Nextcloud heruntergeladen. + - Placeholder wird korrekt gesichert. + - Original wird am produktiven Quellpfad eingesetzt. + - `piwigo-derivative-call.php` ruft wirklich Piwigos nativen `i.php`-Pfad auf. + - Piwigo erzeugt tatsächlich eine konkrete Datei unter `_data/i`. + - strikter Validator erkennt sie als gültig. + - Placeholder wird exakt restauriert. +9. Erst wenn dieser Ein-Bild-Test nachweislich funktioniert, Batchbetrieb und UI wieder anfassen. + +## Entscheidender Verdacht + +Der derzeit wichtigste Verdacht ist **nicht mehr die Anzeige**, sondern dass der Rebuild intern sehr früh keine Arbeit findet oder Piwigo über den aufgerufenen `i.php`-Pfad keine Derivate erzeugt, obwohl der Worker dies erwartet. Genau diese Stelle muss mit realem Lauf/Log belegt werden. + +## Produktionsvalidierung + +Von ChatGPT wurde kein echter Serverlauf durchgeführt. Ohne reale Serverausgaben darf nicht behauptet werden, dass Pfadaudit, Materialisierung, Piwigo-Aufruf oder Cache-Erzeugung funktionieren.