# AK-SET-01 · Settings-Informationsarchitektur: 21 Rail-Einträge zu 6 Hubs bündeln | | | |---|---| | **Typ** | Dev/UI — Informationsarchitektur + Interim-UI-Sanierung | | **Owner** | Akeshan + Agent | | **Status** | 🟡 READY-TO-VERIFY — Dev-DoD 14/14 erfüllt (2026-07-22) | | **Blocked by** | — (`AK-P21` ist in der Branch-Basis enthalten) | | **Tracking** | nur Git-Repo — kein Plane-Ticket (analog zur gelöschten AK-UI-Serie, siehe `AK-UI-ENTFALLEN.md`); diese Doc ist die alleinige Quelle der Wahrheit | 🎨 **design-nachzug: offen** — die sieben Hubs und der Audit-Export verwenden die freigegebene Interim-UI; die finale Subframe-Optik bleibt ein getrackter Nachzug gemäß AD-28. ## Was wir bauen Die Tenant-Settings unter `/app/:tenant/settings` reichen der inneren Rail aktuell **bis zu 21 Einträge** durch. Diese 21 Einträge werden zu **6 Hub-Bereichen + Kundenportal** gebündelt. Jeder Hub bekommt eine eigene Layout-Route mit `PageHeader` und einer permanent sichtbaren horizontalen `~/ui`-Tab-Leiste; jeder Tab behält eine eigene URL. Alle Alt-URLs bleiben über 302-Redirects erreichbar. Zusätzlich wird `/settings/audit-export` überhaupt erst über die Navigation erreichbar gemacht und auf den Interim-UI-Standard gehoben (heute: handgeschriebenes Tailwind mit `bg-blue-600`, kein `PageHeader`, keine Zustände). ## Nicht im Scope (verbindlich) - **`apps/web/app/components/ui/layouts/SidebarIconsLayout.tsx` und `apps/web/app/ui/components/SidebarInside/` werden NICHT angefasst.** Hover-Aufklappen, `HOVER_OPEN_DELAY_MS`/`HOVER_CLOSE_DELAY_MS` (300/350 ms), die `w-[208px]`, der Content-Reflow beim Aufklappen und die Mobile-Tabs-Leiste bleiben exakt wie sie sind. Geändert wird ausschließlich der **Inhalt** des `items`-Arrays, das `settings.tsx` hineinreicht. Die 17 übrigen Call-Sites der Komponente bleiben dadurch unberührt. — *User-Entscheidung 2026-07-21.* - Der Plattform-Admin-Bereich (`routes/admin/settings/*`, eigene 8-Punkt-Navigation in `AdminSidebar.tsx:325-372`) hat dasselbe Problem, ist hier aber bewusst außen vor. - Keine Änderung an VM-Buildern, Domain-Services, Prisma-Schema oder Permissions. Loader/Actions ziehen 1:1 mit um. ## Ist-Stand (live verifiziert 2026-07-21, Tenant `hivegrid-demo`) `getTabs()` in `apps/web/app/routes/app.$tenant/settings.tsx:66-246` baut bis zu 21 Einträge; `settings/` enthält ~35 Route-Dateien mit 8.779 LOC. **Befund 1 — die Rail skaliert nicht auf 21 Einträge.** Die innere Rail ist eine Hover-Rail: `expanded = hovered || focusWithin` (`SidebarIconsLayout.tsx:37`), **es gibt keinen Pin/Toggle**. Im Ruhezustand nur Icons, davon mehrere doppelt (drei identische Aktivitäts-Kurven für Nutzung/Chat-Audit/Protokolle, zwei identische Dokument-Icons für Rechnungen/Richtlinien). Aufgeklappt ist die Spalte `w-[208px]` (`SidebarInside.tsx:144`), abzüglich 32 px Icon-Spalte bleiben ~140 px, der Text hat `truncate` (`SidebarInside.tsx:50`) → **7 von 18 sichtbaren Labels sind abgeschnitten**: „Datensch…", „Abonnem…", „Rechnun…", „Demo-Da…", „Integratio…", „API-Schlü…", „Benachric…". Mobil rendert dieselbe Komponente alle Einträge als horizontale Tabs-Leiste (`SidebarIconsLayout.tsx:132-145`) — 21 Tabs scrollen dort ins Nirgendwo. **Befund 2 — `settings/audit-export.tsx` bricht die Interim-UI-Standards.** Kein `PageHeader`, stattdessen nacktes `

