281 lines
16 KiB
Markdown
281 lines
16 KiB
Markdown
# 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)
|
||
|
||
- [x] **P0-01** Toter Sidebar-Link „Lead-Regeln" (`/sales/settings/leads` → 404)
|
||
- [x] **P0-02** `NaN €` in der Tarif-Spalte auf `/accounts/subscriptions`
|
||
- [x] **P0-03** `1/NAN` in der Pagination der drei `/notifications`-Listen
|
||
- [x] **P0-04** Rohe HTML-Entities (`Europe/Berlin`, `https://`)
|
||
- [x] **P0-05** Job-IDs in der Wire-Form `…%3A…` auf `/jobs`
|
||
- [x] **P0-06** Stat-Karten ohne Zahl bei Wert 0 (7 Routen)
|
||
- [x] **P0-07** Commit-Hash läuft aus der Release-Karte auf `/deploys`
|
||
- [x] **P0-08** Falscher Seitentitel und Breadcrumb im ganzen `/sales/settings/*`-Zweig
|
||
- [x] **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.
|
||
- [x] **P0-10** „Details" auf `/jobs` brauchte zwei Klicks
|
||
- [x] **P0-11** Migrationsstatus las nicht aus der DB; `/system` zeigte leeren Release
|
||
- [x] **P0-12** Zwei verschiedene 404-Seiten auf demselben Host
|
||
|
||
### i18n und Copy (5/6 erledigt)
|
||
|
||
- [x] **I18N-01** ASCII-Transliteration in 26 deutschen Strings + CI-Gate
|
||
- [x] **I18N-02** Rohe Enum-Werte (Support-Status/Priorität/Quelle, Plan-Code,
|
||
Trial-Badge, Provider-Auswahl)
|
||
- [x] **I18N-03** Rohe Event-Keys als Checkbox-Label in `/marketing-integrations`
|
||
- [x] **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**
|
||
- [x] **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.
|