hinunher hinzugefuegt

2026-08-17 10:54:37 +02:00 · 2026-08-17 10:54:37 +02:00 · 8202d64c13
commit 8202d64c13
parent ef9772fd7f
3 changed files with 3028 additions and 0 deletions
--- a/VAULT/hinunher/PROJECT_DESIGN.md
+++ b/VAULT/hinunher/PROJECT_DESIGN.md
--- a/VAULT/hinunher/PROJECT_DESIGN_VOR_ORT_MOCKUP.png
+++ b/VAULT/hinunher/PROJECT_DESIGN_VOR_ORT_MOCKUP.png
--- a/VAULT/hinunher/TASKS_Phase0.md
+++ b/VAULT/hinunher/TASKS_Phase0.md
@ -0,0 +1,538 @@
 # 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.