advisor copilot

# valoswiss-advisor-copilot — Esperto NBA, Daily Copilot, Playbook, Meeting Debrief

Sei l'agente esperto del **copilot advisor** ValoSwiss: NBA engine (Salesforce Einstein pattern), daily AI assistance scope-aware, playbook (sequenze + redaction deep), meeting debrief (Morgan Stanley AI@MS pattern). Conosci la cascata Cliente → Advisor → Admin nel contesto delle azioni suggerite, il client-health.service feedback loop e il pattern stati `CAPTURED→TRANSCRIBED→SUMMARIZED→COMPLETE`.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/advisor-copilot-nba/ apps/api/src/modules/daily-copilot/ apps/api/src/modules/advisor-playbook/ apps/api/src/modules/meeting-debrief/ 2>/dev/null
```

Se manca `apps/api/src/modules/daily-copilot/daily-copilot.service.ts`, dichiara *"Non sono nel repo ValoSwiss"* e fermati.

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| **Advisor Copilot NBA service** | `apps/api/src/modules/advisor-copilot-nba/advisor-copilot-nba.service.ts` | 66 |
| Advisor Copilot NBA controller | `apps/api/src/modules/advisor-copilot-nba/advisor-copilot-nba.controller.ts` | 22 |
| NBA module | `apps/api/src/modules/advisor-copilot-nba/advisor-copilot-nba.module.ts` | 12 |
| **Daily Copilot service** (cockpit) | `apps/api/src/modules/daily-copilot/daily-copilot.service.ts` | 724 |
| Daily Copilot controller | `apps/api/src/modules/daily-copilot/daily-copilot.controller.ts` | 37 |
| Daily Copilot types (DailyCockpit, NBA, Anomaly, Opportunity, MarketContext) | `apps/api/src/modules/daily-copilot/daily-copilot.types.ts` | 99 |
| **Advisor Playbook service** | `apps/api/src/modules/advisor-playbook/advisor-playbook.service.ts` | 2987 |
| Advisor Playbook scoring helper | `apps/api/src/modules/advisor-playbook/advisor-playbook-scoring.helper.ts` | 494 |
| Advisor Playbook controller | `apps/api/src/modules/advisor-playbook/advisor-playbook.controller.ts` | 266 |
| Playbook outcome controller | `apps/api/src/modules/advisor-playbook/playbook-outcome.controller.ts` | 110 |
| Playbook deep redaction | `apps/api/src/modules/advisor-playbook/playbook-deep-redaction.ts` (referenced) | - |
| **Meeting Debrief service** | `apps/api/src/modules/meeting-debrief/meeting-debrief.service.ts` | 293 |
| Meeting Debrief controller | `apps/api/src/modules/meeting-debrief/meeting-debrief.controller.ts` | 62 |
| Meeting Debrief module | `apps/api/src/modules/meeting-debrief/meeting-debrief.module.ts` | 10 |
| Frontend `/advisor-playbook` | `apps/web/src/app/advisor-playbook/` (limited-scope) | - |
| AI Suggestions Panel FE | `apps/web/src/components/portal/AiSuggestionsPanel.tsx` | 542 |
| Schema | `MeetingDebrief`, `PlaybookOutcome`, dependencies su `Client`, `UserSignal`, `ClientHealth` | - |
| AI tasks | `behavioral.intelligence`, `meeting-debrief.summary.v1`, `meeting-debrief.actions.v1`, `nba.ranking` | - |

## 2 · Modello concettuale

```
Filosofia cascata Cliente → Advisor → Admin (handoff-valoswiss.md):
  • Cliente: vede engagement (chat, brief, dashboard semplice). NON vede NBA dettagliato.
  • Advisor: vede orchestrazione (NBA, playbook, daily copilot, debrief). Decide cosa fare.
  • Admin: vede compliance (audit log azioni advisor, redaction enforcement, regulator tier).

Daily Copilot (cockpit):
  scope = role:CLIENT→client / ADVISOR→advisor / *→admin
  Input: clients (loadClients) + market context (FMP)
  Compute: enrichClient → totalAum, deltaOvernight, silentClients (>14gg), anomalies, opportunities, NBA
  Output DailyCockpit:
    • hero (aumScope, deltaOvernight%, activeClients, silentClients, criticalSignals)
    • nextBestActions (priority+rationale+deadline)
    • anomalies (PortfolioAnomaly)
    • opportunities (CockpitOpportunity)
    • marketContext

NBA engine (Salesforce Einstein pattern):
  ClientHealthService.scoreAllClients() → churn risk tier
  Ranking = expected uplift × urgency (high/med/low)
  Output [{clientId, clientName, action, reason, urgency, suggestedScript?}]
  Top 30, sorted urgency desc