` (Z. 109); `bg-blue-600`/`text-blue-600`-Buttons (Z. 158, 166) in einer Farbe, die im Rest der App nicht vorkommt; rohe `` und ``/``, Empty-/Loading-/Error-States mit Klartext. Über Hub F per Navigation erreichbar. - [x] **8.** Doppelte Tab-Leisten entfernt (`MembersPage.tsx:92-97`, `RolesPage.tsx`); Fallback-Tab-Hack `settings.tsx:203-210` entfällt. - [x] **9.** `POLICY_SECTIONS`-Pfade auf die neuen URLs gezogen (Tabelle in §C), inkl. Fix der `"api"`-Kette. - [x] **10.** Leerer Hub = **404**, nicht leere Seite: hat ein User für keinen Tab eines Hubs die Permission, wirft der Hub-Loader 404 und der Rail-Eintrag wird nicht gerendert (DoD E25). - [x] **11.** Registry-Gates nachgezogen: `UI_NAV_IDS`, `docs/ui-inventory/surfaces.json`, `AppSidebar.test.tsx`-Fixtures, i18n de **und** en. - [x] **12.** **`git diff` gegen `SidebarIconsLayout.tsx` und `ui/components/SidebarInside/` ist leer.** - [x] **13.** Tests grün: VM-Unit, Redirect-Contract, Smoke je Hub, Visual-Baselines (interim markiert), plus die bestehenden Suiten aus §Verifikation. - [x] **14.** **Konsumenten-Sweep abgeschlossen** (§Slice 2b): kein Produktions-Code baut mehr eine Alt-URL, die nur noch per 302 erreichbar wäre. Verifiziert per Grep-Kontrolllauf; Suchindex und Command-Palette zeigen direkt auf die neuen Ziele. **Fortschritt:** AK-SET-01: **14/14 DoD = 100 % done** · 0 Punkte offen · finaler Subframe-Design-Nachzug separat offen und gemäß AD-28 nicht Done-blockierend. ## Umsetzungs-Notiz · 2026-07-22 - Basis aus Akeshans geschlossenem PR #208 übernommen (`742fea5a5`), erste Route-/Audit-Vertragsfehler in `628483111` repariert; Abschluss in diesem Settings-Reparaturcommit. - Vollständige Alt→Neu-Matrix: 41 visuelle Alt-Routen, 83 Redirect-Assertions mit 302, Query-Erhalt und Kettenausschluss. CSV-, Attachment-, Privacy- und Rechnungs-Download-Endpunkte bleiben auf ihren veröffentlichten URLs und werden separat getestet. - Permission-/Modul-Parität für Rail und Hub-Loader hergestellt; Hub-Basis-URLs springen auf den ersten tatsächlich erlaubten Tab, leere Hubs liefern 404. Tenant-Audit-Export liest Audit-Daten unter gebundenem RLS-Kontext. - UI-/Registry-Proof: sieben Rail-IDs in `UI_NAV_IDS` und `docs/ui-inventory/surfaces.json`; Interim-Visual-Baseline rendert alle sieben Hubs, Smoke-Spec deckt jeden Hub ab. Der Diff gegen die beiden ausdrücklich gesperrten Sidebar-Layoutpfade ist leer. - Verifikation: `pnpm typecheck`, `pnpm lint`, `pnpm build`, `pnpm run verify:bundle-size` (13/13 Gruppen und 653/653 Einzelrouten), `pnpm run verify:i18n`, `pnpm run verify:sidebar-routes`, `pnpm test:hot-swap`, `pnpm run verify:test-coverage`, `verify:source-health`, `verify:ci-baseline` und `git diff --check` grün. Gezielte Settings-Suite: 126/126 Tests. Voller Core-Lauf: 1.004 Testdateien und 7.240 Tests bestanden; 10 Dateien/55 Live-Integrationstests erwartungsgemäß ohne Infrastruktur übersprungen. Der nachgezogene Worker-Mailvertrag ist zusätzlich mit 21/21 Tests grün. 47 betroffene Playwright-Fälle kompilieren über `--list`; kein lokaler Live-E2E-/Deploy-Lauf durchgeführt. - Konsumenten-Sweep: Produktcode, Worker, Such-/Command-Ziele, visuelle Fixtures und E2E-Defaults zeigen direkt auf die neuen Hub-Routen. Verbleibende Treffer sind Komponenten-Importpfade oder die absichtlich unveränderten Resource-Endpunkte. ## Technische Bausteine (Slices in Reihenfolge) **Slice 0 — Route-Manifest-Baseline.** `apps/web/app/routes.ts` nutzt `createRoutesFromFolders` (v1-Konvention über `~/utils/compat/v1-route-convention`), und der Bestand **mischt** Punkt-Notation (`privacy.export.tsx`) mit Ordner-Notation (`members/new.tsx`). Snapshot-Test über alle `app.$tenant/settings/**`-Pfade anlegen. **Konvention für alles Neue: ausschließlich Ordner-Notation** (`billing.tsx` + `billing/usage.tsx`), analog zum bewährten `members.tsx` + `members/`, `roles-and-permissions.tsx` + `roles-and-permissions/`, `integrations.tsx` + `integrations/`. **Slice 1 — `SettingsHubShell` + VM.** VM: `buildSettingsHubVM({ tabs, activeHref })` → `{ tabs: [{ id, labelKey, href, active }] }`; die Permission-Entscheidung trifft der **Loader** und übergibt nur erlaubte Tabs. Screen komponiert `PageShell` + `PageHeader` (`components/screens/shared/PageShell.tsx`) + `~/ui/components/Tabs`, Tabs als `` — **exakt das Muster aus `components/screens/users/MembersPage.tsx:92-97`**. **Slice 2 — Redirect-Helper + Contract-Test.** `settings/legacy-redirects.server.ts` mit `legacySettingsRedirect(request, params, target)` → 302 mit erhaltenem Query-String. Vorlage 1:1: `routes/app.$tenant/api/legacy-settings-redirects.test.ts` und die Loader in `api/index.tsx`, `api/keys.tsx`. **Slice 2b — Konsumenten-Sweep** *(neu, ergänzt 2026-07-21 nach Grep-Befund — im ursprünglichen Plan unterschätzt).* Der Grep hat **~25 Produktionsdateien außerhalb von `routes/`** gefunden, die Settings-URLs hartkodieren. Redirects halten die zwar am Leben, aber ein Suchindex-Eintrag oder ein Command-Palette-Ziel, das dauerhaft über einen 302 läuft, ist eine schleichende Regression. Diese Konsumenten ziehen **mit** um: | Kategorie | Dateien | Warum kritisch | |---|---|---| | App-Chrome-Menüs | `components/layouts/buttons/ProfileButton.tsx` (6 Pfade!), `layouts/sidebars/shadcn/nav-user.tsx`, `nav-actions.tsx`, `layouts/NavBar.tsx`, `buttons/CurrentSubscriptionButton.tsx` | direkt sichtbare Navigation | | Command-Palette | `services/command-registry/commandRegistry.ts` Z. 99, 109, 118, 127, 150, 159 | 6 Spotlight-Ziele | | Suchindex | `services/search/globalSearch.server.ts`, `services/search/searchIndexProjection.server.ts` | **persistierte** URLs im Index → Re-Index nötig, sonst bleiben Alt-Ziele dauerhaft gespeichert | | URL-Helfer | `utils/app/SubscriptionUrlUtils.ts` (`settings/subscription?subscription_required=1`) | Query-String muss den Redirect überleben — deckt Contract-Test ab | | Fach-Services | `utils/services/.server/akP20OnboardingService.ts`, `modules/events/services/.server/EventsService.ts`, `services/billing/customer-invoices.server.ts`, `modules/chat/routes/chatRoutePaths.ts`, `utils/data/useMembersData.ts` | | | Feature-Gates / Formulare | `components/ui/misc/ProFeature.tsx`, `core/settings/subscription/CheckPlanFeatureLimit.tsx`, `core/pricing/PricingPlanForm.tsx`, `core/settings/members/NewMember.tsx`, `screens/users/InviteMemberForm.tsx`, `modules/users/components/SubscriptionSettings.tsx` | | | Error-Reporter | `packages/error-reporter/src/sentry.ts` (`settings/privacy`) | | | Hot-Swap / Visual | `packages/ui-mock/src/index.ts`, `packages/ui-mock/visual-baseline/{ak-p20-interim,va-p24a-interim,ak-ui-05-plugins}.mock.ts` | sonst driften Hot-Swap-Drill und Baselines | **Nicht betroffen:** E-Mail-Templates. Der Grep über `apps/web/app/modules/emails` und `packages/mail` fand nur zwei Admin-Test-URLs (`admin.example.com/settings/transactional-emails`), keine Tenant-Settings-Links. Die per Mail versendete Lösch-Bestätigungs-URL wird in `privacy.tsx` gebaut und fällt unter die Endpoint-Regel. **Vorgehen:** Der Sweep läuft **pro Hub im jeweiligen Slice**, nicht als Big-Bang — beim Umzug eines Hubs werden dessen Konsumenten mitgezogen. Abschluss-Kontrolle in Slice 10 per Grep. **Slice 3 — Hub D „Abrechnung" (Pilot).** Kleinster Hub, drei Tabs, alle mit demselben `BILLING_MODULE_KEY`-Gate. Löst den `subscription.tsx`-Pass-through-Footgun und verankert ihn im Contract-Test. **Danach STOP und Review**, bevor die übrigen Hubs folgen. **Slice 4 — `audit-export` Interim-UI-Sanierung.** Eigenständig wertvoll, auch ohne den Rest. Neuer Screen `components/screens/audit/AuditExportPage.tsx`; Loader/CSV-/PDF-Streaming (`streamTenantAuditExport`, `streamTenantAuditPdfExport`) bleiben unverändert. Filter-Optionen als VM (`packages/view-models/src/audit/audit-export.vm.ts`) statt hartkodierter `