fa/breadcrumb-the-shire
1
0
Fork 1
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity
Files
25370a1a5543c222501c171ed8444f7c4befcaf5
breadcrumb-the-shire/docs/konventionen.md
fs 25370a1a55 add composer-unused, comprehensive docs, and project restructure 
- Add icanhazstring/composer-unused as dev dependency for dependency hygiene checks
- Add German documentation (docs/) covering architecture, conventions, workflows, and developer checklists
- Add API layer (ApiAuth, ApiBootstrap, ApiResponse), audit, scheduler, custom fields, and SSO services
- Add Microsoft OIDC SSO, API token management, and user lifecycle features
- Add swagger-ui vendor integration and OpenAPI spec
- Add production Docker setup and bin/ scripts
- Update composer dependencies, config, templates, and frontend assets throughout

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-02-22 15:27:35 +01:00

4.5 KiB
Raw Blame History

Konventionen

Letzte Aktualisierung: 2026-02-22

Diese Regeln sind projektweit verbindlich, um Lesbarkeit und Wartbarkeit stabil zu halten.

1) Allgemein

  • ASCII als Standard, außer bestehende Datei nutzt bereits Unicode.
  • Keine toten Pfade/Codezweige einbauen.
  • Wiederholung lieber zentralisieren (Partial/Helper/Utility) als kopieren.
  • Kleine, fokussierte Commits/Changesets bevorzugen.

2) PHP-Schichten

Repository

  • Enthalten SQL und Filterlogik.
  • Keine HTTP-/Session-/Render-Logik.
  • Prepared Statements und bestehende Query-Utilities nutzen.

Service

  • Geschäftsregeln, Validierung, Orchestrierung.
  • Keine HTML-Ausgabe.
  • Keine direkten View-Annahmen.
  • Bei globalen Settings bleibt DB die Quelle (SettingService); Datei-Cache nur gezielt für appSetting(...).

Action (pages/**.php)

  • Request lesen, Zugriff prüfen, Service aufrufen, Variablen für View setzen.
  • Redirects/Flash-Messages hier zentral steuern.

Views (*.phtml)

  • Reines Rendering.
  • Keine DB-Calls.
  • HTML escapen (e(...)) außer bewusst gewünscht.

3) UI-Konventionen

Edit-Seiten

  • Einheitliche Titelzeile mit /templates/partials/app-details-titlebar.phtml.
  • In der Titelzeile nur Primäraktionen halten (typisch: Save, Save & close).
  • Sekundäraktionen nicht im Drei-Punkte-Menü verstecken, sondern im Aside als einklappbarer Block Actions über /templates/partials/app-details-aside-actions.phtml.
  • Partial-Naming klar trennen:
    • linkes Haupt-Aside: app-main-aside*
    • rechtes Details-Aside: app-details-aside*
  • Tab-Reihenfolge:
    • erster Tab Master data
    • später Visibility
    • optional letzter Tab Danger zone
  • Statusfeld über /templates/partials/app-visibility-status-field.phtml.
  • Delete-Aktion über /templates/partials/app-danger-zone-delete-field.phtml.
  • Aside-Metadaten über:
    • /templates/partials/app-details-aside-audit.phtml
    • /templates/partials/app-details-aside-ids.phtml
  • Tenant-Zusatzfelder:
    • Definitionen werden im Tenant-Tab Custom fields über eigene POST-Actions gepflegt (nicht über Tenant-Hauptsave).
    • field_key wird nicht im UI gepflegt; serverseitig aus Label erzeugt und tenant-weit eindeutig gehalten.
    • is_filterable nur für select, multiselect, boolean, date anbieten.
    • User-Werte werden im User-Tab Custom fields tenantweise gruppiert gerendert.
    • User-Zusatzfelder sind optional; keine Pflichtvalidierung in V1.

Listen

  • Grid.js als Standard.
  • Filter/Toolbar konsistent halten.
  • Aktionsspalten nur wenn wirklich nötig; sonst Double-Click/Row-Action nutzen.
  • Dynamische Address-Book-Filter für Zusatzfelder folgen festen Parametern:
    • cf_<definition_uuid> (scalar/select/bool)
    • cfm_<definition_uuid> (multiselect als CSV)
    • cfd_<definition_uuid>_from|to (date range)

4) CSS

  • Prefix app- für eigene Klassen/Dateien.
  • Vendor-Anpassungen in /web/css/vendor-overrides.
  • Layering über /web/css/app-layers.css.
  • Theme-/Contrast-Werte über zentrale Variablen in /web/css/base.

5) JavaScript

  • Struktur:
    • core/ für Basismodule
    • components/ für wiederverwendbare UI-Module
    • pages/ für seitenspezifische Logik
  • Initialisierung zentral in app-init.js bzw. app-login-init.js.
  • Defensive DOM-Checks (Element kann auf manchen Seiten fehlen).
  • Keine Business-Logik im Frontend verstecken.

6) i18n

  • Alle sichtbaren UI-Texte über t('...').
  • Übersetzungs-Keys in i18n/default_de.json und i18n/default_en.json pflegen.
  • Test nutzen: tests/I18n/TranslationKeysTest.php.

7) Qualitätssicherung

Vor Merge mindestens:

  • PHPUnit
  • PHPStan
  • ESLint (web/js)
  • Betroffene Kern-Userflows manuell testen

Checkliste siehe: /docs/entwickler-checkliste.md

Dependency-Hygiene (periodisch, nicht bei jedem Commit)

Ungenutzte Composer-Pakete prüfen:

docker compose exec php vendor/bin/composer-unused

Ausführen bei: Feature-Entfernung, größerem Refactoring oder vor Releases. Pakete die fälschlicherweise als unused gemeldet werden (z.B. dynamisch geladen), können in composer.json unter extra.unused ignoriert werden.

8) Settings-Konvention

  • Neue Settings immer zuerst sauber im SettingService modellieren (Validierung + Read/Write).
  • Nur dann in SettingCacheService::update(...) aufnehmen, wenn der Key wirklich über appSetting(...) im Hot Path genutzt wird.
  • Keine Sicherheits-/Integrationssettings (SMTP, SSO-Secrets, API-Policies) als Pflicht in den Datei-Cache drücken.
  • Bei manuellen DB-Änderungen an gecachten Keys den Cache gezielt aktualisieren (z. B. über Settings-Save-Flow).
Reference in New Issue View Git Blame Copy Permalink