breadcrumb-the-shire/docs/lokale-entwicklung.md

Lokale Entwicklung

Letzte Aktualisierung: 2026-02-21

Ziel

Pragmatischer Tages-Workflow für Entwicklung, Tests und Migrationen.

Start/Stop

docker compose up -d
docker compose down

Hinweis: docker compose up -d startet auch den Service scheduler (globaler Minutely-Runner).

Bei größeren Refactors oder merkwürdigem Laufzeitverhalten:

docker compose restart php nginx

Datenbank und Schema-Updates

• Basis-Schema + Seeds: db/init/init.sql
• Das Repo nutzt aktuell ein konsolidiertes Init-Schema (keine separaten Migrationsdateien in db/init/).
• Für Bestandsumgebungen Schema-/Permission-Änderungen als idempotentes SQL-Update in db/updates/*.sql bereitstellen und manuell ausführen.

Beispiel (bestehende Umgebung, SQL-Update manuell ausführen):

docker compose exec -T db sh -lc \
  'mariadb -u"$DB_USER" -p"$DB_PASS" "$DB_NAME" < /tmp/release-update.sql'

Typischer Implementierungsablauf

1. Requirement klären
2. Repository anpassen (SQL)
3. Service anpassen (Business-Regeln)
4. Action/Page anpassen
5. i18n-Keys ergänzen (i18n/default_de.json, i18n/default_en.json)
6. Doku anpassen (docs/*)

Pflicht-Checks vor Commit

docker compose exec php vendor/bin/phpunit
docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
npx eslint web/js

Optional gezielt:

docker compose exec php vendor/bin/phpunit tests/I18n/TranslationKeysTest.php

API-spezifisch

• OpenAPI aktualisieren: docs/openapi.yaml
• API-Quickref aktualisieren: docs/api.md
• Bei Security-Änderungen auch docs/sicherheitsmodell.md aktualisieren

Bei Unsicherheit

• Architektur zuerst lesen: /docs/architektur.md
• Sicherheitsregeln prüfen: /docs/sicherheitsmodell.md
• Abschluss immer gegen /docs/entwickler-checkliste.md