fortunecookie/README.md

# 📁 START-UT-DEV Framework 1.7 - TEMPLATES

**Version:** 1.7
**Stand:** 30.05.2026
**Maintainer:** darklithium <dev@darklithium.de>
**Validiert durch:** referenz-app (metime-basiert) ✅

---

## 🎯 ZWECK

Dieses Verzeichnis enthält **fertige Templates** für Ubuntu Touch App-Entwicklung mit:
- **QML** (UI)
- **Python** (Backend via PyOtherSide)
- **pure-qml-cmake** (Builder)

**Alle Templates sind validiert** durch die erfolgreiche referenz-app-Implementierung.

---

## 📁 STRUKTUR

```
TEMPLATES/
├── README.md              # Diese Datei
├── CMakeLists.txt         # CMake-Konfiguration (Standard 1.7)
├── clickable.yaml         # Clickable-Konfiguration (Standard 1.7)
├── manifest.json.in       # App-Manifest Template
├── app.apparmor           # AppArmor-Profil Template
├── app.desktop.in         # Desktop-Datei Template
├── python_module_template.py  # Python-Modul Template
├── qml_main_template.qml  # QML Hauptdatei Template
└── .git/                  # Git-Hooks (Symlinks zu /DEV/git/hooks/)
    └── hooks/
        ├── pre-commit     # → /home/chrischi/DEV/git/hooks/pre-commit
        └── commit-msg     # → /home/chrischi/DEV/git/hooks/commit-msg
```

---

## 🚀 SCHNELLSTART: NEUE APP ERSTELLEN

### 1. Projektverzeichnis erstellen
```bash
mkdir -p /home/chrischi/DEV/UT/meine-app/{assets,qml,src}
cd /home/chrischi/DEV/UT/meine-app
```

### 2. Framework einbinden (Symlink)
```bash
ln -s /home/chrischi/DEV/tools/START-UT-DEV/1.7 START-UT-DEV
```

### 3. Templates kopieren & anpassen
```bash
# CMake & Clickable
cp START-UT-DEV/1.7/TEMPLATES/CMakeLists.txt .
cp START-UT-DEV/1.7/TEMPLATES/clickable.yaml .

# Manifest & Desktop
cp START-UT-DEV/1.7/TEMPLATES/manifest.json.in .
cp START-UT-DEV/1.7/TEMPLATES/app.apparmor meine-app.apparmor
cp START-UT-DEV/1.7/TEMPLATES/app.desktop.in meine-app.desktop.in

# Python & QML
cp START-UT-DEV/1.7/TEMPLATES/python_module_template.py src/meine-app.py
cp START-UT-DEV/1.7/TEMPLATES/qml_main_template.qml qml/Main.qml

# Assets (Beispiel-Icon)
cp START-UT-DEV/1.7/TEMPLATES/../ASSETS/logo.svg assets/
```

### 4. Platzhalter ersetzen
**In allen Dateien `<app-name>` durch `meine-app` ersetzen:**
```bash
# Schnell-Ersetzung (Vorsicht: prüfe alle Dateien manuell!)
find . -type f -exec sed -i 's/<app-name>/meine-app/g' {} \;
sed -i 's/<App-Name>/Meine App/g' meine-app.desktop.in manifest.json.in
```

### 5. Git einrichten (narrensicher)
```bash
# Git initialisieren
git init

# Hooks installieren (Symlinks!)
mkdir -p .git/hooks
cp -s /home/chrischi/DEV/git/hooks/pre-commit .git/hooks/
cp -s /home/chrischi/DEV/git/hooks/commit-msg .git/hooks/
chmod +x .git/hooks/*

# git-helper kopieren
cp /home/chrischi/DEV/git/git-helper.sh .
chmod +x git-helper.sh
```

### 6. Erstes Commit
```bash
./git-helper.sh commit 'feat: initiale Projektstruktur'
```

### 7. Build & Test
```bash
# Desktop-Test
qmlscene qml/Main.qml

# Clickable Build (für alle Architekturen)
clickable build --arch all

# Installation in QEMU
clickable install
```

---

## 📝 TEMPLATES IM DETAIL

### 📄 CMakeLists.txt
**Zweck:** Build-Konfiguration für pure-qml-cmake

**Wichtige Punkte (1.7):**
- `CMAKE_AUTOMOC ON` (für Qt5)
- Architektur-Triplet via `dpkg-architecture`
- `PROJECT_NAME` und `FULL_PROJECT_NAME` anpassen
- `DATA_DIR /` (Root für Click-Container)

**Anpassungen:**
- `<app-name>` durch deinen App-Namen ersetzen

---

### 📄 clickable.yaml
**Zweck:** Clickable Build-Konfiguration

