diff --git a/README.md b/README.md index 7dcf797..4a24d3d 100644 --- a/README.md +++ b/README.md @@ -1,11 +1,161 @@ # PIOMINT -Track every hours with minty Fresh Efficiency! -## AppIdee -Es gibt einige Zeit-Tracker Apps für Pioniere. Leide sind die guten in der Regel nur auf Englisch erhältlicht und viel zu Umständlich. +Track every hour with minty fresh efficiency! 🌿 -## Das Ziel -Eine einfache App mit einem freshen UI mit der es leicht fällt die Stunden aufzuschreiben und pünktlich abzugeben. +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](#über-das-projekt) +- [Aktueller Stand](#aktueller-stand) +- [Features](#features) +- [Tech-Stack](#tech-stack) +- [Projektstruktur](#projektstruktur) +- [Lokale Entwicklung](#lokale-entwicklung) +- [Daten & Datenschutz](#daten--datenschutz) +- [Versionierung & Deployment](#versionierung--deployment) +- [Roadmap / offene Punkte](#roadmap--offene-punkte) +- [Mitwirken](#mitwirken) +- [Lizenz](#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 -GANZ AM ANFANG :D \ No newline at end of file + +**Version 26.0** – in aktivem Einsatz. Aus dem "GANZ AM ANFANG"-Prototyp ist eine +funktionsreiche PWA geworden (siehe [Features](#features)). Läuft produktiv unter +[app.piomint.de](https://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](#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.12+ + +```bash +git clone https://git.samuelzielke.de/samuelzielke/piomint.git +cd piomint + +python3 -m venv venv +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/` +(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` 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) + +## 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](https://chat.whatsapp.com/Cy4laGaEdLP1DZbhN04zRQ) oder direkt an +Samuel. + +## Lizenz + +Bisher keine Lizenz festgelegt – alle Rechte liegen beim Autor.