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

# Lokale Entwicklung

Letzte Aktualisierung: 2026-04-01

## Ziel

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

## First-Time Workflow

```bash
bin/dev init
```

`bin/dev init` ist nicht-destruktiv und fuehrt aus:

1. `.env` aus `.env.example` erstellen (falls fehlend)
2. `docker compose up --build -d`
3. `module:sync`
4. `doctor`

## Start/Stop

```bash
bin/dev up
bin/dev 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`).
Alle Dev-Orchestrator-Kommandos: `bin/dev --help`.

## 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\(' core/Service || true) | wc -l
(rg --glob '!**/*Factory.php' 'new\s+[^\s(]+(Service|Gateway|Repository)\(' core/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`