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.
* **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 zeigt dann alle angeschlossenen Drucker mit Namen an und fragt,
welcher verwendet werden soll. Danach richtet es sich selbst ein und meldet
sich bei der Timer-App. Die Anzeige hier springt von „wartet auf den Pi" auf
den fertigen Drucker um — es ist nichts weiter zu tun.

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

**🚪 Abmelden** meldet nur dieses Gerät ab. Laufende Timer bleiben davon
unberührt und laufen weiter.