# Super Admin — Tenant Access Design

**Date:** 2026-06-29
**Status:** Approved
**Scope:** Bug fix (TenantMiddleware schema name) + feature (super admin impersonation with session restore)

---

## Problem

1. **Bug:** `TenantMiddleware` constructs schema name as `"tenant_<uuid-with-hyphens>"` but schemas are named `tenant_<uuid-with-underscores>`. All tenant user requests fail with SET search_path error. Independent of the feature — must always be fixed.

2. **Feature gap:** Super admin can list and create tenants but cannot access or manage data within individual tenant workspaces.

---

## Solution

### Bug Fix — TenantMiddleware

Replace raw UUID concatenation with normalized schema name (hyphens → underscores):

```go
// Before
schema := `"tenant_` + claims.TenantID + `"`

// After
schema := `"tenant_` + strings.ReplaceAll(claims.TenantID, "-", "_") + `"`
```

### Feature — Tenant Impersonation with Session Restore

**Flow:**
1. Super admin clicks "Gerir" on any tenant row in TenantsPage
2. Frontend calls `POST /api/v1/admin/tenants/:id/access`
3. Backend validates tenant (exists + active), generates a 15-min access token with `tenantID=<id>` and `role="tenant_admin"`
4. Frontend saves current session to `previousSession` in authStore, sets new token+user
5. Navigates to `/app` — super admin now sees the tenant workspace
6. AppLayout shows a banner: `[TechXCar Admin]  A gerir: <tenant name>  [← Voltar ao painel]`
7. Clicking "Voltar" restores the previous session and navigates to `/admin`

---

## Backend

### New endpoint

`POST /api/v1/admin/tenants/:id/access`
- Auth: `RequireAuth` + `RequireRole("super_admin")`
- Validates: tenant ID format, tenant exists, tenant status = "active"
- Returns: `{ "data": { "access_token": "...", "tenant": { "id", "name", "slug" } }, "error": null }`
- Token: standard 15-min access token, `userID = super_admin_id`, `tenantID = tenant.ID`, `role = "tenant_admin"`
- No new refresh token — the impersonation session is access-token only

### Route registration

Added to `tenant.RegisterRoutes` under the existing `admin` group:
```
POST /api/v1/admin/tenants/:id/access
```

---

## Frontend

### authStore changes

New fields:
```typescript
previousSession?: { token: string; user: AuthUser }
```

New actions:
- `impersonateTenant(token, user)` — saves current `{ token, user }` to `previousSession`, sets new token+user
- `restoreSession()` — restores `previousSession` into token+user, clears `previousSession`

`previousSession` is NOT persisted to localStorage (impersonation does not survive page refresh — intentional).

### TenantsPage

Each tenant row gains a "Gerir" button (secondary/outline variant).

On click:
1. POST `/admin/tenants/:id/access`
2. On success: `impersonateTenant(data.access_token, { ...data.tenant, role: 'tenant_admin' })`
3. Invalidate TanStack Query cache (avoid stale super-admin-scoped data)
4. Navigate to `/app`

### AppLayout

When `authStore.previousSession` is defined, render a fixed banner at the top:

```
[TechXCar Admin]  A gerir: <user.name>  [← Voltar ao painel]
```

- Background: amber/yellow to visually distinguish from normal tenant UI
- "Voltar" button: calls `restoreSession()`, navigates to `/admin`
- Banner height: ~40px; main content padding-top adjusts accordingly

---

## Error Handling

- Tenant not found or not active → 404 "oficina não encontrada ou inativa"
- `impersonateTenant` failure (network) → show error toast, do not change session
- Restoring session never fails (purely client-side state)

---

## Out of Scope

- Refresh token for impersonation sessions (15-min window is intentional)
- Audit log of impersonation events (future)
- Super admin creating/editing data within tenant as themselves (they appear as tenant_admin)