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

281 lines
16 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.