# Lektionen & Erkenntnisse - 03.06.2026

## 📌 Projekt: FortuneCookie App (Ubuntu Touch 24.04 / Lomiri)

---

## 🎯 Heute erreichte Meilensteine

| Aufgabe | Status | Lösung |
|---------|--------|--------|
| Aktive Liste unten links anzeigen | ✅ | `Label` mit `currentFortuneListDescription` |
| Nur Beschreibung (ohne Name/Anzahl) | ✅ | Eigene Property für reine Beschreibung |
| Listen-Beschreibung auf Icon-Höhe | ✅ | `verticalCenter: musicButton.verticalCenter` |
| Audio-Button verkleinern | ✅ | 10×10 gu → 8×8 gu, Font: xxx-large → xx-large |
| Lautstärke-Regelung (SW) | ❌ | **Funktioniert nicht in Ubuntu Touch** |
| Lautstärke-Anpassung (HW) | ✅ | `chinese_music.mp3` per FFmpeg auf 30% reduziert |
| Alle Listen ≥100 Sprüche | ✅ | farmer wisdom, UNfortune, sandman, famous quotes ergänzt |
| Neue Listen hinzufügen | ✅ | sandman (Bettgehzeit!), famous quotes (Berühmte Zitate) |
| Autoren zu Zitaten | ✅ | Format: "Zitat - Autor" |

---

## 🔧 Technische Erkenntnisse

### 1. **Lomiri/Ubuntu Touch - Medienwiedergabe**

| Problem | Erkenntnis | Lösung |
|---------|-----------|--------|
| `MediaPlayer.volume` wirkt nicht | QtMultimedia Volume-Property wird in Ubuntu Touch ignoriert | **Dateiebene anpassen** mit FFmpeg |
| PyOtherSide sync-Aufrufe blockieren UI | Deadlock-Gefahr | **Asynchrone** `py.call()` verwenden |
| Lautstärke-Slider ohne Effekt | Plattform-Limitierung | Slider entfernt, feste Volumes |

**FFmpeg-Befehl zum Lautstärke reduzieren:**
```bash
ffmpeg -i input.mp3 -af "volume=0.3" -y output.mp3
```

### 2. **Qt/QML Best Practices**

#### ✅ Funktioniert:
```qml
// Property-Binding für automatische Synchronisation
MediaPlayer {
    volume: root.musicVolume  // Wird automatisch aktualisiert
}
```

#### ❌ Problem: Binding wird gebrochen durch:
```qml
// Direkte Zuweisung zerstört das Binding!
mediaPlayer.volume = value;  // ❌
```

#### ✅ Richtig:
```qml
// Nur die Property setzen, Binding überträgt automatisch
root.musicVolume = value;  // ✅
```

#### Anker-Positionierung:
```qml
// Vertikal zentriert mit anderem Element
Label {
    anchors {
        left: parent.left
        verticalCenter: musicButton.verticalCenter  // ✅
        leftMargin: units.gu(2)
    }
}
```

---

## 🌿 Branches-System

### Aktuelle Struktur:
```
main       → Stabil (Releases)
└── daily  → Entwicklung (aktuell)
```

### Regeln:
1. **Daily-Branch** für alle Entwicklungen nutzen
2. **Main-Branch** nur für getestete Releases
3. **Vor Merge:**
   - App testen auf Gerät
   - Alle Funktionen prüfen
   - Keine debug-Logs im Production-Code
4. **Versionierung:**
   - `manifest.json.in`: App-Version (1.0.x)
   - `fortunecookie.py`: Modul-Version (1.1.x)

### Heute genutzt:
```bash
# Im daily-branch arbeiten
git checkout daily

# Ändern, bauen, installieren
clickable build && clickable install
```

---

## 📚 Referenzquellen & Zeitersparnis

### 🔍 **Referenz-Apps studieren!**
- **metime** (Lomiri) - Gute Beispiele für:
  - UI/UX-Patterns
  - MediaPlayer-Integration
  - Einstellungen-Handling
  - Python-QML-Kommunikation

### ⏱️ **Fehlerbehebung beschleunigen:**
1. **Zuerst Referenz-Apps prüfen** (metime, andere Lomiri-Apps)
2. **Lomiri-Dokumentation:** https://docs.ubuntu-touch.io/
3. **QtMultimedia Limitations:** Ubuntu Touch hat Einschränkungen bei Volume-Control
4. **PyOtherSide:** Immer asynchron arbeiten

### 📖 **Wichtige Dateien im Projekt:**
```
qml/Main.qml              # Haupt-UI
src/fortunecookie.py      # Python-Backend
assets/fortunes/*.json     # Spruchlisten
manifest.json.in          # App-Metadaten
fortunecookie.apparmor    # Berechtigungen
```

---

