# Anweisungen für Mistral Vibe - Fichero Printer Projekt

## Projektkontext
- **Ziel**: Home Assistant Add-on für Fichero/D11s Thermodrucker
- **Technologie**: Python, BLE/Classic Bluetooth, FastAPI
- **Referenz**: Original-Code in `original/` funktioniert - halte dich daran

## Arbeitsweise

### 1. Code-Änderungen
- **Vereinfachen**: Bevorzuge einfache, robuste Lösungen
- **Referenz**: Original-Code als Goldstandard nutzen
- **Dokumentation**: Klare Kommentare für komplexe Logik
- **Testen**: Vor dem Commit lokal testen

### 2. Versionierung
- **Semantic Versioning**: MAJOR.MINOR.PATCH
- **Changelog**: Detaillierte Einträge mit:
  - **Fixed**: Bugfixes
  - **Added**: Neue Features
  - **Changed**: Änderungen an bestehendem Verhalten
  - **Improved**: Verbesserungen ohne API-Änderungen

### 3. Git-Workflows
- **Commits**: Atomar, mit klaren Nachrichten
- **Branches**: Feature-Branches für Experimente
- **Tags**: Versionen mit `vX.Y.Z` markieren
- **History**: Saubere, nachvollziehbare Commits

### 4. Fehlerbehandlung
- **Priorität**: Zuverlässigkeit über Features
- **Logging**: Klare, actionable Fehlermeldungen
- **Fallback**: Graceful Degradation implementieren
- **Benutzerführung**: Hilfreiche Fehlermeldungen

### 5. Kommunikation
- **Fragen**: Bei Unklarheiten nachfragen
- **Optionen**: Bei Entscheidungen Alternativen vorstellen
- **Best Practices**: Python/AsyncIO/Bluetooth Standards folgen
- **Dokumentation**: Code und Prozesse dokumentieren

## Checkliste für Pull Requests

- [ ] Code vereinfacht und getestet
- [ ] Referenz zum Original-Code geprüft
- [ ] Dokumentation aktualisiert
- [ ] Version erhöht (CHANGELOG.md)
- [ ] Git-History sauber
- [ ] Tests bestanden (falls vorhanden)

## Projektziele

1. **Stabilität**: Zuverlässige Drucker-Verbindung
2. **Benutzerfreundlichkeit**: Einfache Konfiguration
3. **Wartbarkeit**: Sauberer, dokumentierter Code
4. **Kompatibilität**: Home Assistant Standards einhalten

## Technische Richtlinien

### Python
- Type Hints verwenden
- PEP 8 einhalten
- Async/Await korrekt nutzen
- **Circular Imports vermeiden**: Konstanten in das Modul verschieben, das sie primär nutzt

### Bluetooth
- BLE bevorzugen (zuverlässiger)
- Classic Bluetooth als Fallback
- Zeitouts sinnvoll setzen (5-10 Sekunden)
- **Fehlerbehandlung**: Klare Meldungen ohne komplexe Wiederherstellung

### Home Assistant
- Add-on Standards einhalten
- Konfiguration validieren
- Logging für Debugging
- **Versionierung**: Immer Version erhöhen, damit Änderungen erkannt werden

### Wichtige Lektionen

1. **Circular Imports**: Verursachen `ImportError` und verhindern den Start
   - Lösung: Konstanten in das nutzende Modul verschieben
   - Beispiel: `PRINTHEAD_PX` → `imaging.py`

2. **Versionierung**: Jede Änderung needs neue Version (0.1.42, etc.)
   - Home Assistant erkennt nur Änderungen mit neuer Version
   - Immer config.yaml + api.py + CHANGELOG.md aktualisieren

3. **Einfachheit**: Komplexe Logik oft Quelle von Problemen
   - Bevorzuge direkte Verbindungen über Wiederherstellungsversuche
   - Klare Fehler > komplexe Recovery

## Entscheidungsfindung

1. **Einfache Lösungen bevorzugen**
2. **Original-Code als Referenz**
3. **Benutzererfahrung priorisieren**
4. **Dokumentation nicht vergessen**

---
*Let's build reliable printer connections!* 🖨️