Zum Inhalt springen
`CTRL K`

Dokumentation
Troubleshooting

# Troubleshooting

Typische Probleme und Lösungen. Wenn dein Problem nicht dabei ist → Issue auf Gitea
.

## App startet nicht

### “Rapport ist beschädigt” beim ersten Start

Ursache: macOS Gatekeeper blockt unsignierte/nicht-notarisierte Apps.

Lösung: siehe Installation § 3. Kurz:

    xattr -d com.apple.quarantine /Applications/Rapport.app

### App startet, zeigt aber schwarzen Bildschirm

Ursache: WebView-Cache korrupt.

Lösung:

    rm -rf "~/Library/Caches/com.rapport.app"
    rm -rf "~/Library/WebKit/com.rapport.app"

App neu starten. Daten gehen dabei nicht verloren (liegen in `Application Support`, nicht im Cache).

### App stürzt sofort beim Start ab

Ursache: wahrscheinlich beschädigte JSON-Daten in `studio_data_v1`.

Diagnose:

    # Daten ansehen (DevTools-Output)
    open "~/Library/Application Support/com.rapport.app"

Lösung:

1. Backup wiederherstellen (siehe Datenhaltung)
2. Oder als letzter Ausweg: Daten zurücksetzen

       mv "~/Library/Application Support/com.rapport.app" \
          "~/Library/Application Support/com.rapport.app.bad"

   App neu starten → erstellt frische Daten. Anschliessend Setup-Screen.

## Daten weg

### Nach einem App-Update fehlen Einträge

Ursache: mögliche fehlgeschlagene Migration.

Sofortmassnahme:

1. Rapport beenden (Cmd+Q, nicht nur Fenster zu)
2. Aktuelles Datenverzeichnis sichern:

       cp -R "~/Library/Application Support/com.rapport.app" \
             "~/Documents/Rapport-Notfall-$(date +%Y%m%d-%H%M)"

3. Issue erstellen
   mit:
   - Version vor dem Update (falls bekannt)
   - Version nach dem Update
   - Was fehlt
   - Optional: gesicherter Datenordner (via Pastebin oder verschlüsselt zugesandt)

### localStorage voll

Symptom: Rapport schreibt Fehler-Toast “Speicher voll” beim Sichern.

Ursache: macOS WebView limitiert localStorage auf ~10 MB pro Origin.

Lösung:

- Sehr grosse Logos durch kleinere ersetzen (Bürodaten → Logo)
- Belege (Spesen) selektiv löschen oder als externe Datei archivieren
- Auf Web-Modus wechseln (Postgres ohne praktisches Limit)

## Updates

### Auto-Update findet nichts

Diagnose:

    curl -s https://git.kgva.ch/karim/RAPPORT/raw/branch/main/APP/latest.json

→ sollte JSON liefern. Wenn nicht: Server-/Netzwerkproblem.

### Update lädt, lässt sich aber nicht installieren

Ursache: Signaturprüfung scheitert (Public-Key in App ≠ Signatur in `latest.json`).

Lösung: Manuelles Update — DMG direkt von Releases
laden und installieren. Daten bleiben erhalten.

### “Diese Version überspringen” rückgängig machen

In Einstellungen → Updates → Übersprungene Versionen zurücksetzen. Beim nächsten Start wird die Version wieder angeboten.

## PDF / QR-Schein

### QR-Schein hat falsche Daten

Diagnose-Checkliste:

- IBAN korrekt? (CH, 21 Zeichen, keine Leerzeichen)
- Empfänger-Adresse vollständig? (PLZ und Ort beide gefüllt)
- Schuldner-Adresse vollständig?
- Betrag > 0?
- Referenz nicht zu lang? (max 27 Zeichen)

QR-Bibliothek: `swissqrbill`
— bei merkwürdigen Fehlern dort nachschauen.

### PDF-Export ist leer / weisses Blatt

Ursache: Print-View hat keine Daten (möglicherweise Race-Condition beim Laden).

Lösung: Rechnung schliessen, erneut öffnen, dann PDF.

### PDF-Schrift sieht falsch aus

Ursache: Web-Schrift nicht geladen, Fallback greift.

Lösung: Vor dem Drucken warten, bis das Vorschau-Bild komplett geladen ist (3–5 Sek).

## System-Tray

### Tray-Icon erscheint nicht

Plattform-Hinweis: Tray-Icons unter macOS sind bei extrem voller Menüleiste oder unter “Bartender”/“Hidden Bar” eventuell unsichtbar.

Diagnose:

    ps aux | grep -i rapport

→ wenn Prozess läuft, aber kein Icon: in den Tray-Manager-Apps prüfen.

Konfiguration: Einstellungen → System-Tray → Tray-Icon ausblenden (aus → Icon erzwingen).

### Tray-Menü reagiert nicht / hängt

Lösung: App via Activity Monitor hart beenden und neu starten. Daten gehen nicht verloren (alle Schreibungen sind synchron in localStorage).

## Web-Modus

### Login-Screen zeigt keine Server-URL

Ursache: `.env.production` enthielt nicht den richtigen `VITE_SUPABASE_URL` zur Build-Zeit.

Lösung: `.env.production` prüfen, dann `npm run build` neu, Container restart.

### Realtime-Updates kommen nicht an

Ursache: Websocket-Support fehlt im Reverse Proxy.

Lösung: In Nginx Proxy Manager für `api.*` Websocket Support aktivieren.

Siehe Web-Modus § Troubleshooting.

## Debug-Informationen sammeln

Bei einem Issue helfen folgende Infos:

    # Rapport-Version
    defaults read /Applications/Rapport.app/Contents/Info.plist CFBundleShortVersionString

    # macOS-Version
    sw_vers

    # Architektur
    uname -m

    # Datenverzeichnis-Grösse
    du -sh "~/Library/Application Support/com.rapport.app"

    # Cache-Verzeichnis-Grösse
    du -sh "~/Library/Caches/com.rapport.app"

→ Bei Issue mit anhängen.

## Wenn nichts hilft

Neues Issue auf Gitea
mit:

- Was du gemacht hast
- Was passiert ist
- Was du erwartet hättest
- Screenshots (auch von DevTools-Konsole falls möglich)
- Rapport-Version und macOS-Version

Entwicklung Changelog