Fahrdienst-Assistenz via Telegram

KK-Minutenverwaltung – Setup & Betrieb

Stand: 28.05.2026 ---

Übersicht

Das KK-System deckt ab:

Einzeleintrag mit Soll/Ist/KK-Minuten/Dienstnummer

Löschung mit interaktiver Auswahl

Batch-Erfassung mehrerer Zeilen

Dienstnummernverwaltung

PDF-Reports (Tages-/Wochen-/Monatsabruf)

Personalisierte Eingabereihenfolge pro Nutzer

Besonderheit: Private Funktionen (/kk dn, /kk del, /kk druck) laufen im Privat-Chat. Bei Aufruf aus Gruppe wird der Dialog automatisch dorthin übergeben. Sicherheit: User-Profile (Name, Dienstnummer) sind AES-256 verschlüsselt. ---

Datumslogik (einheitlich)

Format | Bedeutung --------|----------- TT.MM | Laufendes Jahr TT.MM. | Laufendes Jahr TT.MM.YY | Explizites Jahr (z.B. 15.03.25 = März 2025) TT.MM.YYYY | Lange Form Beispiele:

/kk 16.04 22:48 23:05 5 (heute)

/kk 16.04.25 22:48 23:05 5 (April 2025)

/kk del 16.04 (heute löschen)

/kk del 16.04.25 (April 2025 löschen)

---

Voraussetzungen

1. KK-Feature aktivieren: /settings → KK → Speichern 2. Nutzerprofil anlegen: /register (für Reports & Drucke) 3. Bot privat starten: /start (für Auto-Übergabe) ---

Befehlsreferenz

Eintrag hinzufügen

Syntax:

/kk [Soll-Zeit] [Ist-Zeit] [KK-Minuten] (heute)

/kk [Datum] [Soll-Zeit] [Ist-Zeit] [KK-Minuten] [Dienstnummer?] (beliebiges Datum)

Beispiele:

/kk 14:00 14:15 5 (heute)

/kk 16.04.25 14:00 14:15 5 (März 2025)

/kk 16.04.25 14:00 14:15 5 Res112 (mit Dienstnummer)

---

Einträge löschen

Syntax:

/kk del (Einträge für heute, interaktiv)

/kk del [Datum] (Einträge für Datum)

Ablauf: 1. Bot listet alle Einträge auf 2. Mit Nummern antworten: 1,2 oder alle 3. Bei Aufruf aus Gruppe → Dialog im Privat-Chat Beispiele:

/kk del (heute)

/kk del 16.04 (heute)

/kk del 16.04.25 (April 2025)

---

Batch-Erfassung

Syntax:

/kk list mit mehreren Zeilen, optional confirm für Zukunftsdaten

Beispiel:

/kk list
16.04.25 14:00 14:15 5
17.04.25 14:00 14:15 5
18.04.25 14:00 14:15 5 Res112
confirm

---

Dienstnummern nachtragen

Syntax:

/kk dn (interaktiv für heute)

/kk dn [Datum] (für bestimmtes Datum)

Hinweis: Bei Aufruf aus Gruppe → Dialog im Privat-Chat ---

Eingabereihenfolge anpassen

Jeder Nutzer kann die Reihenfolge der vier KK-Felder individuell festlegen. Syntax:

/kk settings (aktuelle Reihenfolge zeigen)

/kk settings <Feld1> <Feld2> <Feld3> <Feld4> (speichern)

Erlaubte Feldnamen: Kanonisch | Aliase | Bedeutung -----------|--------|----------- Soll | A | Soll-Ankunft Ist | D | Ist-Ankunft (Verzug) Min | E, KK | Vergütete KK-Minuten DN | Dienstnummer | Dienstnummer Beispiele:

/kk settings Soll Ist Min DN (Standard)

/kk settings Ist Soll Min DN (Ist zuerst)

/kk settings Ist Soll DN Min (DN an 3. Stelle)

Ergebnis: Nach dem Speichern antwortet der Bot mit der neuen Reihenfolge. Danach genügt /kk 14:15 14:00 Res112 5 in dieser Reihenfolge. Hinweis: Die Einstellung wird dauerhaft pro Nutzer gespeichert (DB: kk_input_order). Zum Zurücksetzen: /kk settings Soll Ist Min DN ---

PDF-Reports & Druckbelege

Befehle:

/kk druck oder /tag druck [TT.MM.YY] (Tagesabruf)

/woche druck [KW.YY] (Wochenabruf)

/monat druck [MM.YY] (Monatsbericht)

/tag [TT.MM.YY], /woche [KW.YY], /monat [MM.YY] (Anzahl-Übersicht)

Hinweise:

Druckbelege laufen immer über Privat-Chat

Bei Aufruf aus Gruppe → Dialog wird automatisch dorthin übergeben

Sicherheits-Hierarchie: Dienstnummer > Datum

Layout: 2 Formulare pro A4-Seite

---

Dienstausweisnummer (Service-ID)

Eindeutigkeit:

service_id ist systemweit eindeutig (auch über Module hinweg)

Bei /register oder /da wird die Nummer geprüft

Duplikate werden abgelehnt

Technisch:

Speicherung: Verschlüsselt + HMAC-Fingerprint (service_id_fp)

Fingerprint eindeutig indiziert für schnelle Konfliktprüfung

Bestandsmigration läuft automatisch in create_tables() (Backfill)

---

Technische Details

Kernberechnung:

Zentral in logic_kk.py über calculate_kk_logic()

Report-Aufbereitung in pdf_reports.py über build_report_row() / build_report_rows()

Konsistenz zwischen Eintrag & Report durch zentrale Logik

Private Chat-Übergabe:

/kk dn, /kk del, /kk druck sind Privat-Chat-Funktionen

Bei Aufruf aus Gruppe → Bot startet Dialog automatisch privat

Voraussetzung: Bot wurde privat per /start aktiviert

Falls nicht: Bot zeigt Deep-Link zur Aktivierung

---

Troubleshooting

/kk druck liefert nichts

Prüfen: Existieren Einträge für das Datum?

Datumsformat prüfen (TT.MM oder TT.MM.YY)

Bot privat aktiviert (/start)?

Datumsablehnung

Ohne Jahr: Zukunftsdaten nicht erlaubt

Für vergangene Jahre: Immer TT.MM.YY nutzen (z.B. 15.03.25)

Report-Fehler nach Änderungen

build_report_row() / build_report_rows() in pdf_reports.py prüfen

Keine lokalen Zeitberechnungen einbauen → immer calculate_kk_logic() nutzen

Dienst neu starten: sudo systemctl restart quasselbot

---

Verwandte Dokumentation

Admin-Betrieb: [OPERATIONS.md](OPERATIONS.md)

Datenbank: [database.py](database.py)

Zeitlogik: [logic_kk.py](logic_kk.py)

PDF-Erzeugung: [pdf_reports.py](pdf_reports.py)