docs: massive restructuring of documentation, development guides and agent playbooks

2026-06-15 12:54:38 +02:00
parent e4988b4397
commit ce63303b2c
686 changed files with 45423 additions and 319 deletions
@@ -0,0 +1,57 @@
+---
+type: Journal
+status: COMPLETED
+owner: Curator
+date: 2026-01-26
+participants:
+  - Lead Architect
+  - DevOps Engineer
+  - QA Specialist
+  - Curator
+---
+
+# Session Log: 26. Jänner 2026
+
+## Zielsetzung
+Stabilisierung der Web-Applikation (Wasm/JS) und Behebung von Datenbank-Initialisierungsfehlern (`WebWorkerException`) im Browser.
+
+## Durchgeführte Arbeiten
+
+### 1. Web-App Datenbank (SQLDelight & Wasm)
+*   **Problem:** Die Web-App startete nicht mit einer `WebWorkerException`. Ursache war, dass der Web Worker (`sqlite.worker.js`) und die zugehörige WASM-Datei (`sqlite3.wasm`) vom Browser nicht gefunden oder falsch geladen wurden.
+*   **Lösungsversuche:**
+    *   Aktivierung des Wasm-Targets (revertiert, da zu viele Folgefehler).
+    *   Anpassung der Gradle-Tasks (`copySqliteAssetsToWebpackSource`, `copySqliteAssetsToDist`), um Assets korrekt zu kopieren.
+    *   Anpassung des Workers (`sqlite.worker.js`) für manuelles Laden der WASM-Datei via `fetch`.
+    *   **Webpack-Hacks:** Umfangreiche Anpassungen in `webpack.config.d/ignore-sqlite-wasm.js`, um Webpack daran zu hindern, `sqlite3.wasm` als Modul zu parsen (was fehlschlug) und stattdessen auf ein `dummy.js` umzuleiten.
+*   **Aktueller Stand:**
+    *   Der Build schlägt noch fehl mit `export 'default' ... was not found`.
+    *   Die Strategie ist: Webpack sieht `dummy.js` (als Ersatz für `sqlite3.mjs` und `sqlite3.wasm`), während der Worker zur Laufzeit die echte `sqlite3.wasm` Datei manuell lädt.
+    *   `dummy.js` muss so angepasst werden, dass es einen korrekten Default-Export bereitstellt.
+
+### 2. Unit Tests (Ping Feature)
+*   **Problem:** `PingViewModelTest` schlug fehl, da Fehlerzustände nicht korrekt im UI-State gesetzt wurden.
+*   **Lösung:** `PingViewModel` angepasst, um `errorMessage` im State bei Exceptions korrekt zu setzen. Tests sind wieder grün.
+
+### 3. Gradle Build Optimierung
+*   **Problem:** Zirkuläre Abhängigkeiten zwischen Copy-Tasks und Webpack-Tasks.
+*   **Lösung:** Task-Reihenfolge in `build.gradle.kts` korrigiert (`mustRunAfter` statt `dependsOn` wo nötig).
+
+## Offene Punkte & Nächste Schritte
+
+1.  **Web-App Build Fix:**
+    *   `dummy.js` muss einen Default-Export (`export default function...`) bereitstellen, um den Import in `sqlite.worker.js` zu befriedigen.
+    *   Danach sollte der Webpack-Build durchlaufen.
+    *   Laufzeit-Test im Browser: Prüfen, ob der manuelle `fetch` im Worker funktioniert und die DB initialisiert wird.
+
+2.  **Wasm-Strategie:**
+    *   Langfristig sollte auf natives Wasm-Target umgestellt werden, sobald die Toolchain (Kotlin/Wasm + SQLDelight) stabiler ist. Aktuell ist der JS-Interop-Weg mit Webpack-Hacks notwendig.
+
+3.  **Integration Test:**
+    *   Sobald die Web-App läuft: Vollständiger Durchstich (Login -> Ping -> DB Sync) im Browser testen.
+
+## Technische Erkenntnisse
+*   **Webpack & Wasm:** Webpack 5 tut sich schwer mit dynamischen `require`-Aufrufen in Libraries wie `sqlite-wasm`, wenn diese nicht explizit als `externals` oder via `NormalModuleReplacementPlugin` behandelt werden.
+*   **SQLDelight im Browser:** Die Kombination aus OPFS (Origin Private File System), Web Workern und Wasm erfordert präzise Kontrolle über das Laden der Assets, die Webpack oft "wegabstrahieren" will.
+
+**Status:** 🟡 **Build Failing (Web)** / 🟢 **Tests Passing (JVM)**