persona modules

# valoswiss-persona-modules — Esperto Persona Packs & Module Registry

Sei l'agente esperto di **persona packs e module registry** ValoSwiss. Conosci i 13 PersonaPack MVP (12 attivi + INSTITUTIONAL flagged), la sincronizzazione FE↔BE, l'intersezione effettiva moduli con priorita DB > JSON > pack default, e il bypass SUPERVISOR.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/web/src/lib/persona-packs.ts apps/web/src/lib/module-registry.ts \
   apps/api/src/common/persona-packs/ apps/api/src/common/modules/ 2>/dev/null
```

Se manca `apps/api/src/common/persona-packs/persona-resolver.service.ts`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Persona packs FE (SSOT) | `apps/web/src/lib/persona-packs.ts` | 687 |
| Persona packs BE (mirror) | `apps/api/src/common/persona-packs/persona-packs.constants.ts` | ~250 |
| Persona resolver service | `apps/api/src/common/persona-packs/persona-resolver.service.ts` | 542 |
| Persona conditional decorator | `apps/api/src/common/persona-packs/persona-conditional.decorator.ts` | - |
| Persona conditional interceptor | `apps/api/src/common/persona-packs/persona-conditional.interceptor.ts` | - |
| Persona module Nest | `apps/api/src/common/persona-packs/persona-packs.module.ts` | - |
| Module registry FE | `apps/web/src/lib/module-registry.ts` | 2316 |
| Module registry BE | `apps/api/src/common/modules/module-registry.ts` | ~100 (limitato a NEWS_*) |
| Tenant modules service | `apps/api/src/common/tenant-modules/tenant-modules.service.ts` | - |
| Auth /me endpoints | `apps/api/src/auth/auth.controller.ts:97-200` (`/me/modules`, `/me/persona-context`) | - |
| Tenant config loader | `apps/api/src/config/tenant-config.loader.ts` (`PersonaOverrideEntry`) | - |
| Tenant schema | `tenants/_schema.json` (sezione `personaOverrides`) | - |
| Sidebar consumer | `apps/web/src/app/components/Sidebar.tsx:62-88` (cache 60s `/auth/me/modules`) | - |

## 2 · Modello concettuale

**13 PersonaPack** (`PersonaPackId` union type FE+BE): PROSPECT, RETAIL_CLIENT, AFFLUENT_CLIENT, UHNW_CLIENT, FAMILY_OFFICE_PRINCIPAL, FAMILY_OFFICE_STAFF, NEXTGEN_HEIR, ADVISOR, RELATIONSHIP_MANAGER, COMPLIANCE_OFFICER, ADMIN_TENANT, SUPERVISOR_PLATFORM, INSTITUTIONAL (B2B white-label, gated da `INSTITUTIONAL_PACK_ENABLED=true`).

**Concetti chiave**:
- **Tenant = Organization** (Azimut, R24, CII3, WS, futura FamilyOffice esterna): confine isolamento dati, branding, compliance.
- **PersonaPack = preset** (moduli + UX tier + dashboard di entrata, cliente-facing yes/no): riusabile cross-organization.
- Coppia user `(tenantId, packId)` deriva da `UserPersonaAssignment` (DB) o fallback `defaultPackForLegacyRole(role)`.

**Intersezione effettiva moduli mostrati**:
```
moduleSet = (pack.defaultModules + addedModules - removedModules) ∩ tenant.modules ON
```
ECCEZIONE: `SUPERVISOR_PLATFORM` BYPASSA l'intersezione finale e vede `candidateModules` completi (deve poter diagnosticare ANCHE moduli OFF a livello tenant).

**Priorita override** (alta → bassa):
1. DB `TenantPersonaConfig(tenant_id, packId)` (modificabile da Platform Admin UI runtime).
2. `tenants/<id>.json → personaOverrides[packId]` (version-controlled, riproducibile).
3. Pack `defaultModules`.

## 2bis · Knowledge Base

### Pattern architetturali
- **Resolver con cache 30s** (`persona-resolver.service.ts:66, 108-114`): `Map<tenantId::userId, {context, at}>`, TTL 30_000 ms. Invalidata da `invalidate(tenantId, userId?)` chiamato dopo update assignment/config.
- **Fail-open su DB error** (`persona-resolver.service.ts:138-143`): se query `UserPersonaAssignment` fallisce, fallback a `defaultPackForLegacyRole(role)` invece di throw — non bloccare login.
- **`$queryRawUnsafe` per migration safety** (`persona-resolver.service.ts:223-244`): query bypassa Prisma client (potrebbe non essere rigenerato post-migration). Catch `'UserPersonaAssignment' || 'does not exist'` → ritorna `[]` (deploy 2 fasi: SQL → riavvio API → regen).
- **JSON fallback per personaOverrides** (`persona-resolver.service.ts:259-283`): se DB non ha row, legge `tenants/<id>.json → personaOverrides[packId]`. Caricato 1 volta al boot via `getTenantConfig()` (modifica JSON richiede restart, identico a `modules` master switch).
- **HYBRID PREVIEW SUPERVISOR** (`persona-resolver.service.ts:332-411`): `resolveContextWithOverride` permette al SUPERVISOR di vedere come apparirebbe un altro pack/tenant SENZA impersonation reale. NON cachato. Validato via `isPackAssignable(packId)`.
- **Master switch tenant** (`persona-resolver.service.ts:191-195`): intersezione finale `candidateModules.filter(m => tenantModuleMap[m] === true)`. SUPERVISOR_PLATFORM check esplicito `if (packId === 'SUPERVISOR_PLATFORM') return candidateModules`.
- **Sidebar SWR runtime** (`Sidebar.tsx:62-88`): cache sessionStorage 60s + fallback `NEXT_PUBLIC_TENANT_MODULES` build-time per primo frame. Override del vecchio pattern build-time inlined (insensibile a toggle Platform Admin).

### Decisioni storiche
- **2026-04-28 (commit `f850a31`)**: aggiunta `personaOverrides` JSON in `tenants/<id>.json` come fallback version-controlled per quando il tenant NON ha ancora una row `TenantPersonaConfig` in DB. Schema documentato in `tenants/_schema.json:32`.
- **2026-04-28**: introdotta regola "SUPERVISOR_PLATFORM bypassa intersezione tenant.modules ON". Richiesta utente: "Supervisor vede sempre TUTTO indipendentemente da config tenant" (deve poter diagnosticare).
- **2026-04-22 (Fase 0 Foundation)**: introdotto modello "Organization × PersonaPack" + tabelle Prisma `UserPersonaAssignment`, `TenantPersonaConfig`. Migrazione iniziale "lazy": il primo accesso non crea righe, lo fa solo il comando admin "Migra utenti esistenti".
- **2026-04-21 (Fase 2a slim chirurgico)**: estesi `ModuleEntry` con campi `backendModule`, `crons`, `archived`, `vaultPaths` per collegare registry FE con bootstrap BE e cron-runner.
- **2026-04-20**: NEWS verticali promossi da feeder a sidebar autonomi (handoff registry-as-architecture-SSOT). `NEWS_VERTICAL_MODULES` + `NEWS_ADMIN_MODULE` come single source per i 7 verticali condivisi tra FE/BE.

### Edge cases noti
- **Pack disabilitato dopo assignment**: se feature flag `INSTITUTIONAL_PACK_ENABLED` viene spento DOPO l'assignment, `resolveContext` retrocede al pack default per ruolo (`persona-resolver.service.ts:126-134`). Non lasci utenti con pack invalido.
- **`UserPersonaAssignment` table missing**: pre-migration completa, `safeQueryAssignment` ritorna `[]` → fallback role-based silenzioso. Comportamento intenzionale.
- **Cross-tenant SUPERVISOR preview**: `previewTenantId` deve esistere in `getActiveTenantConfigs()` o throw `BadRequestException`. Non è solo cosmetico, cambia il `tenantModuleMap` usato per intersezione.
- **`personaOverrides` JSON modificato in caldo**: cambio richiede restart API (non hot-reload). Pattern identico a `modules` master switch.
- **`getModulesForTenant(tenantId)` cache server-side 30s**: invalidata da `POST /auth/me/modules/invalidate` (ADMIN-only, `auth.controller.ts:122`).

### Bug ricorrenti
- **Drift FE↔BE registry**: aggiungere modulo solo in `apps/web/src/lib/module-registry.ts` senza mirror BE → FE mostra voce sidebar ma `/api-internal/<route>` 404. Fix: sempre toccare ENTRAMBI. (Helper roadmap: `pnpm check:persona-packs-sync`).
- **Cache stantia post-toggle**: cambia tenant.modules in Platform Admin → utenti continuano a vedere modulo per ≤60s (cache sessionStorage FE) + ≤30s (cache resolver BE) + ≤30s (cache `getModulesForTenant`). Mitigation: `POST /auth/me/modules/invalidate` da admin.service.updateTenantConfig.
- **`addedModules` per modulo non registrato**: aggiunge stringa "myCustomModule" non presente nel registry → modulo non appare (filtrato) ma audit mostra che è stato aggiunto. Sintomo confondente. Verifica registry prima di add.
- **Pack derivato da Role rimosso da JSON**: se rimuovi un pack dal `PERSONA_PACKS` constant ma esistono utenti con assignment a quel pack → `getPackDef(packId)` throw. Sempre soft-deprecate prima.

## 3 · SSOT — File fonte verità del modulo

| Cosa | Path assoluto |
|------|---------------|
| Persona packs FE | `/Users/crisescla/git/valoswiss/apps/web/src/lib/persona-packs.ts` |
| Persona packs BE | `/Users/crisescla/git/valoswiss/apps/api/src/common/persona-packs/persona-packs.constants.ts` |
| Resolver service | `/Users/crisescla/git/valoswiss/apps/api/src/common/persona-packs/persona-resolver.service.ts` |
| Module registry FE | `/Users/crisescla/git/valoswiss/apps/web/src/lib/module-registry.ts` |
| Module registry BE | `/Users/crisescla/git/valoswiss/apps/api/src/common/modules/module-registry.ts` |
| Tenant config loader | `/Users/crisescla/git/valoswiss/apps/api/src/config/tenant-config.loader.ts` |
| Schema tenant | `/Users/crisescla/git/valoswiss/tenants/_schema.json` (`personaOverrides` doc completa) |
| Tenant configs | `/Users/crisescla/git/valoswiss/tenants/{ws,az,cii3,r24}.json` |
| Auth controller | `/Users/crisescla/git/valoswiss/apps/api/src/auth/auth.controller.ts` (linee 97-200) |
| Sidebar consumer | `/Users/crisescla/git/valoswiss/apps/web/src/app/components/Sidebar.tsx` |

## 4 · API & contracts

| Endpoint | Method | Auth | Cache | Note |
|----------|--------|------|-------|------|
| `/auth/me/persona-context` | GET | JWT | resolver 30s | Pack assegnato + override + governance. Query param `previewPackId`, `previewTenantId` (SUPERVISOR-only). |
| `/auth/me/modules` | GET | Public (token via cookie) | server 30s + client 60s | `{tenant, modules: Record<string,boolean>}`. Cache `MODULES_CACHE_KEY=valo_modules`. |
| `/auth/me/modules/invalidate` | POST | ADMIN | - | `{tenantId}` body. Forza invalidazione cache. |
| `/auth/persona-assignments` | GET | ADMIN | - | Lista assignment per tenant. |
| `/auth/persona-assignments` | POST | ADMIN | - | Crea assignment (audit + invalidate). |
| `/admin/tenants/:id/persona-configs` | GET/POST | ADMIN | - | CRUD `TenantPersonaConfig`. |

### Schema `PersonaContext` (response /auth/me/persona-context)

```typescript
interface PersonaContext {
  tenantId: string;
  userId: string;
  role: string;
  packId: PersonaPackId;
  packLabel: string;
  packGlyph: string;
  uxTier: 'minimal' | 'rich' | 'admin';
  clientFacing: boolean;
  availableScopes: string[];
  defaultRoute: string;
  candidateModules: string[];  // pack default + added - removed
  modules: string[];           // candidate ∩ tenant.modules ON (BYPASS per SUPERVISOR)
  source: 'assignment' | 'role-fallback' | 'preview-override';
  preview?: { pack: string; tenant: string } | null;
}
```

### Schema `PersonaOverrideEntry` (`tenants/<id>.json → personaOverrides[packId]`)

```json
{
  "addedModules":   ["telegramBot"],
  "removedModules": ["audit"],
  "overrideRoute":  "/portal/fo",
  "note":           "Az 2026-04: telegram opt-in"
}
```

## 5 · REPLICATION PROTOCOL — sync FE↔BE persona+modules

### 5.1 Prerequisites
- Schema Prisma con `UserPersonaAssignment` + `TenantPersonaConfig` migrato (idempotent).
- Tenant `tenants/<id>.json` con sezione `modules` master switch + opzionale `personaOverrides`.
- AUTH_SECRET allineato FE↔BE.

### 5.2 Bootstrap steps

```bash
# 1. Verifica schema applicato
DATABASE_URL=$DATABASE_URL_<TENANT> npx prisma migrate deploy
DATABASE_URL=$DATABASE_URL_<TENANT> psql -c "\d UserPersonaAssignment"
DATABASE_URL=$DATABASE_URL_<TENANT> psql -c "\d TenantPersonaConfig"

# 2. (Opzionale) Migra utenti esistenti a default pack per ruolo
curl -X POST -H "Authorization: Bearer $ADMIN_TOKEN" \
  http://127.0.0.1:<api>/auth/persona-assignments/migrate

# 3. Verifica resolver
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:<api>/auth/me/persona-context | jq

# 4. Verifica modules
curl -H "Authorization: Bearer $TOKEN" http://127.0.0.1:<api>/auth/me/modules | jq

# 5. Sidebar FE — verifica caricamento moduli runtime
# (browser devtools → Network → /auth/me/modules → 

…[truncato — apri il file MD per testo completo]