team-scope-wiring

name

team-scope-wiring

description

How to wire an admin SPA page (or the chat) to the global TEAM (= tenant) switcher in the topbar — every authenticated route lives under /app/{teamHash}/…, the X-Tenant-Id header is automatic via the shared axios client, switching team rewrites the URL hash + clears the TanStack cache + remounts the route outlet, project options must come from tenant-scoped endpoints. Trigger when wiring an admin page to the team scope, when adding a NEW admin page / route / feature folder under frontend/src/features/, when adding a `navigate(...)` call, when touching a project picker / project filter, or when a page shows stale cross-team data after a team switch.

Team-scope wiring — cablare una pagina al team switcher

Architettura (cosa è già automatico)

Il menu in alto nella topbar è il TeamSwitcher (frontend/src/components/shell/TeamSwitcher.tsx). Team = tenant. La selezione vive in frontend/src/lib/team-store.ts (Zustand, persistito {userId, currentTeam} su localStorage) e viene sincronizzata da useAuthStore.setMe a ogni bootstrap/login leggendo la chiave teams di GET /api/auth/me (costruita da app/Services/Auth/UserTeamsResolver.php).

Ogni team ha un hash di routing univoco (BE app/Support/TeamHash.php = substr(sha256(tenant_id), 0, 12), esposto nella chiave teams di /api/auth/me). Tutte le rotte autenticate vivono sotto /app/{teamHash}/…. L'URL è la fonte di verità del team attivo: TeamGate (in frontend/src/routes/index.tsx) possiede il segmento $teamHash, sincronizza lo store sull'hash dell'URL e, se il segmento non è un hash valido (vecchio bookmark /app/admin/kb), re-prefissa l'intero path sotto l'hash del team attivo. Il cambio team nel TeamSwitcher è una navigazione che scambia il segmento hash, non un set diretto dello store.

Quattro meccanismi rendono il cablaggio "gratis" per la maggior parte delle pagine:

1. Header automatico — l'interceptor in frontend/src/lib/api.ts timbra X-Tenant-Id su ogni richiesta dell'axios condiviso (esclusi /api/auth/, /sanctum/, /testing/). Lato BE ResolveTenant lo risolve nel TenantContext; AuthorizeTenantHeader autorizza via membership (project_memberships nel tenant) o tenant.cross-access.
2. URL hash-prefissato — il segmento {teamHash} è in ogni rotta; un deep-link a /app/{altroHash}/… cambia team da solo via TeamGate.
3. Cache flush — switchTeam() fa queryClient.cancelQueries() + queryClient.clear(): ogni query montata rifetcha sotto il nuovo team.
4. Remount keyed — in AppShell l'<Outlet /> è dentro un div key={currentTeam}: lo stato locale di pagina (picker, selezioni, filtri free-text) si azzera da solo al cambio team.

Navigazione: passa SEMPRE l'hash

Ogni navigate(...) / <Navigate> / href / BrowserRouter basename verso una rotta /app/… deve includere il segmento team. Pattern: navigate({ to: '/app/$teamHash/admin/kb', params: { teamHash } }), con const teamHash = useTeamStore(selectCurrentHash) ?? ''. Per i fetch/location.assign raw, interpolare /app/${teamHash}/…. I selettori selectCurrentTeam / selectCurrentHash vivono in frontend/src/lib/team-store.ts. Le rotte in nav-config.ts usano il literal /app/$teamHash/… e AppShell.onNav passa params: { teamHash }.

Checklist per pagina (in ordine)

1. Le chiamate passano dall'axios condiviso? Un fetch / EventSource raw NON riceve l'header: replicarlo a mano come fa frontend/src/features/chat/use-chat-stream.ts (accanto a X-XSRF-TOKEN). Grep: fetch( e new EventSource nel feature folder.
2. Il controller BE è tenant-scoped? Ogni query su tabella tenant-aware deve avere forTenant() / where('tenant_id', …) (R30, vedi [[cross-tenant-isolation]]). Se manca, fixare il BE PRIMA di cablare il FE — il cambio team che "non cambia niente" di solito è un controller che aggrega tutti i tenant.
3. Le Cache::remember BE includono il tenant nella chiave? Esempio canonico: DashboardMetricsController::cacheKey() → admin.metrics.{kind}.{tenant}.{project}.{days}. Una chiave senza tenant serve i numeri del team A al team B per tutta la TTL.
4. Le opzioni progetto derivano da un endpoint tenant-scoped? (R18) Mai liste literal: il picker di KbView usa GET /api/admin/kb/projects (già forTenant) e si aggiorna da solo. Per i progetti A CUI L'UTENTE HA ACCESSO nel team attivo: useTeamStore → team corrente → projects.
5. Lo stato locale vive sotto l'Outlet keyed? useState dentro la pagina si resetta gratis. Stato in store globali (Zustand/context) o nell'URL sopravvive al remount → serve un reset esplicito al cambio team (subscribe su currentTeam) o va spostato in stato locale.
6. La pagina è volutamente globale? (Roles/Permissions, PII strategy, application log, activity, failed jobs, queue) → NON cablarla: aggiungi il chip "global" con tooltip (pattern in frontend/src/features/admin/logs/LogsView.tsx) e documenta il perché.
7. Test. PHPUnit: fixture su 2 tenant + assert di esclusione per il controller (pattern: AdminMetricsServiceTest::test_every_metric_excludes_rows_from_other_tenants). E2E: scenario di switch su tenant acme (seedato da DemoSeeder) in frontend/e2e/team-switcher.spec.ts o spec dedicata — i conteggi default/acme sono volutamente diversi (R16).

Anti-pattern

• ❌ Tenant nelle query key di TanStack invece del clear globale: l'header è implicito in ogni richiesta; chiavi parziali = cache miste.
• ❌ Header su /api/auth/*: un team persistito non più valido fa 403 sul bootstrap e locka l'utente fuori. Le esenzioni vivono in TENANT_EXEMPT_PREFIXES (frontend/src/lib/api.ts).
• ❌ Liste tenant/progetti hardcoded nel FE (R18) — i seed PROJECTS in frontend/src/lib/seed.ts sono UI-only legacy.
• ❌ Catch silenzioso del 403 tenant_forbidden: l'interceptor resetta il team MA propaga l'errore (R14) — non aggiungere retry silenziosi a valle.
• ❌ Nuova pagina con picker progetto proprio scollegato dal team — le opzioni devono sempre arrivare da un endpoint tenant-scoped, così il remount le riallinea da solo.

Dati di test

DemoSeeder seeda due tenant: default (3 docs, 5 chat) e acme (label "Acme Corp", 2 docs, 2 chat, membership solo per [e-mail]; [e-mail] resta single-team — serve al failure path). I conteggi diversi sono il segnale differenziante: non pareggiarli mai.