Merge pull request 'Fix #43: CONTRIBUTE.md und Setup-Skript für Mitwirkende' (#45) from fds2610-bot/Finanzmanager:main into main

Reviewed-on: https://codeberg.org/fds2610/Finanzmanager/pulls/45

CONTRIBUTE.md

@@ -0,0 +1,166 @@
+# Mitmachen
+
+## Disclaimer: VIBE Coding ist ausdrücklich erlaubt
+
+Dieses Projekt ist mit intensivem Einsatz von LLMs entstanden – Architektur,
+Implementierung, Tests und Dokumentation liefen zu einem großen Teil über
+Claude Code. Das ist kein Betriebsunfall, sondern bewusste Arbeitsweise. Wer
+hier mitmachen möchte, muss also keine Glaubensfrage klären: Ob eine Änderung
+per Hand geschrieben oder mit einem Coding-Agenten erarbeitet wurde, spielt für
+die Aufnahme keine Rolle. Wichtig ist, was am Ende im PR steht – nachvollziehbar,
+getestet, den Leitlinien unten folgend.
+
+## Leitlinien
+
+Diese drei Punkte sind die grundsätzliche Haltung des Autors und für dieses
+Projekt bindend. Mitwirkende dürfen fachlich anderer Meinung sein – an diesen
+Leitplanken selbst ändert das nichts.
+
+1. **FOSS – Open Source first.** Der Code enthält keine proprietären
+   Bestandteile. So, wie er in diesem Repository liegt, ist er vollständig
+   nutzbar – ohne versteckte Abhängigkeit von einem externen Dienst, einer
+   kostenpflichtigen Lizenz oder einer geschlossenen Komponente.
+2. **Datensparsamkeit.** Wer die Anwendung betreibt, hat jederzeit maximale
+   Transparenz darüber, welche Daten verarbeitet werden. Es gibt keine
+   Telemetrie und keine Übermittlung von Nutzdaten an die Autoren dieses
+   Repos. Werden Daten irgendwohin verschickt, die der Nutzer nicht selbst
+   konfiguriert hat, gilt das als Security-Bug mit höchster Priorität.
+3. **Security.** Das Modul soll jederzeit dem Stand der Technik entsprechen.
+   Gemeldete Sicherheitslücken werden mit oberster Priorität behoben. Da es
+   sich dabei um vertrauliche Informationen handelt: **bitte nicht als
+   öffentliches Issue melden**, sondern direkt per E-Mail an
+   [fds2610@sonnengetrock.net](mailto:fds2610@sonnengetrock.net).
+
+## Wie mithelfen?
+
+Damit ein Beitrag wirklich ankommt, bitte einen der folgenden Wege nutzen:
+
+1. Ein Issue auf [Codeberg](https://codeberg.org/fds2610/Finanzmanager/issues)
+   anlegen – als **BUG** oder **FEATURE**.
+2. Einen Pull Request aus einem eigenen Fork erstellen.
+3. Eine E-Mail an [fds2610@sonnengetrock.net](mailto:fds2610@sonnengetrock.net).
+
+Besonders willkommen ist Unterstützung bei:
+
+- **Dokumentation** (kann immer verbessert werden)
+- **Übersetzungen**
+- **Bugfixes**
+- **Feature-Umsetzungen**
+
+Aktuell review ich jeden Pull Request persönlich. Das ist bei wachsendem
+Interesse möglicherweise irgendwann ein Flaschenhals – dann werde ich mir
+etwas überlegen. Bis dahin: etwas Geduld beim Review einplanen.
+
+Fachbegriffe im Code und in der Oberfläche folgen bewusst dem Original
+(Lexware FinanzManager) und bleiben deutsch – siehe die Begriffsliste in
+[`CLAUDE.md`](CLAUDE.md). Neue Wortschöpfungen oder englische Entsprechungen
+bitte vermeiden.
+
+## Entwicklungsumgebung aufsetzen
+
+Das Setup ist bewusst schlank gehalten: Auf dem Host werden nur **Docker**,
+**Git** und optional **Claude Code** benötigt – alles Projektspezifische läuft
+in Containern. Kein lokales PHP, kein Composer, kein MariaDB auf dem Host.
+
+Wer alle Schritte auf einmal ausführen will, nutzt das Setup-Skript:
+
+```bash
+./dev-setup.sh
+```
+
+Es fragt nichts nach, was sich per Flag oder Umgebungsvariable vorgeben lässt
+(siehe `./dev-setup.sh --help`), und lässt sich beliebig oft erneut ausführen.
+Im Folgenden die einzelnen Schritte, die das Skript automatisiert.
+
+### 0. Voraussetzungen auf dem Host
+
+Nur was zwingend nötig ist, um überhaupt Container starten und Code verwalten
+zu können:
+
+- **Docker** (inkl. Compose-Plugin)
+- **Git**
+- optional **Claude Code**, wenn mit einem Coding-Agenten gearbeitet werden
+  soll
+
+Alles andere – PHP, Composer, MariaDB, Node/Playwright für die E2E-Tests –
+bleibt in Containern gekapselt.
+
+### 1. Fork, Remotes und Zugangsdaten
+
+Dieses Repository arbeitet mit zwei Remotes: dem persönlichen Fork (`origin`,
+wohin gepusht wird) und dem Upstream-Repository (`upstream`, von dem gezogen
+wird):
+
+```bash
+git clone https://codeberg.org/<dein-fork-account>/Finanzmanager.git
+cd Finanzmanager
+git remote add upstream https://codeberg.org/fds2610/Finanzmanager.git
+git fetch upstream
+```
+
+Für Pull Requests reicht ein persönliches [Zugriffs-Token](https://codeberg.org/user/settings/applications)
+mit Schreibrechten auf den eigenen Fork. Wer die Entwicklung automatisiert
+(z. B. über einen eigenen Bot-Account, wie es dieses Repo mit dem
+`fds2610-bot`-Account und dem Token in `CODEBERG_BOT_TOKEN` tut), legt dafür
+einen separaten Account an, forkt darüber das Upstream-Repo und authentifiziert
+sich mit dem Bot-Token statt dem persönlichen:
+
+```bash
+curl -s -X POST "https://codeberg.org/api/v1/repos/fds2610/Finanzmanager/forks" \
+  -H "Authorization: token $CODEBERG_BOT_TOKEN"
+
+git remote set-url origin "https://<bot-account>:${CODEBERG_BOT_TOKEN}@codeberg.org/<bot-account>/Finanzmanager.git"
+```
+
+Der eigentliche Beitrag – Issue, PR, E-Mail – läuft aber unabhängig davon,
+ob mit persönlichem Token oder Bot-Setup gearbeitet wird.
+
+### 2. Lokale Container starten
+
+```bash
+cp .env.example .env
+docker compose up -d
+```
+
+Die Anwendung ist danach unter **http://localhost:8000** erreichbar
+(Port aus `docker-compose.yml`). Migrationen spielt der Container beim Start
+automatisch ein, siehe `docker-entrypoint.sh`. Die Test-Suite:
+
+```bash
+./scripts/run-tests.sh
+```
+
+### 3. E2E-Tests (optional)
+
+Browser-Tests laufen über ein separates, generisches Playwright-Runner-Projekt
+(`e2e-runner`), das **nicht** Teil dieses Repos ist und standardmäßig unter
+`~/projects/e2e-runner` erwartet wird. Ist es nicht vorhanden, überspringt
+`tests/e2e/run.sh` die E2E-Tests automatisch mit einer Warnung – nichts
+schlägt deswegen fehl. Wer es einrichten möchte:
+
+```bash
+docker compose exec -u www-data php php scripts/e2e-benutzer.php   # Testnutzer anlegen
+tests/e2e/run.sh                                                    # läuft, sobald der Runner existiert
+```
+
+Details und abweichende Pfade/URLs stehen in `tests/e2e/README.md`.
+
+### 4. Claude Code auf dem Projektverzeichnis
+
+Claude Code wird im ausgecheckten Projektverzeichnis gestartet und liest
+[`CLAUDE.md`](CLAUDE.md) als verbindliche Betriebs- und Coding-Regeln – unter
+anderem: keine lokale Installation von PHP/Composer/MariaDB ohne Rückfrage,
+Tests immer im Container als `www-data`, SQL nur über `Database::…` mit
+Prepared Statements, deutsche Fachbegriffe. Darüber hinausgehende, riskante
+Aktionen (Force-Push, Löschen, Schema-Änderungen außerhalb von `migrations/`
+usw.) bestätigt Claude Code vor der Ausführung interaktiv – das entspricht dem
+Standard-Berechtigungsmodell von Claude Code und wurde für dieses Projekt
+nicht erweitert. Wer Claude Code stärker automatisiert einsetzen möchte (z. B.
+für wiederkehrende Aufgaben ohne Rückfrage), regelt das über die eigene
+`.claude/settings.json` – das ist eine persönliche Entscheidung und nicht Teil
+dieses Repos.
+
+## Lizenz
+
+MIT, siehe [`LICENSE`](LICENSE). Beiträge werden unter derselben Lizenz
+angenommen.

Changes.md

@@ -1,5 +1,19 @@
 # Änderungen
 
+## CONTRIBUTE.md und Setup-Skript für Mitwirkende (19.08.2026)
+
+`CONTRIBUTE.md` beschreibt, wie Beiträge ankommen (Issue, PR, E-Mail), welche
+Unterstützung gesucht wird und die drei bindenden Leitlinien des Projekts: FOSS,
+Datensparsamkeit und Security mit direktem Kontakt an fds2610@sonnengetrock.net
+für Sicherheitslücken. Vorangestellt ist ein Disclaimer, dass VIBE Coding
+ausdrücklich erlaubt ist – das Projekt selbst ist mit intensivem LLM-Einsatz
+entstanden (Feature #43).
+
+Neu ist außerdem `dev-setup.sh` im Repo-Root: richtet Docker (optional),
+Checkout mit Fork- und Upstream-Remote, lokale Container und optional die
+E2E-Testinfrastruktur ein. Zielverzeichnis, E2E-Setup und Docker-Installation
+lassen sich über Flags oder Umgebungsvariablen abweichend vom Default setzen.
+
 ## Kontoblatt: Typeahead für die Kategorie (19.08.2026)
 
 Die Kategorie ließ sich im Kontoblatt nur über eine lange Auswahlliste finden – bei vielen

README.md

@@ -130,6 +130,7 @@ wieder ein. Einzelheiten in `docs/import-export.md`.
 
 - `PLAN.md` – Projektplan mit allen Phasen
 - `CLAUDE.md` – Entwicklungsregeln
+- `CONTRIBUTE.md` – Mitmachen: Leitlinien, Wege für Beiträge, Entwicklungsumgebung
 - `Changes.md` – Änderungsprotokoll
 - `docs/stammdaten.md` – Konten, Kontengruppen, Kategorien, Klassen
 - `docs/buchungen.md` – Kontoblatt, Umbuchungen, Splitbuchungen, Salden

dev-setup.sh

@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+#
+# Richtet eine lokale Entwicklungsumgebung für den Finanzmanager ein:
+# Docker (optional), Zielverzeichnis mit den Git-Remotes (origin = eigener
+# Fork, upstream = fds2610/Finanzmanager), lokale Container und optional die
+# Infrastruktur für die E2E-Tests. Auf dem Host wird sonst nichts installiert
+# – PHP, Composer und MariaDB laufen ausschließlich in Containern.
+#
+# Beliebig oft erneut ausführbar.
+#
+#   ./dev-setup.sh [Optionen]
+#
+# Optionen (mit Default, alles auch als Umgebungsvariable setzbar):
+#   --verzeichnis PFAD   Zielverzeichnis für den Checkout
+#                         (WORKDIR, Default: ~/projects/Finanzmanager)
+#   --fork ACCOUNT       Codeberg-Account des eigenen Forks (FORK_ACCOUNT)
+#   --kein-e2e           E2E-Testsetup nicht mit einrichten (E2E_SETUP=nein)
+#   --keine-docker-installation
+#                        Docker nicht installieren, auch wenn es fehlt
+#                        (DOCKER_INSTALL=nein)
+#   -h, --help           Diese Hilfe anzeigen
+#
+# Beispiel:
+#   ./dev-setup.sh --verzeichnis ~/code/Finanzmanager --fork meinaccount
+
+set -euo pipefail
+
+WORKDIR="${WORKDIR:-$HOME/projects/Finanzmanager}"
+FORK_ACCOUNT="${FORK_ACCOUNT:-}"
+E2E_SETUP="${E2E_SETUP:-ja}"
+DOCKER_INSTALL="${DOCKER_INSTALL:-ja}"
+UPSTREAM_URL="https://codeberg.org/fds2610/Finanzmanager.git"
+
+melde() { printf '\n\033[1m▸ %s\033[0m\n' "$1"; }
+
+hilfe() {
+    sed -n '2,25p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'
+}
+
+while [ $# -gt 0 ]; do
+    case "$1" in
+        --verzeichnis) WORKDIR="$2"; shift 2 ;;
+        --fork) FORK_ACCOUNT="$2"; shift 2 ;;
+        --kein-e2e) E2E_SETUP=nein; shift ;;
+        --keine-docker-installation) DOCKER_INSTALL=nein; shift ;;
+        -h|--help) hilfe; exit 0 ;;
+        *) echo "Unbekannte Option: $1" >&2; hilfe; exit 1 ;;
+    esac
+done
+
+# ── 0. Docker und Git ────────────────────────────────────────────────────────
+melde "Voraussetzungen prüfen"
+
+if ! command -v git >/dev/null 2>&1; then
+    echo "Git fehlt und muss manuell installiert werden (siehe Distribution)." >&2
+    exit 1
+fi
+
+if ! docker compose version >/dev/null 2>&1; then
+    if [ "$DOCKER_INSTALL" = "ja" ]; then
+        echo "Docker/Compose-Plugin fehlt – Installation über get.docker.com."
+        curl -fsSL https://get.docker.com | sh
+        echo "Ggf. den aktuellen Benutzer zur Gruppe 'docker' hinzufügen und neu anmelden:"
+        echo "  sudo usermod -aG docker \$USER"
+    else
+        echo "Docker/Compose-Plugin fehlt und --keine-docker-installation ist gesetzt." >&2
+        exit 1
+    fi
+else
+    echo "Docker vorhanden: $(docker compose version --short 2>/dev/null || echo ok)"
+fi
+
+# ── 1. Checkout mit Fork- und Upstream-Remote ───────────────────────────────
+melde "Repository unter $WORKDIR"
+
+if [ -d "$WORKDIR/.git" ]; then
+    echo "Vorhanden – kein erneuter Checkout."
+else
+    if [ -z "$FORK_ACCOUNT" ]; then
+        echo "Kein --fork angegeben: Checkout direkt aus dem Upstream-Repository."
+        echo "Für einen eigenen Beitrag vorher auf Codeberg forken und mit"
+        echo "'--fork <eigener-account>' erneut ausführen."
+        git clone "$UPSTREAM_URL" "$WORKDIR"
+    else
+        git clone "https://codeberg.org/$FORK_ACCOUNT/Finanzmanager.git" "$WORKDIR"
+    fi
+fi
+
+cd "$WORKDIR"
+git remote get-url upstream >/dev/null 2>&1 || git remote add upstream "$UPSTREAM_URL"
+git fetch upstream --quiet || true
+
+# ── 2. Lokale Container ─────────────────────────────────────────────────────
+melde "Container starten"
+
+[ -f .env ] || cp .env.example .env
+docker compose up -d
+
+melde "Migrationen"
+docker compose exec -T php php scripts/migrate.php
+
+echo "Anwendung erreichbar unter http://localhost:8000"
+
+# ── 3. E2E-Testsetup (optional) ─────────────────────────────────────────────
+if [ "$E2E_SETUP" = "ja" ]; then
+    melde "E2E-Testnutzer"
+    docker compose exec -u www-data -T php php scripts/e2e-benutzer.php || true
+    echo "E2E-Tests laufen über ein separates Runner-Projekt unter"
+    echo "~/projects/e2e-runner (nicht Teil dieses Repos). Fehlt es, überspringt"
+    echo "tests/e2e/run.sh die Tests automatisch mit einer Warnung."
+    echo "Details: tests/e2e/README.md"
+else
+    echo "E2E-Setup übersprungen (--kein-e2e)."
+fi
+
+# ── 4. Claude Code ───────────────────────────────────────────────────────────
+melde "Claude Code"
+echo "Im Verzeichnis '$WORKDIR' starten, z.B. mit: claude"
+echo "Die Betriebs- und Coding-Regeln stehen in CLAUDE.md und werden automatisch"
+echo "gelesen. Für weitergehende Automatisierung ohne Rückfragen die eigene"
+echo ".claude/settings.json anpassen (persönliche Entscheidung, nicht Teil des Repos)."
+
+melde "Fertig"