datecalc/README.md

# Elpatrons Datumsrechner

[![Test Coverage](https://img.shields.io/badge/test%20coverage-90%25-brightgreen)](https://github.com/elpatron/datecalc)

Diese moderne Python-Webanwendung (Flask) ermöglicht verschiedene Datumsberechnungen über eine übersichtliche, barrierefreie Weboberfläche.

## Inhaltsverzeichnis

- [Demo](#demo)
- [Funktionen](#funktionen)
- [Installation (lokal)](#installation-lokal)
- [Starten der App](#starten-der-app)
- [Statistik-Dashboard & Passwortschutz](#statistik-dashboard-stats--passwortschutz)
- [Docker (empfohlen für Produktion)](#docker-empfohlen-für-produktion)
  - [Log-Verzeichnis mounten](#log-verzeichnis-mounten-logs-auf-dem-host-speichern)
  - [docker-compose Beispiel](#docker-compose-beispiel)
- [REST API](#rest-api)
  - [Tage/Werktage zwischen zwei Daten](#1-tagewerktage-zwischen-zwei-daten)
  - [Wochentag zu einem Datum](#2-wochentag-zu-einem-datum)
  - [Kalenderwoche zu Datum](#3-kalenderwoche-zu-datum)
  - [Start-/Enddatum einer Kalenderwoche](#4-start-enddatum-einer-kalenderwoche)
  - [Datum plus/minus Tage, Wochen, Monate](#5-datum-plusminus-tage-wochen-monate)
  - [Statistik](#6-statistik)
  - [Monitoring & Healthcheck](#7-monitoring--healthcheck)
- [Progressive Web App (PWA)](#progressive-web-app-pwa)
- [Monitoring & Healthcheck](#monitoring--healthcheck)
- [Entwicklung & Hinweise](#entwicklung--hinweise)
- [Automatisierte Tests](#automatisierte-tests)
- [Hinweise](#hinweise)
  - [Motivation](#motivation)
  - [Vibe Coding](#vibe-coding)
  - [Statistik-Erfassung, Logging](#statistik-erfassung-logging)
  - [Barrierefreiheit (Accessibility)](#barrierefreiheit-accessibility)
  - [Code Statistik](#code-statistik)
- [Lizenz](#lizenz)

## Demo

Datumsrechner Live: [https://date.elpatron.me](https://date.elpatron.me)

![App Screenshot](./assets/image-20250725095959116.png)

**Lighthouse-Performance-Score:** 

Die Webanwendung erreicht hervorragende Performance-Werte in allen Kategorien (Performance, Accessibility, Best Practices, SEO).

[Lighthouse-Ergebnis anzeigen](./lighthouse-score.pdf) - 

## Funktionen

- Anzahl der Tage zwischen zwei Daten
- Anzahl der Werktage zwischen zwei Daten (mit optionaler Berücksichtigung bundeslandspezifischer Feiertage)
- Anzeige des Wochentags eines Datums
- Datum plus/minus X Tage
- Datum plus/minus X Werktage
- Datum plus/minus X Wochen/Monate
- Kalenderwoche zu Datum
- Start-/Enddatum einer Kalenderwoche eines Jahres
- Sprachausgabe für alle Ergebnisse (barrierefrei)
- Statistik-Dashboard mit Passwortschutz unter `/stats`

## Bundesland-Feiertage

Die Werktagsberechnung kann optional bundeslandspezifische Feiertage berücksichtigen. Dazu wird die kostenlose API von [feiertage-api.de](https://feiertage-api.de) verwendet.

**Verfügbare Bundesländer:**
- Baden-Württemberg (BW)
- Bayern (BY)
- Berlin (BE)
- Brandenburg (BB)
- Bremen (HB)
- Hamburg (HH)
- Hessen (HE)
- Mecklenburg-Vorpommern (MV)
- Niedersachsen (NI)
- Nordrhein-Westfalen (NW)
- Rheinland-Pfalz (RP)
- Saarland (SL)
- Sachsen (SN)
- Sachsen-Anhalt (ST)
- Schleswig-Holstein (SH)
- Thüringen (TH)

Die Feiertage werden automatisch für den gewählten Zeitraum abgerufen und bei der Werktagsberechnung als arbeitsfreie Tage behandelt. Im Ergebnis werden zusätzlich die Anzahl der Wochenendtage und Feiertage angezeigt.

## Installation (lokal)

1. Python 3.8+ installieren
2. Abhängigkeiten installieren:

```bash
pip install -r requirements.txt
```

## Starten der App

```bash
python app.py
```

Die App ist dann unter http://localhost:5000 erreichbar.

## Statistik-Dashboard (/stats) & Passwortschutz

Das Dashboard ist mit einem statischen Passwort geschützt, das über die Umgebungsvariable `STATS_PASSWORD` gesetzt wird.

![Statistics page](./assets/image-20250725100127004.png)

Beispiel (PowerShell):

```powershell
$env:STATS_PASSWORD = "meinSicheresPasswort"
python app.py
```

Für Docker:

```powershell
$env:STATS_PASSWORD = "meinSicheresPasswort"
docker run -e STATS_PASSWORD=$env:STATS_PASSWORD -p 5000:5000 datumsrechner
```

## Docker (empfohlen für Produktion)

Die App läuft im Container mit dem WSGI-Server **Gunicorn**:

```bash
docker build -t datumsrechner .
docker run -p 5000:5000 datumsrechner
```

- Gunicorn startet automatisch (siehe Dockerfile)
- Empfohlen für produktiven Einsatz

### Log-Verzeichnis mounten (Logs auf dem Host speichern)

Um die Logdateien außerhalb des Containers zu speichern, kannst du das log-Verzeichnis mounten:

**PowerShell-Beispiel:**

```powershell
docker run -e STATS_PASSWORD=deinPasswort -p 5000:5000 -v ${PWD}/log:/app/log datumsrechner
```

### docker-compose Beispiel

Erstelle eine Datei `docker-compose.yml`:

```yaml
services:
  datumsrechner:
    build: .
    ports:
      - "5000:5000"
    environment:
      - STATS_PASSWORD=deinPasswort
    volumes:
      - ./log:/app/log
```

Starte mit:

```bash
docker-compose up --build
```

## REST API

Alle Datumsfunktionen stehen auch als REST-API zur Verfügung. Die API akzeptiert und liefert JSON.  
**Basis-URL:** `http://localhost:5000/api/`

**Hinweis:** Die Nutzung der REST API wird im Statistik-Dashboard ausgewertet und als Diagramm angezeigt.

### Endpunkte und Beispiele

#### 1. Tage/Werktage zwischen zwei Daten

**POST** `/api/tage_werktage`

```json
{
  "start": "2024-06-01",
  "end": "2024-06-10",
  "werktage": true,
  "bundesland": "BY"
}
```

**Mit curl:**

```bash
curl -X POST http://localhost:5000/api/tage_werktage \
  -H "Content-Type: application/json" \
  -d '{"start": "2024-06-01", "end": "2024-06-10", "werktage": true, "bundesland": "BY"}'
```

**Antwort:**

```json
{ "result": 7 }
```

**Hinweis:** Der Parameter `bundesland` ist optional und wird nur bei `"werktage": true` berücksichtigt. Verfügbare Bundesland-Kürzel siehe oben.

#### 2. Wochentag zu einem Datum

**POST** `/api/wochentag`

```json
{ "datum": "2024-06-10" }
```

**Mit curl:**

```bash
curl -X POST http://localhost:5000/api/wochentag \
  -H "Content-Type: application/json" \
  -d '{"datum": "2024-06-10"}'
```

**Antwort:**

```json
{ "result": "Montag" }
```

#### 3. Kalenderwoche zu Datum

**POST** `/api/kw_berechnen`

```json
{ "datum": "2024-06-10" }
```

**Mit curl:**

```bash
curl -X POST http://localhost:5000/api/kw_berechnen \
  -H "Content-Type: application/json" \
  -d '{"datum": "2024-06-10"}'
```

**Antwort:**

```json
{ "result": "KW 24 (2024)", "kw": 24, "jahr": 2024 }
```

#### 4. Start-/Enddatum einer Kalenderwoche

**POST** `/api/kw_datum`

```json
{ "jahr": 2024, "kw": 24 }
```

**Mit curl:**

```bash
curl -X POST http://localhost:5000/api/kw_datum \
  -H "Content-Type: application/json" \
  -d '{"jahr": 2024, "kw": 24}'
```

**Antwort:**

```json
{
  "result": "10.06.2024 bis 16.06.2024",
  "start": "2024-06-10",
  "end": "2024-06-16"
}
```

#### 5. Datum plus/minus Tage, Wochen, Monate

**POST** `/api/plusminus`

```json
{
  "datum": "2024-06-10",
  "anzahl": 5,
  "einheit": "tage",
  "richtung": "add",
  "werktage": false
}
```

**Mit curl:**

```bash
curl -X POST http://localhost:5000/api/plusminus \
  -H "Content-Type: application/json" \
  -d '{"datum": "2024-06-10", "anzahl": 5, "einheit": "tage", "richtung": "add", "werktage": false}'
```

**Antwort:**

```json
{ "result": "2024-06-15" }
```

**Hinweis:**  
- `"einheit"`: `"tage"`, `"wochen"` oder `"monate"`
- `"richtung"`: `"add"` (plus) oder `"sub"` (minus)
- `"werktage"`: `true` für Werktage, sonst `false` (nur bei `"tage"` unterstützt)

#### 6. Statistik

**GET** `/api/stats`

**Mit curl:**

```bash
curl http://localhost:5000/api/stats
```

**Antwort:**

```json
{
  "pageviews": 42,
  "func_counts": { "plusminus": 10, "tage_werktage": 5 },
  "impressions_per_day": { "2024-06-10": 7 }
}
```

#### 7. Monitoring & Healthcheck

**GET** `/api/monitor`

**Mit curl:**

```bash
curl http://localhost:5000/api/monitor
```

**Antwort:**

```json
{
  "status": "ok",
  "message": "App running",
  "time": "2025-07-24T13:37:00.123456",
  "uptime_seconds": 12345,
  "pageviews_last_7_days": 42
}
```

---

**Fehlerfälle** liefern immer einen HTTP-Statuscode 400 und ein JSON mit `"error"`-Feld, z.B.:

```json
{ "error": "Ungültige Eingabe", "details": "..." }
```

## Progressive Web App (PWA)

Elpatrons Datumsrechner ist als PWA installierbar (z.B. auf Android/iOS-Homescreen oder Desktop). Die App funktioniert offline für die Startseite und statische Ressourcen, die Datumsberechnung bleibt serverseitig.

- Manifest und Service Worker sind integriert
- App-Icon und Theme-Color für Homescreen
- Installation über Browser-Menü ("Zum Startbildschirm hinzufügen")

## Monitoring & Healthcheck

Die App bietet einen Monitoring-Endpunkt unter `/monitor`, der Statusinformationen als JSON zurückgibt (z.B. für Uptime-Robot, Docker Healthcheck oder eigene Tools):

- Status (ok)
- Aktuelle Serverzeit
- Uptime (Sekunden seit Start)
- Pageviews der letzten 7 Tage

Beispiel-Aufruf:

```
GET https://date.elpatron.me/monitor
```

Antwort:

```json
{
  "status": "ok",
  "message": "App running",
  "time": "2025-07-24T13:37:00.123456",
  "uptime_seconds": 12345,
  "pageviews_last_7_days": 42
}
```

## Entwicklung & Hinweise

- Die HTML-Templates liegen im Ordner `templates/` (Trennung von Logik und Darstellung)
- Das Projekt ist auf Codeberg gehostet: [https://codeberg.org/elpatron/datecalc](https://codeberg.org/elpatron/datecalc)
- Modernes, responsives Design mit Akkordeon und Icons

## Automatisierte Tests

Automatisierte Tests sind mit pytest möglich:

```powershell
pip install -r requirements.txt
pytest test_app.py
```

Die Tests prüfen u.a. die Erreichbarkeit der App, die wichtigsten Funktionen und den Schutz vor XSS-Angriffen.

## Hinweise

### Motivation

Finde mal eine Datumsrechner- Webapp, die nicht völlig Werbe- und Tracking verseucht ist! Da ich sowas häufiger mal brauche, hab ich mir eine eigene gemacht.

### Vibe Coding

Dieses Projekt wurde zu nahezu 100% mit Unterstützung künsticher Intelligenz (*[Vibe Coding](https://de.wikipedia.org/wiki/Vibe_Coding)*) erstellt. Das Grundgerüst war nach ca. 45 Minuten fertig gestellt, insgesamt hat die Entwicklung des Projekts ca. 4 Stunden Zeit beansprucht.

### Statistik-Erfassung, Logging

Es werden keine IP-Adressen oder sonstigen persönlichen Daten gespeichert, lediglich die Zahl der Aufrufe der Funktionen in einer kumulierten Darstellung. Die Logdatei enthält nur Einträge der letzten sieben Tage.

### Barrierefreiheit (Accessibility)

*Elpatrons Datumsrechner* ist barrierefrei gestaltet und erfüllt zentrale Anforderungen an Accessibility (a11y):

- *Semantische HTML-Struktur:* Überschriften, Labels und Formularelemente sind korrekt ausgezeichnet und verknüpft.
- *ARIA-Attribute:* Accordion und Statusmeldungen sind mit ARIA-Attributen versehen, damit Screenreader die Struktur und Zustände erkennen.
- *Tastaturbedienbarkeit:* Alle interaktiven Elemente (Accordion, Buttons, Formulare) sind vollständig per Tastatur bedienbar (inkl. Fokus-Indikator und Pfeiltasten-Navigation im Accordion).
- *Fokus-Indikatoren:* Deutliche visuelle Hervorhebung des Fokus für alle Bedienelemente.
- *Farbkontraste:* Hohe Kontraste für Texte, Buttons und Ergebnisboxen, geprüft nach WCAG-Richtlinien.
- *Status- und Fehlermeldungen:* Ergebnisse und Fehler werden mit `aria-live` für Screenreader zugänglich gemacht.
- *Sprachausgabe:* Alle Ergebnisse können über 🔊-Buttons vorgelesen werden (Web Speech API, deutsche Sprache).
- *Mobile Optimierung:* Zusätzliche Meta-Tags für bessere Bedienbarkeit auf mobilen Geräten und Unterstützung von Screenreadern.
- *SEO:* Das Thema Barrierefreiheit ist in den Meta-Tags für Suchmaschinen sichtbar.

Damit ist die App für Menschen mit unterschiedlichen Einschränkungen (z.B. Sehbehinderung, motorische Einschränkungen) gut nutzbar und entspricht modernen Webstandards.

### Code Statistik

cloc|github.com/AlDanial/cloc v 2.06  T=0.16 s (137.5 files/s, 29033.4 lines/s)
--- | ---

Language|files|blank|comment|code
:-------|-------:|-------:|-------:|-------:
HTML|8|36|6|1998
Python|2|53|57|614
JavaScript|2|95|87|571
Markdown|2|123|0|353
JSON|3|0|0|243
CSS|1|186|3|188
SVG|2|0|0|14
Dockerfile|1|5|6|8
DOS Batch|1|0|0|1
--------|--------|--------|--------|--------
SUM:|22|498|159|3990

## Lizenz

Dieses Projekt steht unter der [MIT-Lizenz](LICENSE).

---
(c) 2025 [Markus Busche](https://digitalcourage.social/@elpatron)