# 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 `` durch die tatsächlich verwendete pyenv-Version ersetzen: ```bash pyenv virtualenv 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.