**Standard 1.7:**
```yaml
clickable_minimum_required: 8.8.0
builder: pure-qml-cmake
kill: qmlscene
```

**Für Apps mit nativem Code:**
- `builder: cmake` oder `builder: qmake`
- `kill: <app-name>`

---

### 📄 manifest.json.in
**Zweck:** App-Manifest für Click-Pakete

**Wichtige Felder (1.7):**
- `name`: `<app-name>.darklithium` (Format: appname.maintainer)
- `maintainer`: `"Vorname Nachname <email>"` (OHNE spitze Klammern um den Namen!)
- `architecture`: `"all"` (für pure-qml-cmake)
- `framework`: `"ubuntu-sdk-20.04"`

**⚠️ WICHTIG:** Nur Standardfelder verwenden! Keine `permissions`, `policy_groups`, `read_path`, `write_path` (schlagen Validierung fehl).

---

### 📄 app.apparmor
**Zweck:** AppArmor-Sicherheitsprofil

**Standard 1.7:**
```json
{
    "policy_version": 20.04,
    "policy_groups": ["networking"]
}
```

**Verfügbare Policy-Gruppen:**
- `networking` (HTTP, etc.)
- `content_exchange_source` (Dateiaustausch)
- `video` (Video-Wiedergabe)
- `pulseaudio` (Audio)
- `bluetooth` (Bluetooth)
- `location` (Standort)
- `contacts` (Kontakte)
- `calendar` (Kalender)
- `camera` (Kamera)
- `sensors` (Sensoren)

---

### 📄 app.desktop.in
**Zweck:** Desktop-Datei für Lomiri

**Wichtige Einträge (1.7):**
- `Exec=qmlscene %U qml/Main.qml` (für pure-QML-Apps)
- `X-Lomiri-Touch=true` (für Ubuntu Touch)
- `Icon=assets/logo.svg` (Standard)
- `X-Ubuntu-Applications=<app-name>` (ohne .desktop Endung)

---

### 🐍 python_module_template.py
**Zweck:** Python-Backend für PyOtherSide

**Wichtige Punkte (1.7):**
- **KEINE** dbus-Importe (PyOtherSide-Kompatibilität)
- **KEINE** Top-Level print() Statements
- **KEINE** Top-Level Code-Ausführung
- Plattform-Erkennung via `platform.machine()`
- **Ein Modul reicht** für 90% der Apps

**Beispiel-Funktionen:**
- `get_platform()` → "arm64" oder "amd64"
- `get_status_text()` → Status für UI
- `on_button_click()` → Button-Handler
- `get_data_dir()` → Persistentes Datenverzeichnis

---

### 🎨 qml_main_template.qml
**Zweck:** QML-Hauptdatei

**Wichtige Punkte (1.7):**
- **Imports:**
  ```qml
  import QtQuick 2.7
  import QtQuick.Layouts 1.3  // NEU 1.7!
  import Lomiri.Components 1.3
  import Lomiri.Components.Popups 1.3
  import io.thp.pyotherside 1.4
  ```
- **fontSize:** **Immer als STRING** (`"large"`, `"x-large"`, `"medium"`) - nicht units.sp()
- **Layouts:** QtQuick.Layouts 1.3 für ColumnLayout, RowLayout
- **PyOtherSide:** `Qt.resolvedUrl("../src")` **FUNKTIONIERT!**
- **Button-Größen:** 20x8 GU (200x80 DP) für Touch-Optimierung
- **PageFooter:** **Existent NICHT** in Lomiri.Components 1.3 → als Label implementieren

---

## 🔗 GIT-HOOKS (SYMLINKS)

Die Hooks in `.git/hooks/` sind **Symlinks** zu `/home/chrischi/DEV/git/hooks/`:

```
.git/hooks/
├── pre-commit  → /home/chrischi/DEV/git/hooks/pre-commit
└── commit-msg  → /home/chrischi/DEV/git/hooks/commit-msg
```

### Vorteile von Symlinks:
1. **Zentrale Updates:** Änderungen an den Hooks in `/DEV/git/hooks/` gelten sofort für alle Projekte
2. **Konsistenz:** Alle Projekte nutzen dieselben Hooks
3. **Wartung:** Nur eine Stelle zu pflegen

### Hooks im Detail:

#### pre-commit
Prüft vor jedem Commit:
- ✅ Branch-Naming (nur stable/testing/feature/bugfix/hotfix/release)
- ✅ Dateigrößen (max. 1MB)
- ✅ Sensible Daten (Passwörter, Keys, Tokens)
- ✅ Code-Style (kein Trailing Whitespace, LF Line Endings)

