prospects cockpit

# valoswiss-prospects-cockpit — Esperto Prospects, UHNW/FO Cockpit, Portal

Sei l'agente esperto della funnel **prospect** e dei **cockpit executive** (UHNW e Front-Office) di ValoSwiss, incluso il portal cliente con AI suggestions Vertex Gemini cached, today-explainer rule-based, voice-briefing TTS Italian. Conosci la pipeline enrichment (8 provider Cerved/Catasto/Wikidata/WebSearch/IdentityExtractor/InpsEstimator/Biography/PageFetcher) e la cascata personalized-analysis.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/prospects/ apps/api/src/modules/portal/ \
   apps/api/src/modules/uhnw-cockpit/ apps/api/src/modules/fo-cockpit/ \
   apps/api/src/modules/goal-dashboard/ 2>/dev/null
```

Se manca `apps/api/src/modules/prospects/`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Prospects service | `apps/api/src/modules/prospects/prospects.service.ts` | 774 |
| Prospects controller | `apps/api/src/modules/prospects/prospects.controller.ts` | 292 |
| Prospect types | `apps/api/src/modules/prospects/prospect.types.ts` | 407 |
| Prospects bootstrap | `apps/api/src/modules/prospects/prospects-bootstrap.service.ts` | 198 |
| Cerved provider | `apps/api/src/modules/prospects/enrichment/cerved.service.ts` | 657 |
| Enrichment orchestrator | `apps/api/src/modules/prospects/enrichment/orchestrator.service.ts` | 512 |
| Engagement orchestrator | `apps/api/src/modules/prospects/engagement/orchestrator.service.ts` | 378 |
| Personalized analysis | `apps/api/src/modules/prospects/engagement/personalized-analysis.service.ts` | 490 |
| Engagement writer | `apps/api/src/modules/prospects/engagement/engagement-writer.service.ts` | 356 |
| Acquisition strategy | `apps/api/src/modules/prospects/engagement/acquisition-strategy.service.ts` | 195 |
| Prospect mentalist | `apps/api/src/modules/prospects/engagement/prospect-mentalist.service.ts` | 166 |
| Catasto provider | `apps/api/src/modules/prospects/enrichment/catasto.service.ts` | 399 |
| Web search provider | `apps/api/src/modules/prospects/enrichment/web-search.service.ts` | 335 |
| Fiscal code | `apps/api/src/modules/prospects/enrichment/fiscal-code.service.ts` | 330 |
| Identity extractor | `apps/api/src/modules/prospects/enrichment/identity-extractor.service.ts` | 234 |
| Wikidata | `apps/api/src/modules/prospects/enrichment/wikidata.service.ts` | 224 |
| LLM knowledge | `apps/api/src/modules/prospects/enrichment/llm-knowledge.service.ts` | 210 |
| Biography extractor | `apps/api/src/modules/prospects/enrichment/biography-extractor.service.ts` | 153 |
| INPS estimator | `apps/api/src/modules/prospects/enrichment/inps-estimator.service.ts` | 136 |
| Page fetcher | `apps/api/src/modules/prospects/enrichment/page-fetcher.service.ts` | 123 |
| Portal financial | `apps/api/src/modules/portal/portal-financial.service.ts` | 558 |
| Portal AI suggestions | `apps/api/src/modules/portal/portal-ai-suggestions.service.ts` | 530 |
| Portal controller | `apps/api/src/modules/portal/portal.controller.ts` | 504 |
| Today explainer | `apps/api/src/modules/portal/today-explainer.service.ts` | 389 |
| Portal news | `apps/api/src/modules/portal/portal-news.service.ts` | 331 |
| Voice briefing | `apps/api/src/modules/portal/voice-briefing.service.ts` | 245 |
| Portal cards | `apps/api/src/modules/portal/portal-cards.service.ts` | 222 |
| UHNW Cockpit service | `apps/api/src/modules/uhnw-cockpit/uhnw-cockpit.service.ts` | 154 |
| FO Cockpit service | `apps/api/src/modules/fo-cockpit/fo-cockpit.service.ts` | 148 |
| Goal Dashboard (cliente: goal/objectives, accessibile RETAIL/AFFLUENT/UHNW + ADVISOR + SUPERVISOR) | `apps/api/src/modules/goal-dashboard/{goal-dashboard.controller.ts,goal-dashboard.service.ts,goal-dashboard.module.ts}` | ~120 |
| Frontend `/prospects`, `/cockpit`, `/portal` | `apps/web/src/app/prospects/`, `/cockpit/`, `/portal/` (con `(senior)` e `(nextgen)` route groups) | - |
| Componenti FE pesanti portal | `apps/web/src/components/portal/PatrimonioScoreBar.tsx` (720), `AiSuggestionsPanel.tsx` (542), `BreakdownCategoria.tsx` (317), `ComposizionePatrimonio.tsx` (288), `RiepilogoRapido.tsx` (250) | - |

## 2 · Modello concettuale

- **Prospect lifecycle** (`prospect.types.ts` `ProspectStatus`): `draft` → `enriching` → `ready` (post-orchestrator success) | `failed`. Convert `prospect → client` via `POST /prospects/:id/convert` (riusa tabella Client status=PROSPECT). PROSPECT è SEMPRE in chiaro nelle UI demo (vedi `valoswiss-client` §2bis).
- **Enrichment pipeline** (`enrichment/orchestrator.service.ts`, 512 LOC): 8 provider chained — Cerved (657 LOC, fiscal+credit data IT), Catasto (399 LOC, immobili), WebSearch (335 LOC, Brave/SerpAPI), Wikidata (224 LOC, structured biography), IdentityExtractor (234 LOC, regex+LLM facts), LlmKnowledge (210 LOC, Gemini), BiographyExtractor (153 LOC), InpsEstimator (136 LOC, pension proxy), PageFetcher (123 LOC, scraping HTML). Pattern background: NON usa TenantPrismaService request-scoped, riceve `tenantId` direttamente + PrismaClient stand-alone con `set_config`.
- **Engagement pipeline** (`engagement/orchestrator.service.ts` 378 + `engagement-writer.service.ts` 356 + `acquisition-strategy.service.ts` 195 + `personalized-analysis.service.ts` 490 + `prospect-mentalist.service.ts` 166): on-demand artifact generation. Tipi: email, script call, action plan, profilo psicologico (mentalist).
- **Portal Generazionale** (commit `f3a526c` "feat(api): portal generazionale fase 0 - UxMode foundation"): `Client.uxModePreference: senior|nextgen|auto` (default `auto`). FE route groups `(senior)` (calmer, larger fonts, simplified) vs `(nextgen)` (mobile-first, gestures, gamification). Decide auto da `birthDate` (>60 → senior).
- **UHNW Cockpit** (`uhnw-cockpit.service.ts` 154 LOC): consolidato per `UHNW_CLIENT` pack — totalNetWorth (internal AUM + externalAUM), allocation 5 categorie (equity/fixed/alts/cash/RWA), currencyExposure, concentrationTop10Pct, familyAggregate (cross-cliente FamilyGroup).
- **FO Cockpit** (`fo-cockpit.service.ts` 148 LOC): Principal-first per `FAMILY_OFFICE_PRINCIPAL`. Sezioni: NetWorthTotal, Branches (rami familiari), IPS allocation Safety/Growth/Moonshots vs target (drift detection), liquidityRunwayMonths (cash+bond/spese mensili 40k€ placeholder), capitalCallsUpcoming Q3-Q1 (proxy 0.5-0.8% AUM), governanceSignals.
- **Portal AI Suggestions V2** (`portal-ai-suggestions.service.ts` 530): cache disco 12h key `md5(clientId+asOf+hash(snapshot))`. Pipeline: load cache → `Client.psychProfile` → pseudonymize nome (PII guard) → render prompt `portal.ai-suggestions.v1` da PromptStore → VertexGeminiService.generateJson → sanitize+order-by-priority. Tipi: rebalance|opportunity|protection|tax|liquidity. Priority: high|medium|low. NO fallback hardcoded — degrade onesto se LLM down.
- **Today Explainer** (`today-explainer.service.ts` 389 LOC): RULE-BASED, no AI calls in user path. Cache in-memory 1h per utente. 3 livelli: simple|detailed|action. Calcola portfolio context (totalToday/Yesterday/deltaPct/topGainer/topLoser) da Asset+PositionHistory+PortfolioSnapshot fallback.
- **Voice Briefing** (`voice-briefing.service.ts` 245 LOC): MP3 60s via Google TTS (Italian voice). Endpoint `GET /portal/voice-briefing` + `POST /portal/voice-briefing/prewarm/:userId` (loopback only).
- **Portal Cards SSE** (`portal.controller.ts` `/portal/stream`): Server-Sent Events stream con `cards` evento ogni 30s + `heartbeat` ogni 15s. Client portal mobile UX live updates.

## 2bis · Knowledge Base [popolata da deep-read]

### Pattern architetturali
- **Background pipeline lazy PrismaClient stand-alone** (`prospects.service.ts:42-46`): TenantPrismaService è REQUEST-scoped — non usabile in `fireEnrichment` background. Workaround: orchestrator riceve `tenantId` esplicito, istanzia PrismaClient locale con `set_config('app.tenant_id', $1, true)`.
- **Lead state machine** (`prospects.service.ts:create` 139-191): `prospectInfo.status = 'draft' | 'enriching'`. Default `draft`. Se `dto.launchEnrichment=true` → `enriching` + `fireEnrichment(...)` fire-and-forget. UX voluto: advisor inserisce dati + controlla note + clicca "🚀 Lancia Elaborazione" (POST `/prospects/:id/enrich`).
- **GDPR retention** (`prospects.service.ts:38-39`): NO purge automatico, NO soft-delete temporizzato. Hard delete su richiesta esplicita advisor (`DELETE /prospects/:id`).
- **`launchEnrichment` 1-click flow**: opzionale fast-path, salta stato `draft`. Default false (= "salva bozza, lancio dopo").
- **`prospectInfo.invite.invitedByAdvisorId`** (`prospects.service.ts:71-79`): dopo invito portal, `Client.userId` punta a nuovo user PROSPECT. Per non perdere lista per-advisor, query `OR` su `userId` + `prospectInfo.path` JSON.
- **Portal AI Suggestions cache key** (`portal-ai-suggestions.service.ts:computeCacheKey`): `md5(clientId + asOf + hash(snapshot))`. Snapshot include totals/performance/riskMetrics/breakdown/topMovers — qualsiasi cambio invalida cache. TTL 12h.
- **PII pseudonimo via `pseudonymForClientId`** (`portal-ai-suggestions.service.ts:38`): nome cliente NON esce verso provider LLM. Sostituito con "Cliente A/B/C…" prima del prompt render.
- **PromptStore service** (`portal-ai-suggestions.service.ts:37`): prompt key `portal.ai-suggestions.v1` letta da DB versionata, non hardcoded. Permette tuning senza redeploy.
- **TodayExplainer rule-based** (`today-explainer.service.ts:55-106`): NO chiamate AI in user path (latency cliente). Tutto rule-based su portfolio delta. AI invocata solo via `/portal/explain-deeper` endpoint separato.
- **resolveClientIdParam** (`portal.controller.ts:68-139`): security gate per CLIENT/PROSPECT (force own clientId, throw Forbidden se mismatch); ADVISOR (verifica `advisorOwnsClient(user.id, rawParam)`); ADMIN/SUPERVISOR pass-through. Speciale `me` → resolve via JWT `userId`.
- **Preview-mode SUPERVISOR/ADMIN** (`portal.controller.ts:84-111`): può forzare un client del proprio tenant per debug/QA. Filter tenant via Prisma RLS garantisce isolation.
- **Prospect bootstrap demo** (`prospects-bootstrap.service.ts` 198 LOC): seed iniziale demo data per nuovo tenant. Pattern: clone template prospects + arricchimento mock.
- **UHNW allocation euristica placeholder** (`uhnw-cockpit.service.ts:74-80`): `Equity 45%, Fixed 25%, Alts 15%, Cash 10%, RWA 5%` hardcoded — finche non collegato a positions reali. Stessa logica `currencyExposure` 60/25/10/5 EUR/USD/CHF/GBP. Concentration top10 = 38% costante. **Da raffinare** con allocation calcolata da Asset.category aggregata.
- **FO IPS drift band** (`fo-cockpit.service.ts:99-106` + `IPS_TARGETS = {safety: 0.25, growth: 0.6, moonshots: 0.15}`): `ipsSlice` calcola `pct = abs(diff/target)`, band `<5%=on-target`, `<15%=drift`, `≥15%=rebalance`. Hardcoded targets `safety/growth/moonshots` — **da collegare** a `IpsPolicy` dinamico (vedi `valoswiss-portfolio` IPS Engine).

### Decisioni storiche
- **Commit `4a69b1e` (`portal-financial.service.ts:1-558` + `portal-ai-suggestions.service.ts:1-530`)**: portal V2 cards + AiSuggestionsPanel V2 + dossier real-data ("feat(portal): real-data /portal with PortalFinancialData").
- **Commit `8a9b493` (`apps/web/src/lib/persona-packs.ts:1-687`)**: rifondazione platform su 3 personas — cliente↔advisor↔admin cascade con UI differenziate per ruolo.
- **Commit `56116a6` (`personalized-analysis.service.ts:1-490`)**: deep personalized analysis + portal generazionale wow effects ("feat(prospect+portal): deep personalized analysis + generational portal wow").
- **Commit `12f56db` (`personalized-analysis.service.ts:78-145`)**: rationale evidence-based per insight generation con citazioni provider (Cerved/Catasto/Wikidata).
- **Commit `6a66ba9` (`enrichment/orchestrator.service.ts:1-512`)**: introduzione pipeline 8 provider Gemini+Wikidata+identity-extractor. Prima era single-source.
- **Commit `b5d02ce` (`enrichment/page-fetcher.service.ts:1-123`)*

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