breadcrumb-the-shire/docs/erste-aenderung.md

Leitfaden für die erste Änderung

Letzte Aktualisierung: 2026-02-22

Ziel

Ein neuer Entwickler soll den ersten Change strukturiert und reproduzierbar umsetzen können.

Beispiel 1: Spalte in Admin-Liste ergänzen

Schrittfolge

1. Data-Endpoint erweitern (z. B. pages/admin/users/data().php)
2. Falls nötig: neue Repository-Methode ergänzen – je nach Typ:
   • Listenabfrage / Filterung / Paginierung → lib/Repository/User/UserListQueryRepository.php
   • Einzelnes Objekt lesen → lib/Repository/User/UserReadRepository.php
   • Schreiboperation → lib/Repository/User/UserWriteRepository.php
3. Grid-Spalte in pages/admin/<modul>/index(default).phtml ergänzen (z. B. pages/admin/users/index(default).phtml)
4. i18n-Key für Spaltennamen setzen
5. php -l + manueller UI-Test

Done-Kriterien

• Kein SQL in View-Dateien
• Neue Werte im Endpoint dokumentiert/benannt
• Sortierung und Mapping im Grid konsistent
• Bei neuen Filtern: Query-Param, Repository-Filter und Grid-State konsistent

Beispiel 2: API-Response erweitern

Schrittfolge

1. Endpoint in pages/api/v1/... anpassen (z. B. pages/api/v1/me/index().php oder pages/api/v1/users/show($id).php)
2. Permission- und Tenant-Scope-Prüfungen beibehalten
3. Optional Service/Repository ergänzen
4. docs/openapi.yaml aktualisieren
5. docs/api.md mit Beispiel aktualisieren
6. Bei neuen Berechtigungen: PermissionService + init.sql synchron halten, für Bestandsumgebungen idempotentes SQL-Update in db/updates/*.sql bereitstellen

Done-Kriterien

• Keine numerischen IDs exponieren, wenn UUID bereits Contract ist
• Fehlercodes konsistent (ApiResponse::error(...))
• Kein Body-Leak in Logs/Audit
• OpenAPI und tatsächlich gelieferte Response-Felder stimmen 1:1

Finaler Check

Vor PR/Merge diese Liste gegenprüfen:

• /docs/entwickler-checkliste.md