piomint/README.md

PIOMINT

Track every hour with minty fresh efficiency! 🌿

Eine schlanke Progressive Web App für Pioniere, um Dienststunden, Bibelstudien und Bemerkungen unkompliziert zu erfassen – und den Monatsbericht mit einem Klick fertig formatiert für WhatsApp zu teilen.

---

Inhalt

• Über das Projekt
• Aktueller Stand
• Features
• Tech-Stack
• Projektstruktur
• Lokale Entwicklung
• Daten & Datenschutz
• Versionierung & Deployment
• Roadmap / offene Punkte
• Mitwirken
• Lizenz

---

Über das Projekt

Es gibt einige Zeit-Tracker-Apps für Pioniere. Leider sind die guten in der Regel nur auf Englisch erhältlich und viel zu umständlich.

Das Ziel: eine einfache App mit einem frischen UI, mit der es leicht fällt, die Stunden aufzuschreiben und pünktlich abzugeben – als installierbare PWA, komplett auf Deutsch, ohne Account-Zwang.

Aktueller Stand

Version 26.0 – in aktivem Einsatz. Aus dem "GANZ AM ANFANG"-Prototyp ist eine funktionsreiche PWA geworden (siehe Features). Läuft produktiv unter app.piomint.de.

Features

• Dienstjahr statt Kalenderjahr – rechnet korrekt von September bis August, inkl. Navigation beliebig weit vor und zurück über Jahresgrenzen hinweg
• Monats- & Jahresübersicht mit Fortschrittsbalken (600h-Ziel) und individuellem Monatsziel
• 55h-Regel (optional, in den Einstellungen aktivierbar): deckelt Monate mit LDC-/Sonstiges-Anteil bei der Jahressumme automatisch auf 55h
• Schnellwahl-Feld (früher fix "LDC") – Name frei in den Einstellungen anpassbar
• Aktivitäten-Tabelle mit Sortierung (Datum/Dauer/Typ, auf-/absteigend), ein-/ausblendbaren Filteroptionen und Maximieren-Ansicht für mehr Überblick
• Bericht teilen – ein Klick kopiert den Monatsbericht fertig für WhatsApp formatiert in die Zwischenablage (inkl. Vorschau-Dialog)
• Timer zur direkten Zeiterfassung
• Installierbare PWA (Homescreen-Icon, Standalone-Modus, Splashscreen) mit automatischem Update-Hinweis bei neuer Version
• Alle Daten liegen lokal auf dem Gerät (IndexedDB) – siehe Daten & Datenschutz

Tech-Stack

Bereich	Technologie
Backend	Django 5.2 (django-pwa für Manifest/Service-Worker-Einbindung)
Datenhaltung (Nutzerdaten)	IndexedDB im Browser (kein serverseitiges Datenmodell)
Datenbank (Backend)	SQLite lokal / MySQL in Produktion
Frontend	Vanilla JavaScript, Bootstrap (CSS + JS-Bundle)
Deployment	Gunicorn
Sprache	Deutsch (LANGUAGE_CODE = 'de')

Es gibt bewusst kein Frontend-Build-Setup (kein npm/webpack) – die JS-Dateien unter app/static/app/js/ werden direkt vom Browser geladen.

Projektstruktur

piomint/
├── piomint/            # Django-Projekt (Settings, URLs, PWA-Konfiguration)
│   ├── settings.py
│   ├── pwa_settings.py # App-Name, Icons, Start-URL, Theme-Farben
│   └── urls.py
├── app/                # Hauptanwendung (Dashboard, Tracking, Einstellungen)
│   ├── views.py        # Versionierte Routen (siehe Versionierung & Deployment)
│   ├── urls.py
│   ├── templates/app/  # base.html (Header/Settings), home.html (Dashboard), ...
│   └── static/app/
│       ├── js/         # dbcontrol.js (IndexedDB), home01.js (UI-Logik), ...
│       ├── css/
│       └── images/
├── web/                # Öffentliche Landingpage (piomint.de)
├── doc/                # Platzhalter-App, aktuell ungenutzt
└── requirements.txt

