# TASKS.md — AHK-Ehrenamtsmanagement

> **Status:** Phase 0 freigegeben zur Umsetzung  
> **Stand:** 13.08.2026  
> **Source of Truth:** `PROJECT_DESIGN.md`  
> **Arbeitsweise:** kleine Sessions mit klar prüfbarem Ergebnis  
> **Wichtig:** Dieses Dokument darf keine neue Architektur erfinden. Offene Entscheidungen werden markiert und gemeinsam entschieden.

---

# Phase 0 — Greenfield-Projektbasis

## Ziel der Phase

Das Projekt wird **komplett neu von Grund auf aufgebaut**.

Der bestehende CheckPoint-/Legacy-Prototyp ist **kein Migrationsziel**. Es gibt keine erhaltenswerten Produktivdaten und keine bestehende Codebasis, auf deren Kompatibilität Rücksicht genommen werden muss.

Bestehender Legacy-Code wird nicht übernommen, nur weil er bereits existiert. Falls später einzelne Ideen oder Implementierungen als Referenz dienen, müssen sie zuerst gegen `PROJECT_DESIGN.md` geprüft werden.

Am Ende von Phase 0 existiert eine minimale, lauffähige und getestete Flask-Anwendung mit:

- sauberem Git-Repository,
- festgelegter Python-3.14-Projektumgebung über `pyenv`,
- eigenem `pyenv-virtualenv`,
- Flask App Factory,
- eigenem Core-Blueprint für `/health`,
- getrennten Runtime- und Development-Abhängigkeiten,
- erstem automatisierten Test.

Noch **nicht** Teil dieser Phase:

- Datenbank,
- SQLAlchemy,
- Flask-Migrate / Alembic,
- Accounts oder Rollen,
- Authentifizierung,
- Teams oder Organisation,
- Templates / Dashboard,
- CSS / Branding,
- Docker / Gunicorn / Caddy,
- Fachmodule.

---

# 0.1 — Projektidentität festlegen

## Entscheidungen

- [x] Produktname: **AHK-Ehrenamtsmanagement**
- [x] Technischer Name: **`ahk-ehrenamtsmanagement`**
- [x] Greenfield-Neustart statt Legacy-Migration
- [x] Lokale Shell: **Bash**
- [x] Entwicklungsbetriebssystem: **EndeavourOS / Arch Linux**
- [x] Python-Serie: **3.14**
- [x] Python-Versionierung: **pyenv**
- [x] Virtuelle Umgebung: **pyenv-virtualenv**

## Konvention

Der technische Name `ahk-ehrenamtsmanagement` soll später konsistent für Repository, App-Verzeichnis, Stack-Verzeichnis und Container verwendet werden.

## Prüfergebnis

Phase 0.1 ist abgeschlossen, wenn keine weiteren Namensentscheidungen für den Projektstart notwendig sind.

**Status:** ✅ entschieden

---

# 0.2 — Neues Git-Projekt initialisieren

## Ziel

Ein sauberes lokales Git-Repository ohne Legacy-Code und ohne vorweggenommene Anwendungsstruktur.

## Aufgaben

- [ ] Neuen Projektordner `ahk-ehrenamtsmanagement` anlegen.
- [ ] In den Projektordner wechseln.
- [ ] Neues Git-Repository initialisieren.
- [ ] `PROJECT_DESIGN.md` in den Projektroot übernehmen.
- [ ] Vor-Ort-Mockup als visuelle Referenz in den Projektroot übernehmen.
- [ ] Minimale `.gitignore` anlegen.
- [ ] Prüfen, dass keine lokalen Secrets oder Entwicklungsdaten versioniert werden.
- [ ] Ersten Baseline-Commit erstellen.

## Beispiel

```bash
mkdir ahk-ehrenamtsmanagement
cd ahk-ehrenamtsmanagement
git init
```

Die beiden Ausgangsdateien anschließend in den Projektroot kopieren.

