538 lines
12 KiB
Markdown
538 lines
12 KiB
Markdown
# 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.
|