timer-app/README.md

# Timer — Zeiterfassung

Zeiterfassung mit automatischer Kostenberechnung für den Einsatz im Laden.

> **Installation und Technik:** siehe [DEPLOY.md](DEPLOY.md).
> Diese Datei ist die Kurzanleitung für die tägliche Bedienung.

---

## Anmelden

Seite im Browser öffnen, Passwort eingeben. Die Anmeldung gilt 24 Stunden und
verlängert sich bei Benutzung — ein Tablet am Tresen muss also nicht täglich neu
angemeldet werden.

## Timer starten

Oben optional einen Namen eintippen — zum Beispiel „Tisch 2", „Herr Müller" oder
„Reparatur Werkbank" — und auf **▶ Neuer Timer** klicken.

Es können **beliebig viele Timer gleichzeitig** laufen, einer je Platz oder Kunde.
Jeder bekommt eine eigene Karte mit Zeit und laufendem Betrag. Der Name lässt
sich jederzeit nachträglich ändern, einfach im Feld überschreiben.

## Während der Timer läuft

| Knopf | Wirkung |
|---|---|
| **❚❚ Pause** | Zeit anhalten, Betrag friert ein |
| **▶ Weiter** | pausierten Timer fortsetzen |
| **🖨 Bon** | Zwischenstand ausdrucken — der Timer läuft weiter |
| **✓ Beenden** | Vorgang abschließen, in der Historie speichern und Bon drucken |
| **✕ Verwerfen** | Timer wegwerfen, **nichts** wird gespeichert |

Vor dem Beenden und dem Verwerfen kommt eine Rückfrage mit Zeit und Betrag.

### Was passiert, wenn …

* **… der Browser geschlossen wird?** Nichts. Der Timer läuft auf dem Server
  weiter und ist beim nächsten Öffnen wieder da.
* **… das Tablet neu startet?** Ebenfalls nichts — einfach wieder aufrufen.
* **… ein Kollege am zweiten Gerät nachschaut?** Er sieht dieselben Timer live.
* **… über Nacht vergessen wurde zu stoppen?** Der Timer zählt weiter, wie eine
  Wanduhr. Die Karte zeigt, seit wann er läuft. Wer die Zeit korrigieren will,
  verwirft den Timer und erfasst ihn neu.

## Bon für die Kasse

Auf dem Bon steht, was der Kunde zahlen muss — mit Beginn, Ende, Dauer und dem
Tarif, damit der Betrag nachvollziehbar ist. Der Betrag selbst steht groß und
allein darunter.

Zwei Wege, je nachdem, wie der Kunde geht:

* **Der Platz wird frei.** **✓ Beenden** drücken. Der Vorgang wandert in die
  Historie und der Bon kommt aus dem Drucker — damit geht der Kunde zur Kasse.
* **Der Kunde will zwischendurch zahlen, bleibt aber.** **🖨 Bon** drücken. Der
  Zettel zeigt den Stand von jetzt und ist als *Zwischenstand* gekennzeichnet;
  der Timer läuft unverändert weiter.

### Strichcode für die Kasse

Unter dem Betrag steht ein Strichcode. Die Kasse scannt ihn und hat den Artikel
sofort auf dem Bildschirm — niemand muss ihn in einer Liste suchen. Der Code
steht ohne Beschriftung da: auf einem Kundenbeleg hat ein interner Artikelname
nichts verloren.

Welcher Artikel das ist, steht in den **Einstellungen** unter *Artikel in der
Kasse*; ab Werk `techniker`. Wird die Leistung in der Kasse umbenannt, wird der
Name hier geändert — ohne dass jemand an die App muss. Der ganze Block lässt
sich mit *Strichcode für die Kasse drucken* auch abschalten.

Zwei Grenzen setzt das Papier: Der Name darf **keine Umlaute und keine
Sonderzeichen** enthalten (ein Strichcode kann sie nicht abbilden) und nicht
länger sein, als quer auf die Rolle passt — bei 80 mm sind das 17 Zeichen. Beides
sagt die App beim Speichern, statt später einen unlesbaren Code zu drucken.

### Wenn nichts aus dem Drucker kommt

Der Vorgang ist trotzdem gespeichert — die App sagt in dem Fall ausdrücklich,
dass der Bon nicht gedruckt wurde, und nennt den Grund. Meist ist die Papierrolle
leer oder der Drucker aus. Nach dem Beheben: in der **Historie** beim Eintrag auf
**🖨** tippen, dann kommt derselbe Beleg noch einmal. Genauso, wenn ein Kunde
seinen Bon verlegt hat.

