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

Leitfaden für die erste Änderung

Letzte Aktualisierung: 2026-02-24

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. Service-Auflösung in Action-Dateien nur über app(Foo::class) nutzen (kein new ...Factory() in pages/**)
6. In data().php: GET-only (gridRequireGetRequest()) und Grid-Querys über gridQueryLimitOffset()/gridQueryOrderDir() normalisieren
7. 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
• Instanziierungsstandard eingehalten (app(...), keine Legacy-Helper)

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, Instanziierung über app(...)/Factory-Standards
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