## 📁 Dateistruktur FortuneCookie

```
fortunecookie-neu/
├── testing/                      # Entwicklungszweig
│   ├── qml/
│   │   └── Main.qml            # Haupt-UI (Navigation, MediaPlayer, Einstellungen)
│   ├── src/
│   │   └── fortunecookie.py    # Backend (Sprüche laden, Einstellungen)
│   ├── assets/
│   │   ├── fortunes/            # Spruchlisten
│   │   │   ├── fortune.json         (140 Sprüche)
│   │   │   ├── farmer wisdom.json   (114 Sprüche)
│   │   │   ├── UNfortune.json        (100 Sprüche)
│   │   │   ├── sandman.json          (100 Sprüche - Bettgehzeit!)
│   │   │   └── famous quotes.json    (121 Sprüche - Berühmte Zitate)
│   │   ├── chinese_music.mp3    # Hintergrundmusik (30% Lautstärke)
│   │   └── cookie_crack.mp3     # Knack-Geräusch (100% Lautstärke)
│   └── manifest.json.in         # App-Version: 1.0.8
└── build/                       # Build-Output
```

---

## 🎓 Gelernte Lektionen

### 1. **Ubuntu Touch spezifisch**
- MediaPlayer.volume wird **ignoriert** → Lautstärke in Datei anpassen
- PyOtherSide: **Immer async** (`py.call()`, nicht `py.syncCall()`)
- UI-Elemente: `units.gu()` für konsistente Größen
- Icons: Emoji-Shortcodes funktionieren (z. B. `\uD83D\uDD0A` = 🎆)

### 2. **QML Best Practices**
- **Property-Bindings** nutzen statt manueller Zuweisungen
- **Anker** statt absoluter Positionen
- **Component.onCompleted** mit `Qt.callLater()` für verzögerte Initialisierung
- **Visible vs. Opacity:** `visible: false` entfernt Element komplett

### 3. **Python Backend**
- **Settings speichern:** `save_setting()` / `load_setting()`
- **JSON-Listen laden:** Automatisch aus `assets/fortunes/`
- **AVAILABLE_FORTUNE_LISTS** muss alle Listen enthalten

### 4. **Projektmanagement**
- **Referenz-Apps vor Implementierung prüfen** (spart Stunden!)
- **Branches diszipliniert nutzen** (daily für Entwicklung)
- **Kleine, testbare Änderungen** statt großer Refactorings
- **Fehler dokumentieren** für zukünftige Referenz

---

## 🚀 Empfehlungen für zukünftige Sessions

### ✅ DO:
- [ ] Vor Implementierung: Referenz-Apps (metime) prüfen
- [ ] QtMultimedia-Limitations in Ubuntu Touch beachten
- [ ] Immer im **daily-branch** arbeiten
- [ ] Änderungen in kleinen Schritten testen
- [ ] FFmpeg für Audio-Bearbeitung nutzen
- [ ] Property-Bindings statt direkter Zuweisungen

### ❌ DON'T:
- [ ] `MediaPlayer.volume` für Lautstärke-Regelung erwarten
- [ ] Sync PyOtherSide-Aufrufe in Timern
- [ ] Direkte MediaPlayer-Property-Zuweisungen (bricht Bindings)
- [ ] Main-Branch für Entwicklung nutzen
- [ ] Ohne Test auf Gerät deployen

---

## 📊 Versionen & Änderungen

| Datum | Version (App) | Version (Modul) | Änderungen |
|-------|---------------|------------------|-----------|
| 03.06.2026 | 1.0.8 | 1.1.1 | Listen-Beschreibung, Lautstärke-Fix, neue Listen |

### Detailed Changelog:
```
1.0.8 (03.06.2026):
- FEAT: sandman-List (100 Sprüche, "Bettgehzeit!")
- FEAT: famous quotes-List (121 Zitate mit Autoren)
- FEAT: Alle Listen auf ≥100 Sprüche ergänzt
- FIX: Musik-Lautstärke via FFmpeg auf 30% reduziert
- FIX: Listen-Beschreibung vertikal zentriert mit Audio-Button
- FIX: Audio-Button verkleinert (8×8 gu)
- FIX: Lautstärke-Slider entfernt (funktioniert nicht in UT)
- REFACTOR: Property-Bindings für MediaPlayer.volume
```

---

## 🔗 Nützliche Links

- [Lomiri Documentation](https://docs.ubuntu-touch.io/)
- [QtMultimedia Documentation](https://doc.qt.io/qt-5/qtmultimedia-index.html)
- [PyOtherSide GitHub](https://github.com/thp/pyotherside)
- [Ubuntu Touch Forum](https://forums.ubports.com/)

---

*Dokument erstellt: 03.06.2026 | Letzte Aktualisierung: 03.06.2026*