Fichero/VIBECHAT.md

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! 🖨️