Vault/VAULT/hinunher/TASKS_Phase0.md

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

• Produktname: AHK-Ehrenamtsmanagement
• Technischer Name: ahk-ehrenamtsmanagement
• Greenfield-Neustart statt Legacy-Migration
• Lokale Shell: Bash
• Entwicklungsbetriebssystem: EndeavourOS / Arch Linux
• Python-Serie: 3.14
• Python-Versionierung: pyenv
• 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

mkdir ahk-ehrenamtsmanagement
cd ahk-ehrenamtsmanagement
git init

Die beiden Ausgangsdateien anschließend in den Projektroot kopieren.

.gitignore

# Python
__pycache__/
*.py[cod]

# Optional local virtual environments
.venv/
venv/

# Local application data
instance/

# Environment / secrets
.env

# OS / editor noise
.DS_Store

Danach:

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

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

• 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

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:

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

Prüfen:

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

• Runtime-Abhängigkeiten: requirements.txt
• Development-/Test-Abhängigkeiten: requirements-dev.txt
• 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

Flask

requirements-dev.txt

-r requirements.txt

pytest

Installation:

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

Konvention

Für Paketbefehle bevorzugen wir:

python -m pip ...

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

Prüfergebnis

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:

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

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

from flask import Blueprint


bp = Blueprint("health", __name__)


from app.core.health import routes

app/core/health/routes.py

from app.core.health import bp


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

app/__init__.py

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

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

In einem zweiten Terminal:

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

Erwartung

HTTP-Status:

200 OK

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

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:

python -m pytest

Erwartung

Mindestens:

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:

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

Erwartete Struktur am Ende von Phase 0

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.