#### commit-msg
Prüft Commit-Messages:
- ✅ Subject-Länge (max. 72 Zeichen)
- ✅ Format: `<typ>: <beschreibung>`
- ✅ Typen: feat/fix/docs/style/refactor/test/chore/revert/perf/build/ci/WIP
- ✅ Beschreibung muss vorhanden sein

---

## 📊 PROJEKTSTRUKTUR (STANDARD 1.7)

```
meine-app/
├── CMakeLists.txt          # Build-Konfiguration
├── clickable.yaml          # Clickable-Konfiguration
├── manifest.json.in        # App-Manifest
├── meine-app.apparmor      # AppArmor-Profil
├── meine-app.desktop.in    # Desktop-Datei
├── .git/                   # Git-Repository
│   └── hooks/              # Git-Hooks (Symlinks)
│       ├── pre-commit
│       └── commit-msg
├── START-UT-DEV/           # Framework (Symlink)
│   └── 1.7/
│       ├── TEMPLATES/      # Templates
│       └── TOOLS/          # Tools (git-helper.sh)
├── assets/                 # Icons, Bilder
│   └── logo.svg           # App-Icon
├── qml/                    # QML-Dateien
│   └── Main.qml            # Haupteinstiegspunkt
└── src/                    # Python-Module
    └── meine-app.py        # Python-Backend
```

---

## 🧪 TESTING

### Desktop-Test (schnell)
```bash
qmlscene qml/Main.qml
```

### Clickable Build & Test
```bash
# Build für alle Architekturen
clickable build --arch all

# Installation in QEMU
clickable install

# Log prüfen
clickable log
```

### Git Workflow Test
```bash
# Feature-Branch erstellen
./git-helper.sh new-feature test-funktion

# Änderungen machen...

# Commit (wird durch Hooks validiert)
./git-helper.sh commit 'feat: Testfunktion hinzugefügt'

# Push
./git-helper.sh push
```

---

## 📚 BEST PRACTICES (1.7)

### ✅ DO:
- **Ein Python-Modul** für einfache Apps (modulare Trennung ist optional)
- **Qt.resolvedUrl("../src")** für PyOtherSide-Imports
- **fontSize als STRING** verwenden
- **Button-Größen:** 20x8 GU für Touch
- **Git-Hooks nutzen** (verhindern Fehler)
- **git-helper.sh nutzen** (einfache Befehle)

### ❌ DON'T:
- **dbus-Importe** in Python-Modulen (PyOtherSide-Kompatibilität)
- **Absolute Pfade** für PyOtherSide-Imports
- **Top-Level Code** in Python-Modulen (wird nicht ausgeführt)
- **units.sp()** für fontSize (String-Werte bevorzugen)
- **Direkte Commits auf stable** (nur über Merge)

---

## 🔄 UPDATES

### Templates aktualisieren
Die Templates in `/DEV/tools/START-UT-DEV/1.7/TEMPLATES/` werden laufend verbessert.

**Aktualisierung für bestehendes Projekt:**
```bash
# CMakeLists.txt
cp /home/chrischi/DEV/tools/START-UT-DEV/1.7/TEMPLATES/CMakeLists.txt .

# clickable.yaml
cp /home/chrischi/DEV/tools/START-UT-DEV/1.7/TEMPLATES/clickable.yaml .

# Python-Template (neue Funktionen)
cp /home/chrischi/DEV/tools/START-UT-DEV/1.7/TEMPLATES/python_module_template.py src/meine-app.py
```

### Hooks aktualisieren
Da die Hooks **Symlinks** sind, werden sie automatisch aktualisiert, wenn die zentraler Hooks in `/DEV/git/hooks/` geändert werden.

---

## 📞 UNTERSTÜTZUNG

### Häufige Probleme

| Problem | Lösung |
|---------|--------|
| PyOtherSide-Modul wird nicht geladen | `Qt.resolvedUrl("../src")` verwenden |
| Button zu klein | 20x8 GU (200x80 DP) verwenden |
| fontSize funktioniert nicht | String-Werte (`"large"`) verwenden |
| Git-Hook blockiert Commit | `git commit --no-verify` (nur für Ausnahmen!) |
| PageFooter nicht verfügbar | Als Label implementieren |

### Referenz-App
- **Pfad:** `/home/chrischi/DEV/UT/referenz-app/`
- **Status:** ✅ ERFOLGREICH UMGESETZT
- **Dokumentation:** `IMPLEMENTATION.md`

### Manifest
- **Pfad:** `/home/chrischi/DEV/manifest.holy/manifest.holy`
- **Aktueller Stand:** Python/QML-Standards 1.7

---

**Letzte Aktualisierung:** 30.05.2026
**Version:** 1.7
**Maintainer:** darklithium <dev@darklithium.de>