Files

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.9 KiB

Raw Blame History

Globale Suche erweitern

Letzte Aktualisierung: 2026-02-21

Diese Doku erklärt, wie neue Entitäten sauber in die globale Suche integriert werden.

Überblick

Es gibt zwei Suchausgaben mit derselben Datenquelle:

Aside-Preview (admin/search/data)
- zeigt je Resource Count + bis zu 5 Preview-Einträge.
Vollseite Suche (search/data -> /search)
- zeigt gemischte Trefferliste über alle Resources.

Die zentrale Fassade liegt in:

/lib/Support/SearchConfig.php

Die eigentliche Logik ist in Provider aufgeteilt:

/lib/Support/Search/SearchSqlResourceProvider.php
/lib/Support/Search/SearchUiMetaProvider.php
/lib/Support/Search/SearchItemMapperProvider.php
/lib/Support/Search/SearchSpecialResourceProvider.php
/lib/Support/Search/SearchQueryNormalizer.php

Relevante Dateien

/lib/Support/SearchConfig.php
- stabile Orchestrierungs-Fassade (kompatible Methoden nach außen)
/lib/Support/Search/SearchSqlResourceProvider.php
- Resource-Definitionen (SQL + Permission + Label) + Tenant-Filter
/lib/Support/Search/SearchUiMetaProvider.php
- URL- und Icon-Mapping pro Resource-Key
/lib/Support/Search/SearchItemMapperProvider.php
- Mapping SQL-Row -> Preview-/Result-Item
/lib/Support/Search/SearchSpecialResourceProvider.php
- Spezialressourcen (docs, hotkeys)
/lib/Support/Search/SearchQueryNormalizer.php
- Query-Normalisierung für LIKE/Score
/pages/admin/search/data().php
- Aside-Preview API (Counts + Preview)
/pages/search/data().php
- Volltext-Treffer API
/templates/partials/app-main-aside.phtml
- Sichtbarer Eintrag im Such-Panel (data-search-key=...)
/web/js/components/app-global-search.js
- Render-Logik (generisch; meist keine Anpassung nötig)
/lib/Service/Docs/DocsCatalogService.php
- Zentrale Katalog-/Anchor-Logik für Entwicklerdoku (Single Source of Truth)

Standard-Vorgehen für neue Resource

1) Resource in `SearchSqlResourceProvider::resources()` anlegen

Neue Struktur mit:

key (z. B. scheduled-jobs)
label (übersetzbar via t(...))
permission (z. B. PermissionService::JOBS_VIEW)
countSql + countParams
previewSql + previewParams
resultSql + resultParams

Regeln:

SQL immer mit ... like ? escape '\\'.
Bei tenant-sensitiven Entitäten {{tenantFilter}} nutzen und in SearchSqlResourceProvider::tenantScopeFilters() ergänzen.
Preview-Query immer mit limit ?.

2) URL-/Icon-/Mapping ergänzen

SearchUiMetaProvider::iconForKey() erweitern
SearchUiMetaProvider::listUrl() erweitern
SearchItemMapperProvider::mapPreviewItem() ergänzen (falls Spezialformat nötig)
SearchItemMapperProvider::mapResultItem() ergänzen (falls Spezialformat nötig)

Ziel:

Preview und Volltreffer sollen sprechende Labels zeigen.
URLs sollen direkt auf sinnvolle Zielseiten gehen.

3) Eintrag im Aside-Search-Panel anlegen

In /templates/partials/app-main-aside.phtml:

<li data-search-key="..." data-search-base="..."> ergänzen
Anzeige per Permission guarden (z. B. $canViewJobs)

Wichtig:

data-search-key muss exakt dem key in SearchConfig entsprechen.

4) i18n prüfen

Neue Labels in:

/i18n/default_de.json
/i18n/default_en.json

Sicherheits- und Qualitätsregeln

Permission in SearchConfig setzen, nicht nur im Aside.
Tenant-Scope für tenant-bezogene Daten nicht vergessen.
Keine sensiblen Daten im Preview-Label.
Bei optionalen Modulen nur dann Resource aktivieren, wenn Schema vorhanden ist (oder Migration als Pflicht voraussetzen).

Kurzes Beispiel: `scheduled-jobs`

Integration umfasst:

Resource in SearchSqlResourceProvider::resources()
Mapping auf admin/scheduled-jobs/edit/{id}
Icon bi-calendar-check
Aside-Search-Item mit data-search-key="scheduled-jobs"
Permission jobs.view

Doku-Resource (`docs`) im System

Die Entwicklerdoku ist als eigene Search-Resource integriert:

Key: docs
Permission: docs.view
Quelle: docs/*.md (über DocsCatalogService, kein openapi.yaml)
Aside: eigener Block Documentation mit Count + Preview
Vollsuche: Treffer vom Typ Documentation
Ziel-URLs: admin/docs/{slug}#anchor (direkter Abschnitt)