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

# Lokale Entwicklung

Letzte Aktualisierung: 2026-03-18

## Ziel

Kompakter Tagesworkflow für Entwicklung, Tests und schema-nahe Änderungen.

## Start/Stop

```bash
docker compose up -d
docker compose down
```

Hinweis: `up -d` startet auch den Scheduler-Service.

Bei inkonsistentem Laufzeitverhalten:

```bash
docker compose restart php nginx
```

## Module-Sync

Nach Aenderungen an Modulen, Manifesten oder `APP_ENABLED_MODULES`:

```bash
docker compose exec php php bin/console module:sync
```

Dieser Befehl fuehrt automatisch aus: `migrate` → `permissions-sync` → `build` → `assets-sync`.

Falls `web/index.php` den Fehler "Module runtime is stale" wirft, ist der Sync noetig.

Alle verfuegbaren CLI-Kommandos: `php bin/console list` (siehe `/docs/reference-cli-commands.md`).

## Schema-Stand

- Basis-Schema + Seeds: `db/init/init.sql`
- Für Bestandsumgebungen: idempotente SQL-Updates in `db/updates/*.sql`

## Umsetzungsablauf

1. Requirement klären
2. Repository anpassen (SQL)
3. Service anpassen (Business-Regeln)
4. Action/Page anpassen
5. i18n ergänzen
6. Doku aktualisieren

## Pflichtchecks vor Commit

```bash
docker compose exec php vendor/bin/phpunit
docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
```

Bei Modul-/Manifest-Aenderungen zusaetzlich:

```bash
docker compose exec php php bin/console module:sync
```

Bei JS-Änderungen zusätzlich Browser-Smoke mit DevTools-Console (keine JS-Errors).

## Struktur-Gates (empfohlen)

```bash
(rg 'new\s+[^\s(]+Factory\(' lib/Service || true) | wc -l
(rg --glob '!**/*Factory.php' 'new\s+[^\s(]+(Service|Gateway|Repository)\(' lib/Service || true) | wc -l
(rg "\b(accessServicesFactory|directoryServicesFactory|userServicesFactory|authServicesFactory|tenantServicesFactory|settingServicesFactory|userRepositoryFactory|authRepositoryFactory|authGatewayFactory)\(" pages lib templates web || true) | wc -l
```

## API-spezifisch

- `docs/openapi.yaml` aktualisieren
- bei Bedarf `/docs/reference-api.md` ergänzen
- bei Security-Änderungen `/docs/explanation-sicherheitsmodell.md` aktualisieren

## Vertiefung

- `/docs/reference-entwickler-checkliste.md`
- `/docs/tutorial-04-architektur-request-flow.md`