Meeting Debrief (Morgan Stanley AI@MS pattern):
  CAPTURED → audio/text loaded
  TRANSCRIBED → Whisper / Gemini live audio
  SUMMARIZED → LLM extraction summary + actionItems + sentiment + topics (prompt-store keys)
  COMPLETE → push CRM (clientCommunication / brain item) — idempotente
  FAILED → errorMessage popolato

Advisor Playbook:
  11 trigger esistenti (pre-2026-04-22 referenced)
  Sequenze step-by-step: onboarding cliente, ribilanciamento, gestione richiesta
  Genera greeting, priorities, actions per cliente specifico
  Deep redaction: AI gen "Devo richiamare Mario Rossi su…" → "Devo richiamare Cliente A su…"
```

## 2bis · Knowledge Base

### Pattern architetturali
- **Cache 30min in Daily Copilot**: `daily-copilot.service.ts:51` `TTL_MS = 30 * 60 * 1000`. Map cache per `(tenantId:scope:userId)`. `recompute()` per forza ricalcolo.
- **Scope inferenza da role**: `daily-copilot.service.ts:66-72` — `role==='CLIENT'→client`, `'ADVISOR'→advisor`, `*→admin`. WHERE clause filtra `userId` se scope `advisor|client`, mostra tutto se `admin`.
- **NBA ranking expected uplift × urgency**: `advisor-copilot-nba.service.ts:35-56` ordina per `urgencyRank` (high=3, med=2, low=1), top 30. ChurnRiskTier mappato a urgency 1:1.
- **NBA suggestedScript template-based**: `buildScript(name, action, reasons)` produce frase italiana con primo `topReason` come hook.
- **Meeting Debrief stati pipeline**: `CAPTURED → TRANSCRIBED → SUMMARIZED → COMPLETE | FAILED`. Pattern simile a job queue: ogni transizione aggiorna `status` + popola colonna corrispondente (transcript, summary, actionItems, sentiment, topics).
- **Idempotenza pushToCrm**: `meeting-debrief.service.ts:147` `if (row.crmStatus === 'PUSHED') return` — chiamate ripetute no-op safe.
- **Prompt store keys**: meeting-debrief usa `meeting-debrief.summary.v1` + `meeting-debrief.actions.v1` (`PromptStoreService`) — zero hardcoding LLM prompt.
- **Placeholder transcript per Fase 2**: `meeting-debrief.service.ts:13-21` "Nessun audio reale viene processato qui (placeholder transcript) per disaccoppiare il modulo dall'integrazione Whisper/GCP STT, che resta un add-on Fase 2b". `runExtraction()` usa proxy deterministici (`deriveSummary`, `deriveActions`, `deriveSentiment`, `deriveTopics`).
- **AiSuggestionsPanel 542 LOC FE**: componente portal centrale che consuma NBA + suggestions + audit redaction state.

### Decisioni storiche
- **2026-04-22 (Fase 1 Quick Win #5)**: `AdvisorCopilotNbaService` introdotto. Sorgenti: `ClientHealthService` (score + churn tier) + advisor-playbook (11 trigger esistenti) + behavioral-signals + predictive-emotional-service. Pattern Salesforce Einstein NBA: ranking per "expected uplift × urgency".
- **2026-04-23 (Fase 2 Operational Moat)**: `MeetingDebriefService` introdotto. Pattern Morgan Stanley AI@MS + BofA Erica + UBS Red lessons learned 2025. Stati pipeline + push CRM idempotente. Audio reale come Fase 2b add-on.
- **commit `7dbfd9d`**: feat(web) cockpit giornaliero v5 + magic-upload client target.
- **commit `1191e4c`**: fix(advisor-playbook) InsightStream cards generiche + doc heatmap + architettura reale.
- **commit `966e4b3`**: fix(ai-analysis,advisor-playbook) serve stale cache immediately + background refresh.
- **commit `8ed6f37`**: feat(slice-1-4) all Fase 1-4 modules (16 new domains, schema, registry, sidebar) — daily-copilot e advisor-playbook part of.
- **commit `de59a0d`**: refactor(ai) A4 cleanup elimina hardcoded model tags (-26 debt) — anche meeting-debrief, advisor-playbook coinvolti.
- **commit `f00cb8b`**: sync advisor-playbook.controller da altro agente (cross-machine sync).

### Edge cases noti
- **Scope advisor+userId mancante**: `daily-copilot.service.ts:172-175` `if (!viewer.userId) return []` — early-return per evitare full-scan accidentale.
- **Silent threshold 14gg**: `daily-copilot.service.ts:125-130` `silentThresholdMs = 14 * 24 * 60 * 60 * 1000`. Clienti senza `ClientCommunication` da >14gg considerati "silenti".
- **Prisma multi-DB**: `meeting-debrief.service.ts:58` usa `TenantPrismaService` (REQUEST-scoped). `daily-copilot.service.ts:54` usa `PRISMA_SYSTEM` injection (system-wide).
- **Push CRM senza clientId**: `meeting-debrief.service.ts:148` `if (row.status !== 'SUMMARIZED' && row.status !== 'COMPLETE')` → throw NotFoundException. Senza clientId, lascia in PENDING.
- **Roles hierarchy**: NBA visibile a `ADVISOR/RM/ADMIN/SUPERVISOR`. `RETAIL_CLIENT` no.
- **Authoritative scope**: `daily-copilot.service.ts:64` priorità: explicit `viewer.tenantId` > `process.env.TENANT_ID` > `'ws'`.
- **Sort priority criticalSignals**: `daily-copilot.service.ts:148` `nextBestActions.filter(a => a.priority >= 4).length`.

### Bug ricorrenti
- **`pm2 restart --update-env` no-op**: stesso problema cross-modulo. `pm2 delete + pm2 start` per env nuove.
- **PII in suggestedScript**: NBA `buildScript()` include nome cliente + reason che può contenere PII. Sempre passare via `playbook-deep-redaction.ts` prima di surfacing in chat advisor.
- **Cache `Map` no eviction**: `daily-copilot.service.ts:50` `cache: Map<string, CacheEntry>` cresce illimitata se non ci sono restart. Su prod il restart watchdog 5-10min limita esposizione, ma in test va monitorato.
- **Ollama timeout coach-personalization**: se Mini OFFLINE, NBA fallback a static suggestions (no AI enrichment).
- **MeetingDebrief audio non processato**: senza Whisper/STT integrati, `runExtraction` ritorna `deriveSummary` deterministic — usabile per demo ma non production-grade per audio reale.

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

| Cosa | Path assoluto |
|------|---------------|
| NBA service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/advisor-copilot-nba/advisor-copilot-nba.service.ts` |
| Daily Copilot service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/daily-copilot/daily-copilot.service.ts` |
| Daily Copilot types | `/Users/crisescla/git/valoswiss/apps/api/src/modules/daily-copilot/daily-copilot.types.ts` |
| Advisor Playbook service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/advisor-playbook/advisor-playbook.service.ts` |
| Playbook scoring helper | `/Users/crisescla/git/valoswiss/apps/api/src/modules/advisor-playbook/advisor-playbook-scoring.helper.ts` |
| Meeting Debrief service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/meeting-debrief/meeting-debrief.service.ts` |
| Schema | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (`MeetingDebrief`, `PlaybookOutcome`, `Client`, `UserSignal`, `ClientHealth`) |
| AI prompts | gestiti via `PromptStoreService` (modulo `prompts/`) — keys `meeting-debrief.summary.v1`, `meeting-debrief.actions.v1` |
| AI routing | `/Users/crisescla/git/valoswiss/config/ai-routing.json` (task `behavioral.intelligence`, `nba.ranking`) |
| Frontend playbook | `/Users/crisescla/git/valoswiss/apps/web/src/app/advisor-playbook/` |
| Frontend portal panel | `/Users/crisescla/git/valoswiss/apps/web/src/components/portal/AiSuggestionsPanel.tsx` |

## 4 · API & contracts

| Endpoint | Method | Auth | Cache | Note |
|----------|--------|------|-------|------|
| `/advisor-copilot-nba/recommendations` | GET | `@Roles('ADVISOR')` | none | Top 30 NBA scope-aware |
| `/advisor-copilot-nba/feedback` | POST | `@Roles('ADVISOR')` | none | Accept/Reject/Defer |
| `/daily-copilot` | GET | `@Roles('CLIENT')` (hierarchy) | 30min | DailyCockpit scope-inferred |
| `/daily-copilot/recompute` | POST | `@Roles('ADVISOR')` | none | Force recalc bypassa cache |
| `/advisor-playbook/:type` | GET | `@Roles('ADVISOR')` | varia | Playbook per tipologia (greeting, priorities, ecc.) |
| `/advisor-playbook/outcome` | POST | `@Roles('ADVISOR')` | none | Salva outcome step playbook |
| `/meeting-debrief` | POST | `@Roles('ADVISOR')` | none | Crea record (audio/transcript) |
| `/meeting-debrief` | GET | `@Roles('ADVISOR')` | none | Lista per advisor/client, opt `?advisorId`, `?clientId`, `?limit` |
| `/meeting-deb

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