Lokale Entwicklung

Voraussetzung: Python 3.10+ (Django 5.2 erfordert das; auf macOS zeigt python3 je nach System noch auf eine ältere Version – im Zweifel python3 --version prüfen und notfalls python3.12/python3.13 explizit installieren, z. B. via brew install python@3.12).

git clone https://git.samuelzielke.de/samuelzielke/piomint.git
cd piomint

python3.12 -m venv venv         # ggf. durch die passende 3.10+-Version ersetzen
source venv/bin/activate        # Windows: venv\Scripts\activate

pip install -r requirements.txt

python manage.py migrate
python manage.py runserver

Die App läuft dann unter http://127.0.0.1:8000/app/ (aktuelle Version, siehe unten). Für die Backend-Datenbank reicht lokal SQLite (Standardeinstellung in piomint/settings.py) – die eigentlichen Nutzerdaten (Stunden, Einstellungen) landen ohnehin im Browser, nicht in dieser DB.

Daten & Datenschutz

PioMint speichert alle erfassten Stunden, Einstellungen und Bevorzugungen lokal im Browser (IndexedDB + localStorage) – es gibt aktuell keinen Account und keine Server-Synchronisation. Das bedeutet:

• Kein Tracking, keine personenbezogenen Daten auf dem Server
• Löscht man die App/den Browser-Speicher, sind alle Einträge unwiderruflich weg – ein manuelles Backup (Export-Funktion in den Einstellungen) ist bis zu einer Server-Synchronisation die einzige Absicherung

Versionierung & Deployment

Jede Version bekommt ihre eigene URL nach dem Muster /app/v<version>/ (z. B. /app/v260/ für 26.0), definiert in app/urls.py / app/views.py. Der Grund: die PWA merkt sich beim Hinzufügen zum Homescreen eine feste start_url (PWA_APP_START_URL in piomint/pwa_settings.py). Damit Nutzer:innen nach einem Update nicht auf einer eingefrorenen alten Version hängen bleiben, leiten alle bisherigen Versions-URLs auf die aktuellste weiter.

Checkliste für ein neues Release:

1. Neue View + URL v<neue Version> in app/views.py / app/urls.py anlegen
2. Alle bisherigen Versions-Views auf die neue Route umbiegen (redirect(...))
3. PWA_APP_START_URL in piomint/pwa_settings.py auf die neue Route setzen
4. versionnumber in app/templates/app/updateinfo.html hochzählen
5. Changelog-Text in updateinfo.html schreiben (erscheint als Update-Hinweis beim ersten Öffnen der neuen Version)
6. STATIC_VERSION in piomint/settings.py hochzählen – hängt als ?v=... an allen CSS/JS-{% static %}-Links (siehe piomint/context_processors.py) und sorgt dafür, dass bereits installierte Geräte garantiert die neuen Dateien laden statt eine alte, gecachte Version zu behalten. Ohne diesen Schritt können CSS/JS und HTML auseinanderlaufen (führte schon zu eingefrorenen Screens bei Bestandsnutzern) – nicht vergessen!
7. Auf dem Server deployen: neuen Code holen (git pull), falls sich Models geändert haben python manage.py makemigrations app && python manage.py migrate ausführen (Migrationen sind nicht im Repo, siehe .gitignore), Static Files einsammeln (python manage.py collectstatic), Gunicorn neu starten

Roadmap / offene Punkte

• Server-seitige Synchronisation / Account-System (aktuell rein lokale Speicherung)
• Einstellbares Rundungsverhalten (aktuell fix: Aufrundung ab 15 Minuten)
• doc-App ist als Platzhalter angelegt, aber noch ohne Inhalt/Routing

Mitwirken

Feedback, Bug-Reports und Ideen gerne über die WhatsApp-Community, per E-Mail an app-feedback@zielke.studio (auch direkt in der App unter Einstellungen → Kontakt verlinkt) oder direkt an Samuel.

Lizenz

Bisher keine Lizenz festgelegt – alle Rechte liegen beim Autor.