### `.gitignore`

```gitignore
# Python
__pycache__/
*.py[cod]

# Optional local virtual environments
.venv/
venv/

# Local application data
instance/

# Environment / secrets
.env

# OS / editor noise
.DS_Store
```

Danach:

```bash
git add .
git status
git commit -m "Initialize AHK-Ehrenamtsmanagement project"
```

## Noch nicht tun

- keinen Remote erzwingen,
- kein GitHub/Gitea-Setup vorwegnehmen,
- kein Flask installieren,
- keine komplette spätere Verzeichnisstruktur leer vorbauen.

## Prüfergebnis

```bash
git status
```

soll einen sauberen Arbeitsbaum zeigen.

**Done wenn:** Projektroot + Source-of-Truth + Mockup + `.gitignore` sauber versioniert sind.

---

# 0.3 — Python 3.14 als Projektbasis festlegen

## Ziel

Die Anwendung wird bewusst auf Python 3.14 entwickelt.

## Aufgaben

- [x] Python-Major/Minor festgelegt: **3.14**
- [ ] Konkreten installierten `3.14.x`-Patchstand für die Projektumgebung verwenden.
- [ ] Sicherstellen, dass dieser Interpreter über `pyenv` verfügbar ist.

> Die konkrete Patchversion wird nicht in `TASKS.md` erfunden. Verwendet wird der bewusst ausgewählte/installierte Python-3.14-Patchstand.

## Prüfergebnis

```bash
pyenv versions
```

zeigt einen geeigneten Python-3.14-Interpreter.

**Done wenn:** Python 3.14 lokal über pyenv bereitsteht.

---

# 0.4 — Projekt-Virtualenv mit pyenv-virtualenv anbinden

## Ziel

Das Projekt besitzt eine eigene isolierte Python-Umgebung und aktiviert sie projektbezogen über `.python-version`.

## Voraussetzung

`pyenv` und `pyenv-virtualenv` funktionieren auf dem Entwicklungsrechner bereits und wurden mehrfach getestet. Die globale Bash-Konfiguration wird deshalb in dieser Phase **nicht erneut umgebaut**.

## Aufgaben

- [ ] Virtualenv für das Projekt auf Basis des gewählten Python-3.14-Interpreters erzeugen.
- [ ] Environment-Name: **`ahk-ehrenamtsmanagement`**
- [ ] Environment im Projektroot mit `pyenv local` zuweisen.
- [ ] Prüfen, dass `.python-version` entstanden ist.
- [ ] `.python-version` versionieren.
- [ ] Prüfen, dass `python` tatsächlich aus dem Projekt-Environment kommt.

## Beispiel

`<PYTHON_3_14_X>` durch die tatsächlich verwendete pyenv-Version ersetzen:

```bash
pyenv virtualenv <PYTHON_3_14_X> ahk-ehrenamtsmanagement
pyenv local ahk-ehrenamtsmanagement
```

Prüfen:

```bash
python --version
which python
pyenv version
```

## Erwartung

- `python --version` zeigt Python 3.14.x.
- `pyenv version` zeigt `ahk-ehrenamtsmanagement`.
- `.python-version` liegt im Projektroot.

## Prüfergebnis

**Done wenn:** Das Projekt verwendet automatisch sein eigenes pyenv-virtualenv.

---

# 0.5 — Minimale Python-Abhängigkeiten einführen

## Ziel

Runtime- und Development-Abhängigkeiten werden von Beginn an getrennt gepflegt.

## Entscheidungen

- [x] Runtime-Abhängigkeiten: `requirements.txt`
- [x] Development-/Test-Abhängigkeiten: `requirements-dev.txt`
- [x] Entwicklungsdatei bindet Runtime-Abhängigkeiten mit `-r requirements.txt` ein.

## Aufgaben

