Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/.planning/ticket-docs/R-ADMIN1.md
T

16 KiB
Raw Blame History

R-ADMIN1 · Admin-Bereich: Befunde aus dem Staging-Audit vom 26.07.2026

Typ Dev (Fix-Serie)
Owner Raffael
Phase Querschnitt · Plattform-Admin
Cycle/Fenster 26.07.2026
Status in Arbeit — 21 von 67 eigenständigen Befunden erledigt (~31 %)
Plane noch nicht angelegt
Branch fix/admin-audit-20260726 (Worktree HiveGrid-Cloud-fix-admin-audit-20260726)

Was wir bauen

Behebung der Befunde eines vollständigen Klick-Audits des Admin-Bereichs auf staging-admin.hivegrid.de (erhoben 26.07.2026, Release b05b69964, Viewport 1018–1400 px, DE, Super-Admin-Sitzung). Der Auditbericht ist kein Roadmap-Ticket, sondern eine Fehlerliste mit Route, Element und Textstring je Befund.

Quelle: Auditbericht im Auftrag vom 26.07.2026. Er bricht in Kapitel 5 bei LAY-09 ab; die Kapitel 6 bis 8 fehlen (UI-01 verweist auf ein „Kapitel 8"). Was dort steht, ist in diesem Ticket nicht abgedeckt.

Definition of Done

P0 — Blocker (12/12 erledigt)

  • P0-01 Toter Sidebar-Link „Lead-Regeln" (/sales/settings/leads → 404)
  • P0-02 NaN € in der Tarif-Spalte auf /accounts/subscriptions
  • P0-03 1/NAN in der Pagination der drei /notifications-Listen
  • P0-04 Rohe HTML-Entities (Europe/Berlin, https://)
  • P0-05 Job-IDs in der Wire-Form …%3A… auf /jobs
  • P0-06 Stat-Karten ohne Zahl bei Wert 0 (7 Routen)
  • P0-07 Commit-Hash läuft aus der Release-Karte auf /deploys
  • P0-08 Falscher Seitentitel und Breadcrumb im ganzen /sales/settings/*-Zweig
  • P0-09 Falscher aktiver Sidebar-Eintrag — Teil 1 ist kein Defekt (/settings/security ist ein Unterpunkt von „Plattform-Admins", die Hervorhebung ist korrekt). Teil 2 („auf /settings kurzzeitig Feature-Flags aktiv") ist im Code nicht reproduzierbar: das Matching ist exakt und segmentweise, ohne Fallback auf die erste Route. Vermutlich ein Übergangszustand während der Navigation, verwandt mit P0-10.
  • P0-10 „Details" auf /jobs brauchte zwei Klicks
  • P0-11 Migrationsstatus las nicht aus der DB; /system zeigte leeren Release
  • P0-12 Zwei verschiedene 404-Seiten auf demselben Host

i18n und Copy (5/6 erledigt)

  • I18N-01 ASCII-Transliteration in 26 deutschen Strings + CI-Gate
  • I18N-02 Rohe Enum-Werte (Support-Status/Priorität/Quelle, Plan-Code, Trial-Badge, Provider-Auswahl)
  • I18N-03 Rohe Event-Keys als Checkbox-Label in /marketing-integrations
  • I18N-04 Deutsch/Englisch-Mix (Sales Workspace, Clients, Inbound, API Clients, Inbound Registrations, Failed)
  • I18N-05 Ansprache uneinheitlich (du/neutral/wir), drei Varianten desselben Begründungstexts — offen
  • I18N-06 Verwaiste Copy: /settings-Subline, „Profil"-Karte, Roadmap-Satz im Feature-Flag-Editor. Zwei Teile offen (siehe unten)

Design-System (0/9 erledigt — offen)

  • UI-01 Fünf Sub-Navigations-Patterns → eines. Bewusst als eigenes Ticket abgetrennt (Nutzer-Entscheidung 26.07.): betrifft ~15 Screens und Davids finale Optik, braucht eine Design-Entscheidung statt eines Fixes.
  • UI-02 Zwei PageHeader-Varianten
  • UI-03 Doppelte Breadcrumbs mit unterschiedlichen Wurzeln
  • UI-04 Button-Hierarchie zerfasert, Fremd-Blau neben Marke Gelb/Schwarz
  • UI-05 Zwei EmptyState-Komponenten, sechs Textmuster
  • UI-06 Trend-Semantik falsch (grüner Aufwärtspfeil auf „Kritisch")
  • UI-07 Versalien-Labels nur punktuell
  • UI-08 Icon-Vergabe (Dollar-Icon auf Mail-Kacheln, Doppelbelegungen)
  • UI-09 Pagination: doppelte 10-Option, Accessible Name 11, zweite Implementierung auf /audit

Layout und Responsive (0/9 erledigt — offen)

  • LAY-01 Badge überlagert Kachel-Überschrift (/dashboard, /accounts/billing)
  • LAY-02 identisch mit P0-07 — bereits erledigt
  • LAY-03 Tag anlegen / Feld anlegen abgeschnitten
  • LAY-04 Vor- und Nachname überlappen in /accounts/new
  • LAY-05 Override speichern rechts abgeschnitten
  • LAY-06 Tabellenköpfe überlappen in /sales/settings/pipelines
  • LAY-07 break-all zerlegt Wörter auf /jobs unter 1130 px
  • LAY-08 Spalten ohne Ellipse, /audit-Filterblock 450 px hoch
  • LAY-09 Ungruppierte Abo-Historie in einer Zelle bei „RheinMain Gebäudetechnik" (neun Zeilen Plan/Beendet-am ohne Gruppierung). Der Bericht bricht mitten in diesem Befund ab; die Beschreibung ist unvollständig.
  • LAY-09b Spaltenbreiten auf /accounts: die ID-Spalte (25-stellige CUID) frisst die Breite, die Plan-Spalte wird gequetscht. Trägt in Teil 2 dieselbe Nummer wie LAY-09, ist aber ein anderer Befund.
  • LAY-10 Horizontaler Scroll auf Seiten- statt Tabellenebene, dadurch scrollen Seitenkopf und Filterleiste mit weg (/audit, /accounts, /api/logs, /accounts/subscriptions, /jobs)
  • LAY-11 Icon-Rail als Sub-Navigation auf /feature-flags — steckt in UI-01
  • LAY-12 /accounts/:id ist eine Mega-Seite: 34 Feature-Zeilen mit je eigenem Speichern-Button, kein Dirty-State, Gefahrenbereich erst nach langem Scroll erreichbar
  • LAY-13 /select-tenant bricht die Admin-Shell (H1 doppelt, Versalien-Label)

Barrierefreiheit — Kapitel 6 des Berichts (0/10 erledigt)

  • A11Y-01 Glocken-Icon im Header ist ein toter Link. Verifiziert: SubframeAppShell setzt href={params.tenant ? … : "#"}; im Admin gibt es keinen Tenant-Parameter, also zeigt der Link immer auf #. Ziel: /notifications.
  • A11Y-02 Karten-Links ohne Accessible Name (/dashboard, /support, /accounts/billing)
  • A11Y-03 Verschachtelte interaktive Elemente (a > button) — dieselbe Ursache wie P0-10, dort für /jobs behoben, an sechs weiteren Stellen offen
  • A11Y-04 Formularfelder auf /admin-users ohne for/id-Verknüpfung
  • A11Y-05 Icon-only Submit-Buttons ohne aria-label (/audit, /api/logs, /admin-users)
  • A11Y-06 Modal-Close ohne Namen, Focus-Trap und Esc ungeprüft (Job-Detail)
  • A11Y-07 Pagination-Accessible-Name 11 — identisch mit UI-09
  • A11Y-08 Status nur über Farbe (/notifications/channels, /health, /deploys, Trendpfeile)
  • A11Y-09 Hover-only Navigation (Feature-Flags-Icon-Rail) — steckt in UI-01
  • A11Y-10 Sidebar ohne Gruppen-Semantik (~30 Einträge ohne role="group"/aria-labelledby)

Daten und Konsistenz — Kapitel 7 des Berichts (0/14 erledigt)

  • DATA-01 Derselbe Mandant zeigt drei Tarif-Wahrheiten: /accounts „Business", /accounts/billing business + Badge Trial, /accounts/:id „Plan: Keine" + Aktiv + trial. Wichtigster Befund aus Teil 2.
  • DATA-02 Plan ist ein Freitextfeld (Placeholder z. B. starter) — Ursache von DATA-01
  • DATA-03 Feature-Flag-Zähler widersprechen sich (Übersicht „2/2" vs. Liste „Alle (1)")
  • DATA-04 Flag-Name identisch mit Flag-Key
  • DATA-05 NaN und flächendeckend „Nicht verfügbar" auf /accounts/subscriptions — NaN-Teil mit P0-02 behoben, die leeren Zeitraum-Spalten sind offen
  • DATA-06 Audit-Akteur mischt Typen (Text Admin vs. rohe CUID)
  • DATA-07 Rohe technische IDs im UI (Rechnungs-Objekt-ID, Admin-ID, roher User-Agent)
  • DATA-08 Drei ID-Schemata für Mandanten in Routen (CUID, UUID, Slug)
  • DATA-09 Identische Initialen-Avatare auf /select-tenant
  • DATA-10 Identische Zeitstempel für Erstellt/Verarbeitet/Beendet im Job-Modal
  • DATA-11 Interne Pfade und Stacktraces ungefiltert im Job-Modal (file:///myapp/…)
  • DATA-12 /health zeigt „Branch: unknown", leere Kritisch-/Unklar-Kacheln — Kachel-Teil mit P0-06 behoben, Build-Metadaten offen
  • DATA-13 Seed-/Provider-Namen leaken („Hallo authentik", „authentik Default Admin", Zeile ohne Rollen-Badge, dauerhaft deaktivierter Button „Admin vorbereiten")
  • DATA-14 Rollen-Terminologie dreifach („Superadmin", „Superbenutzer", „Super Admin")

Informationsarchitektur — Kapitel 8 des Berichts (0/13 erledigt)

  • IA-01 Label ≠ Route ≠ H1 ≠ document.title ≠ Breadcrumb (Tabelle mit 7 Beispielen)
  • IA-02 document.title uneinheitlich — für /sales/settings/* mit P0-08 behoben, die übrigen Zweige offen
  • IA-03 Tote Route in der Sidebar — identisch mit P0-01, behoben
  • IA-04 ~30 Top-Level-Einträge, Sidebar-Scrollposition resettet bei jeder Navigation
  • IA-05 17 Routen nur über Karten oder Command-Palette erreichbar
  • IA-06 Command-Palette kennt eine Hierarchie, die die Sidebar nicht hat; 8 Einträge, nicht scrollbar, keine Volltextsuche
  • IA-07 Doppelte Wahrheiten: /health + /system, zwei Audit-Views, Telefonie-Settings zweimal, /sales/contacts vs. /sales/companies, drei Links auf /accounts/billing (einer als „Events öffnen")
  • IA-08 Geschwister-Seiten mit unterschiedlichem Funktionsumfang
  • IA-09 Falsche Gruppenzuordnung („Import und Export" unter Sales-Einstellungen)
  • IA-10 /kwp-contracts auf Top-Level, unverständlicher Beschreibungstext
  • IA-11 Zwei Produkte in einer Navigation (11 Sales-Routen im Plattform-Admin)
  • IA-12 Breadcrumb-Wurzel „Helpdesk" ohne Gegenstück in der Admin-Navigation. Präzisierung: der Begriff existiert als Sidebar-Label der Mandanten-App; im Admin heißt der Eintrag „Support". Der Kern des Befunds bleibt gültig.
  • IA-13 Einstellungen über fünf Orte verstreut

Herkunft und Grenzen der Befundliste

Der Bericht kam in zwei Teilen und ist in beiden Teilen abgebrochen; der erhebende Agent steht nicht mehr zur Verfügung, es kommt nichts nach.

Was fehlt:

  • Das Ende von LAY-09 in der Fassung aus Teil 1 (ungruppierte Abo-Historie bei „RheinMain Gebäudetechnik"). Teil 2 führt unter derselben Nummer einen anderen Befund (Spaltenbreiten und horizontaler Scroll) — beide sind hier als LAY-09 und LAY-09b geführt.
  • Kapitel 10 bis 13. Die Überschrift von Teil 2 kündigt sie an, geliefert ist bis Kapitel 9.4; die Redirect-Map bricht mitten in einer Zeile ab. Der Inhalt ist unbekannt und wird nicht rekonstruiert.
  • Die Kapitelnummerierung ist zwischen den Teilen verrutscht: Teil 1 verweist für das Navigations-Pattern auf „Kapitel 8", dort steht in Teil 2 die IA-Kritik.

Was der Audit methodisch nicht abgedeckt hat (unabhängig vom Abbruch, aus dem Kopf des Berichts selbst ableitbar):

  1. Kein Mobile. Erhoben nur bei 1018–1400 px. HiveGrid ist PWA-only (AD-17) mit mobile-first Monteur-Sichten; unter 768 px existiert kein einziger Befund.
  2. Nur eine Rolle. Alles als Super-Admin. Ob berechtigungsabhängige Einträge für schwächere Rollen ins 404 führen — der Fehlertyp aus P0-01 — ist ungeprüft.
  3. Keine Messung. Ladezeit, Bundle-Größe und echte Screenreader-Ausgabe sind nicht Teil des Berichts.

Diese drei Lücken werden nicht durch einen neuen Fließtext-Audit geschlossen, sondern über die vorhandenen wiederholbaren Gates (verify:a11y-coverage, Playwright + axe, Lighthouse, docs/route-inventory.md).

Umsetzungs-Notiz

2026-07-26 — 21 von 36 Befunden erledigt (~58 %), davon P0 vollständig.

Drei Commits auf fix/admin-audit-20260726:

Commit Inhalt
178c28961 P0-01, P0-02, P0-03, P0-04, P0-05, P0-06, P0-08, P0-12
9398d1826 P0-07, P0-10, P0-11
ea88bc139 I18N-01, I18N-02, I18N-03, I18N-04, I18N-06 (teilweise)

Jeder Befund ist an der Ursache behoben, nicht pro Route:

  • P0-04 lag nicht an den zwei gemeldeten Strings, sondern an i18nConfig: i18next escapte Interpolationswerte, obwohl React jeden Textknoten selbst escaped. Jeder Wert mit Slash war betroffen. Fix in packages/i18n/src/index.ts.
  • P0-02 entsteht, weil SubscriptionPrice.price ein Prisma-Decimal ist und die Loader-Serialisierung es als Objekt überträgt; Number(...) ergibt NaN. /accounts war unauffällig, weil dort ein Service serverseitig konvertiert. Fix: Normalisierung im Loader plus —-Fallback in den Formattern.
  • P0-06 lag an den generierten Subframe-Guards {value ? … : null}, die die Zahl 0 verwerfen. Ein Fix in app/ui/components/StatsCard deckt alle sieben gemeldeten Routen ab (sync-disable + Eintrag in docs/subframe/COMPONENT-MAPPING.md).
  • P0-01 war ein fehlender globaler Rollout-Datensatz. Mit CR-007 sind die fertigen Admin-Sales-Routen standardmäßig aktiv; AdminUser, Permissions und Own-/All-RLS bleiben die einzigen Zugriffsgates.
  • P0-11 war ein Rechteproblem: _prisma_migrations hat seit dem RLS-Cutover keinen GRANT für hivegrid_app. Neue Migration 20260726190000_grant_app_migration_history_read mit spaltenweisem SELECT und Inverse-SQL als Kommentar, plus ein Log, das die Ursache künftig sichtbar macht.
  • P0-05 ist bewusst nur zur Hälfte umgesetzt: die Anzeige zeigt die ID dekodiert, der Detail-Link behält die Wire-ID. Eine Rückabbildung im Link wäre für Keys mit % mehrdeutig. Der Bericht sah %253A im Link als Fehler; das ist korrektes einmaliges URL-Encoding einer ID, die selbst %3A enthält.

Nebenbefund außerhalb des Berichts: toBullMqJobId ist nicht bijektiv — die Keys 42 und job-42 erzeugen beide die Job-ID job-42. Zwei verschiedene Idempotenzkeys könnten damit als Duplikat gelten. Praktisch unwahrscheinlich, aber dokumentiert und per Test festgehalten (packages/queue/src/job-id.test.ts).

Test-Proof (lokal grün): pnpm typecheck, pnpm lint, pnpm run verify:ui-visual (130 passed, 14 observed, 0 failed), pnpm run test:hot-swap, pnpm run verify:i18n (Parität 14.549 Keys über 9 Namespaces + neuer Diakritika-Check), Admin-Suite apps/web/app/components/screens/admin + apps/web/app/routes/admin (315 Tests). Neue Tests: 8 Dateien mit 46 Fällen.

Interim-Baselines: ak-p19-interim.visual.test.tsx und platform-leads-interim.visual.test.tsx wurden nachgezogen (AD-28). Beide Diffs wurden vor dem Update Zeichen für Zeichen geprüft: ausschließlich die neu sichtbaren Nullen und die neuen Label-Werte, keine Layout-Änderung.

Dev-Nachzug

  • UI-01 (fünf Nav-Patterns → eines) ist auf Nutzerwunsch ein eigenes Ticket. Empfehlung des Berichts: permanent sichtbare Inner-Sidebar mit Textlabels. Betrifft /api, /notifications, /support, /feature-flags, /sales/calls, /sales/bookings, /sales/email und zieht neue Visual-Baselines nach.
  • I18N-06, zwei Reste: settings.tenant.generalDescription („Aktualisiere deine Kontoeinstellungen" über einem fremden Mandanten) und search.command.placeholder (bietet im Admin Projekte und Dateien an) sind mit der Tenant-App geteilt. Beide brauchen eine kontextabhängige Komponente, keine Textänderung, sonst bricht die Tenant-Seite.
  • P0-09 Teil 2 und P0-10 (weitere Stellen): Das Muster <Link><Button/></Link> — ungültige verschachtelte interaktive Elemente — liegt an mindestens sechs weiteren Admin-Stellen (AdminSupportTicketPage, AdminTenantCreatePage, AdminSupportInboxPage 2×, AdminHealthPage). Ein sauberer Fix braucht eine ButtonLink-Komponente, die die Button-Optik auf ein <a> legt; der Subframe-Button rendert hart ein <button> und kennt kein asChild. Bis dahin bleibt der Doppelklick dort.

Quellen

  • Auditbericht vom 26.07.2026 (Auftragstext, unvollständig ab LAY-09)
  • AGENTS.md, docs/AGENT-CHECKLIST.md
  • docs/subframe/COMPONENT-MAPPING.md (Regeln für app/ui-Patches)
  • docs/security/RLS-HARDENING-2026-07-13.md (Kontext zu P0-11)
  • .planning/INTERIM-UI-PLAYBOOK.md (AD-28, Re-Baseline-Pflicht)

💡 Vorschläge (außerhalb Ticket-Scope)

  1. Copy-Button für den Commit-Hash auf /deploys. Der Bericht empfiehlt ihn; ich habe ihn nicht gebaut, weil er eine neue Funktion ist. Aufwand klein, Nutzen für Operatoren hoch.
  2. toBullMqJobId bijektiv machen (siehe Nebenbefund). Ein Präfix, das keine Kollision erzeugt, z. B. n- nur für rein numerische Keys, plus Migration der bestehenden IDs. Risiko heute gering, Fehlerbild später schwer zu finden.
  3. Währungs-Fallback prüfen: /accounts/subscriptions fällt bei fehlender Währung auf USD zurück. In einem EU-Produkt wäre EUR naheliegender. Nicht angefasst, weil außerhalb des Befunds.