## Historie

Unter **📊 Historie** stehen alle abgeschlossenen Vorgänge mit Datum, Name,
Dauer und Betrag. Oben summieren drei Kacheln den gewählten Zeitraum.

* Filter nach **Von/Bis-Datum** und nach **Name**
* Schnellauswahl **Heute** und **Dieser Monat**
* **⬇ CSV-Export** lädt genau die gefilterte Auswahl herunter — die Datei lässt
  sich direkt in Excel öffnen, Umlaute und Beträge stimmen
* Das **🗑**-Symbol löscht einen Eintrag endgültig (mit Rückfrage)

## Einstellungen

Unter **⚙️ Einstellungen** wird der Tarif festgelegt: Betrag und Intervall,
zum Beispiel „10 € pro 10 Minuten". Die Vorschau rechnet Beispiele durch.

Darunter steht, was auf dem Bon gedruckt wird:

* **Kopfzeilen** — Ladenname, Adresse, Telefonnummer. Die erste Zeile wird groß
  gedruckt.
* **Fußzeilen** — der Hinweis unter dem Betrag, etwa „Bitte an der Kasse
  bezahlen."
* **Bon beim Beenden automatisch drucken** — ausgeschaltet kommt ein Bon nur
  noch über die 🖨-Knöpfe.
* **Strichcode für die Kasse drucken** — siehe unten. Ausgeschaltet bleibt der
  Bon genau wie vorher.
* **Artikel in der Kasse** — der Name, der im Strichcode steckt.
* **Drucker am Pi** — an welchem Gerät gedruckt wird. **🔄 Suchen** fragt den
  Pi, was gerade angeschlossen ist, und zeigt die Drucker mit Namen an
  („EPSON TM-T88IV"). „Automatisch" nimmt den ersten gefundenen — richtig,
  solange nur ein Drucker am Pi hängt.
* **Probedruck** — druckt einen Beispielbon. Beantwortet die Frage, ob der
  Drucker überhaupt erreichbar ist; darüber steht sein aktueller Zustand.

Wichtig zu wissen:

* **Jede angefangene Einheit wird voll berechnet.** 10 Minuten und 1 Sekunde
  kosten bei einem 10-Minuten-Takt bereits zwei Einheiten.
* Der Tarif und die Bon-Texte gelten für **alle Geräte gemeinsam**.
* Eine Änderung wirkt sofort auf laufende und neue Timer. Bereits gespeicherte
  Einträge in der Historie behalten den Tarif, der beim Beenden galt.

### Einen neuen Drucker anschließen

Wenn der Drucker-Rechner getauscht wird oder ein zweiter Laden dazukommt:
**🔧 Drucker einrichten** anklicken, dann **🔗 Einrichtungslink erzeugen**.

Es erscheint ein Befehl. Der wird auf dem Raspberry Pi in ein Terminal
eingegeben — über **📋 Kopieren** landet er in der Zwischenablage:

```
curl -fsSL "…" -o bondrucker.sh && sudo bash bondrucker.sh
```

Das Skript installiert die Software und meldet den Pi anschließend bei der
Timer-App an. Die Anzeige hier springt von „wartet auf den Pi" auf den fertigen
Drucker um.

Danach oben unter **Drucker am Pi** auf **🔄 Suchen** tippen und den Drucker
auswählen. Hängt nur einer am Pi, kann „Automatisch" stehen bleiben.

Der Link **gilt nur einmal und eine halbe Stunde lang**. Ist er abgelaufen,
einfach einen neuen erzeugen. Weitergeben sollte man ihn nicht: wer ihn hat,
kann einstellen, auf welchem Gerät hier gedruckt wird.

Voraussetzung: Auf dem Pi läuft ein frisches Raspberry Pi OS (oder Debian) und
der Bondrucker hängt am USB-Anschluss.

## Abmelden

Ganz oben steht die Handy-Insel-Leiste. Über den Avatar rechts öffnet sich das
Benutzer-Menü, dort steht **Abmelden**. Das meldet dieses Gerät beim Timer, im
Portal und bei Authentik ab. Laufende Timer bleiben davon unberührt und laufen
weiter. Laufen noch welche, fragt die App vorher nach.

Ist das Portal einmal nicht erreichbar, fehlt die Leiste. Dann steht
**🚪 Abmelden** wie früher oben rechts in der App.