- [ ] `requirements.txt` anlegen.
- [ ] Nur Flask als erste Runtime-Abhängigkeit eintragen.
- [ ] `requirements-dev.txt` anlegen.
- [ ] `requirements.txt` darin referenzieren.
- [ ] `pytest` als erste Development-Abhängigkeit eintragen.
- [ ] Development-Abhängigkeiten im aktiven pyenv-Environment installieren.
- [ ] Keine späteren Pakete vorsorglich hinzufügen.

### `requirements.txt`

```text
Flask
```

### `requirements-dev.txt`

```text
-r requirements.txt

pytest
```

Installation:

```bash
python -m pip install -r requirements-dev.txt
```

## Konvention

Für Paketbefehle bevorzugen wir:

```bash
python -m pip ...
```

statt eines unqualifizierten `pip ...`, damit eindeutig der Paketmanager des aktiven Python-Interpreters verwendet wird.

## Prüfergebnis

```bash
python -c "import flask; print(flask.__version__)"
python -m pytest --version
```

Beide Befehle müssen funktionieren.

**Done wenn:** Flask und pytest im Projekt-Environment verfügbar sind und die Abhängigkeiten getrennt dokumentiert sind.

---

# 0.6 — Minimale Flask-App mit App Factory bauen

## Ziel

Die erste Anwendung startet über eine Flask App Factory und besitzt einen eigenen Core-Blueprint für den Healthcheck.

## Architekturentscheidung

`/health` wird **nicht** direkt in `app/__init__.py` definiert.

Stattdessen erhält die Betriebsinfrastruktur einen kleinen eigenen Core-Bereich:

```text
app/
├── __init__.py
└── core/
    ├── __init__.py
    └── health/
        ├── __init__.py
        └── routes.py
```

Die Factory baut die App zusammen; der Blueprint besitzt die Route.

## Aufgaben

- [ ] Verzeichnis `app/core/health/` anlegen.
- [ ] notwendige `__init__.py`-Dateien anlegen.
- [ ] Health-Blueprint definieren.
- [ ] `/health`-Route definieren.
- [ ] `create_app()` in `app/__init__.py` implementieren.
- [ ] Health-Blueprint in der Factory registrieren.
- [ ] Flask Development Server starten.
- [ ] `/health` manuell prüfen.

### Verzeichnisse anlegen

```bash
mkdir -p app/core/health

touch app/__init__.py
touch app/core/__init__.py
touch app/core/health/__init__.py
touch app/core/health/routes.py
```

### `app/core/health/__init__.py`

```python
from flask import Blueprint


bp = Blueprint("health", __name__)


from app.core.health import routes
```

### `app/core/health/routes.py`

```python
from app.core.health import bp


@bp.get("/health")
def health():
    return {"status": "ok"}, 200
```

### `app/__init__.py`

```python
from flask import Flask


def create_app():
    app = Flask(__name__)

    from app.core.health import bp as health_bp
    app.register_blueprint(health_bp)

    return app
```

## Starten

```bash
flask --app 'app:create_app' run --debug
```

In einem zweiten Terminal:

```bash
curl -i http://127.0.0.1:5000/health
```

## Erwartung

HTTP-Status:

```text
200 OK
```

JSON:

```json
{"status": "ok"}
```

Der Endpoint enthält keine personenbezogenen, sensiblen oder unnötigen Systeminformationen.

## Noch nicht tun

- keine Datenbank,
- keine Konfigurationsarchitektur vorwegnehmen,
- keinen `SECRET_KEY` erfinden,
- keine Templates,
- keinen Startseiten-Blueprint,
- keine Fachmodule.

**Done wenn:** `create_app()` startet und `/health` zuverlässig `200` liefert.

---

# 0.7 — Testbasis mit pytest aufsetzen

## Ziel

Die erste Funktion der App wird sofort automatisiert getestet.

## Aufgaben

