tbh/breadcrumb-the-shire
1
0
Fork 0
forked from fa/breadcrumb-the-shire
Code Pull Requests Activity
Files
16fe1b0db3588faec2d67803bfbed8de87536d90
breadcrumb-the-shire/docs/reference-konventionen.md
fs 545bcc789b docs: replace ASCII umlaut fallbacks with proper äöüß across all .md 
Most German docs were written with `ue`/`ae`/`oe`/`ss` ASCII fallbacks
(`fuer`, `aenderung`, `koennen`, `gemaess`) — relic from older toolchain
constraints. Replaced 237 occurrences across 38 .md files with proper
umlauts and ß so the docs read naturally.

Substitutions are constrained to plain prose: fenced code blocks
(```...```), inline code spans (`...`), markdown link targets `[..](..)`,
and HTML comments are preserved verbatim. Path references like
`docs/howto-erste-aenderung.md` keep their original (umlaut-replaced)
filenames — only the surrounding prose is normalised.

Tool: bin/fix-md-umlauts.py (idempotent — no-op on already-clean files).
Re-runnable if ASCII fallbacks creep back in via copy-paste.

Doc-link-check + doc-drift-check stay green.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-04-29 09:57:22 +02:00

3.7 KiB
Raw Blame History

Konventionen (kurz und verbindlich)

Letzte Aktualisierung: 2026-03-24

1) Code

  • Kleine, fokussierte Änderungen statt Misch-Commits.
  • Kein toter Code, keine ungenutzten Helpers.
  • ASCII als Standard, Unicode nur wenn Datei es bereits nutzt.

2) Schichten

  • SQL nur in core/Repository/**.
  • Fachlogik nur in core/Service/**.
  • pages/** bleibt dünn: Input, Auth/AuthZ, Service-Aufruf, Response.
  • Neue Domain-Logik als Instanz-Service mit Factory-Verdrahtung.
  • Service-Instanzen in Actions/Helpern nur via app(Foo::class).
  • new ...Factory() nur im Composition Root (web/index.php + core/App/registerContainer.php) oder in *Factory.php.
  • In core/Service/** außerhalb von *Factory.php keine direkten new ...Factory(), new ...Service(), new ...Gateway() oder new ...Repository().
  • Alte Service-Helper (accessServicesFactory(), userServicesFactory() usw.) nicht mehr verwenden.
  • pages/**/data().php nur GET (gridRequireGetRequest()), Query-Normalisierung ausschließlich über gridParseFilters(...).
  • Für jede Liste ein filter-schema.php im selben Verzeichnis; data().php, index().php und index(default).phtml verwenden dieses Schema.
  • Filter-Toolbar nur über renderGridFilterToolbar(...), keine manuellen Filter-Inputs/-Selects.
  • Client-Filterbindung nur über gridFiltersFromSchema(...) (kein inline filters: [...]).
  • Für Listen gilt Filter UX 2.0: Quick Search sichtbar, restliche Filter im Drawer, aktive Filter-Chips.
  • Search-only-Listen (nur Quick Search) verwenden keinen Drawer und bleiben im Live-Modus.
  • data-filter-overflow, data-filter-toggle und data-toolbar-toggle sind Legacy und in Listen-Templates nicht mehr erlaubt.
  • Listen-IDs nur als CSV-Parameter mit pluralem Key (*_ids), keine Alias-Fallbacks.

3) Autorisierung

  • Nur zentrale Policy-Abilities nutzen.
  • Keine verteilten userHas(...)-Checks als Hauptlogik.
  • Tenant-Scope nicht in Templates oder JavaScript nachbauen.

4) API

  • UUID-first für externe Ressourcen.
  • Interne IDs nicht nach außen geben.
  • Fehlerantworten einheitlich halten (ok, request_id, error_code, details; kein Legacy-error/errors).
  • OpenAPI bei jeder API-Änderung im selben Merge aktualisieren.

5) Frontend

  • Templates nur für Rendering.
  • UI-Texte über t('...').
  • Strukturregeln in /docs/reference-frontend-css.md und /docs/reference-frontend-javascript.md.
  • Runtime-Komponenten nur über Lifecycle-Contract (init(root, config) + destroy()), ohne komponenteneigenen Auto-Init.
  • Host-gebundene Runtime-Komponenten über data-app-component markieren; nur echte Global-Utilities ohne Host als runtime-global registrieren.

7) Module

  • Namespace: MintyPHP\Module\<Name>\* — nie Core-Namespaces (MintyPHP\Service\*, MintyPHP\Repository\*).
  • Verzeichnis: modules/<id>/lib/Module/<Name>/ (Service, Repository, Providers, Support).
  • Session-Keys: Prefix module.<id>.*.
  • UI-Integration nur über Plattform-Slots (aside.tab_panel, topbar.right_item, layout.head_style, runtime.component, etc.).
  • Kein Modul-spezifisches Markup in Core-Templates.
  • Tests: modules/<id>/tests/ (werden von phpunit.xml automatisch entdeckt via modules/*/tests).
  • Modul-Actions importieren nie OperationsAuthorizationPolicy::ABILITY_* — eigene Policy nutzen.
  • Manifest-Contract: /docs/reference-module-manifest-contract.md.

8) Mindestchecks vor Merge

  • docker compose exec php vendor/bin/phpunit
  • docker compose exec php vendor/bin/phpstan analyse -c phpstan.neon --no-progress
  • bei Modul-/Manifest-Änderungen: docker compose exec php php bin/console module:sync
  • bei JS-Änderungen: Browser-Smoke mit DevTools-Console (keine JS-Errors)
View Git Blame Copy Permalink