100 lines
3.3 KiB
Markdown
100 lines
3.3 KiB
Markdown
# 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!* 🖨️ |