- [ ] Verzeichnis `tests/` anlegen.
- [ ] `tests/test_health.py` anlegen.
- [ ] Flask-App über `create_app()` im Test erzeugen.
- [ ] Flask Test Client verwenden.
- [ ] HTTP-Status von `/health` prüfen.
- [ ] JSON-Antwort prüfen.
- [ ] Gesamte Testsuite mit `python -m pytest` ausführen.

### `tests/test_health.py`

```python
from app import create_app


def test_health_endpoint():
    app = create_app()
    client = app.test_client()

    response = client.get("/health")

    assert response.status_code == 200
    assert response.get_json() == {"status": "ok"}
```

Ausführen:

```bash
python -m pytest
```

## Erwartung

Mindestens:

```text
1 passed
```

**Done wenn:** Der Healthcheck automatisiert getestet wird und die komplette aktuelle Testsuite grün ist.

---

# 0.8 — Phase-0-Checkpoint

## Ziel

Einen klaren, reproduzierbaren Ausgangspunkt schaffen, bevor Datenbank, Core-Domänenmodelle oder Authentifizierung beginnen.

## Aufgaben

- [ ] Projektstruktur kontrollieren.
- [ ] `git status` prüfen.
- [ ] `.python-version` ist versioniert.
- [ ] `.env`, `instance/` und lokale Daten sind nicht versioniert.
- [ ] `python --version` zeigt Python 3.14.x.
- [ ] `pyenv version` zeigt das Projekt-Environment.
- [ ] `python -m pytest` ist grün.
- [ ] `/health` funktioniert manuell.
- [ ] Keine fachliche Funktionalität wurde vorweg implementiert.
- [ ] Phase-0-Stand committen.

Beispiel:

```bash
git add .
git status
git commit -m "Build minimal Flask application foundation"
```

## Erwartete Struktur am Ende von Phase 0

```text
ahk-ehrenamtsmanagement/
├── app/
│   ├── __init__.py
│   └── core/
│       ├── __init__.py
│       └── health/
│           ├── __init__.py
│           └── routes.py
├── tests/
│   └── test_health.py
├── PROJECT_DESIGN.md
├── PROJECT_DESIGN_VOR_ORT_MOCKUP.png
├── .gitignore
├── .python-version
├── requirements.txt
└── requirements-dev.txt
```

---

# Definition of Done — Phase 0

Phase 0 ist abgeschlossen, wenn alle folgenden Aussagen wahr sind:

- [ ] Das Projekt ist ein neuer Greenfield-Codebestand.
- [ ] Der technische Projektname ist `ahk-ehrenamtsmanagement`.
- [ ] Das Projekt liegt in einem eigenen Git-Repository.
- [ ] `PROJECT_DESIGN.md` ist im Repository die verbindliche Source of Truth.
- [ ] Das Vor-Ort-Mockup liegt als visuelle Referenz vor.
- [ ] Python 3.14 wird über pyenv verwaltet.
- [ ] Das Projekt nutzt ein eigenes `pyenv-virtualenv`.
- [ ] `.python-version` bindet die lokale Projektumgebung.
- [ ] Runtime- und Development-Abhängigkeiten sind getrennt.
- [ ] Flask wird über `create_app()` erzeugt.
- [ ] `/health` liegt in einem eigenen Core-Blueprint.
- [ ] `/health` liefert `200` und nur einen minimalen Status.
- [ ] pytest ist eingerichtet.
- [ ] Der Healthcheck besitzt einen automatisierten Test.
- [ ] Alle Tests sind grün.
- [ ] Der Stand ist sauber committed.
- [ ] Es wurden noch keine nicht entschiedenen Architekturdetails vorweggenommen.

---

# Danach

Nach Phase 0 wird **nicht automatisch weiterimplementiert**.

Die nächsten Phasen werden zuerst gemeinsam anhand von `PROJECT_DESIGN.md` durchgesprochen. Offene Produkt- oder Betriebsentscheidungen werden ausdrücklich geklärt, bevor daraus Aufgaben entstehen.
