document vault

# valoswiss-document-vault — Esperto Document Vault, Vault Messages & NextGen Academy

Sei l'agente esperto del **document vault** ValoSwiss: repository documenti metadata-only con sharing per ramo familiare, secure messaging advisor↔client legato ai documenti, NextGen Academy (education + paper trading + sub-account training wheel).

> **Boundary chiaro**: 
> - `valoswiss-document-vault` (questo) = **storage metadata + sharing policies + lifecycle**
> - `valoswiss-vault-pii` = **encryption envelope KEK+DEK + redaction PII + lockdown policy DAEO**
> - `valoswiss-ingestion` (Magic Upload) = **OCR + extraction + classification AI** (può essere upstream del vault)

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/document-vault/ apps/api/src/modules/nextgen-academy/ 2>/dev/null
```

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

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Document Vault service | `apps/api/src/modules/document-vault/document-vault.service.ts` | 283 |
| Document Vault controller | `apps/api/src/modules/document-vault/document-vault.controller.ts` | 119 |
| Document Vault module | `apps/api/src/modules/document-vault/document-vault.module.ts` | 10 |
| NextGen Academy service | `apps/api/src/modules/nextgen-academy/nextgen-academy.service.ts` | 421 |
| NextGen Academy controller | `apps/api/src/modules/nextgen-academy/nextgen-academy.controller.ts` | 104 |
| FE document-vault page | `apps/web/src/app/document-vault/page.tsx` | - |
| FE wealth-vault page | `apps/web/src/app/wealth-vault/page.tsx` | - |
| FE asset-upload (upstream pipe) | `apps/web/src/app/asset-upload/page.tsx` | - |
| Schema Prisma | `VaultDocument`, `VaultMessage`, `AcademyCourse`, `AcademyProgress`, `PaperPortfolio`, `SubAccount`, `ClientDocument`, `OfficeDocument` | - |

## 2 · Modello concettuale

Tre sotto-aree distinte sotto lo stesso ombrello:

### Document Vault (Citi/Aleta/Masttro pattern, MVP Fase 2)
- **Metadata-only**: `VaultDocument` salva `{filename, mimeType, storageUrl, contentHash, sizeBytes, category, tags, encryption='AES_256_GCM' (default dichiarato), retentionUntil, status='ACTIVE'}`. **Cifratura at-rest gestita dallo storage layer**, non dal service.
- **Sharing dual-axis**: `sharedWithUserIds` (lista user puntuale) + `sharedWithBranches` (rami familiari abilitati). Family Group integration.
- **Categorie standardizzate**: `KYC | CONTRACT | TAX | STATEMENT | GOVERNANCE | OTHER`.
- **Access tracking**: ogni `getDoc()` incrementa `accessCount` + aggiorna `lastAccessedAt`/`lastAccessedBy` (compliance trail interno).
- **Lifecycle reapable**: `retentionUntil` ≤ `now()` → endpoint `/documents/reapable` lista candidati per cleanup batch (max 200 sort `retentionUntil asc`).

### Vault Messages (secure messaging advisor↔client legato a documenti)
- `VaultMessage`: `{senderId, recipientUserIds[], subject?, body, documentId?, threadId?, encryption='AT_REST', readByUserIds[], status='SENT'}`.
- Read tracking: `markRead()` aggiunge userId a `readByUserIds` set.

### NextGen Academy (Fase 3 Differentiation, $84T great wealth transfer)
- **Education tracker**: `AcademyCourse` (slug, level BEGINNER/INTERMEDIATE/ADVANCED, durationMinutes, pointsReward, visibleToPacks[]) + `AcademyProgress` (progressPct, streakDays, pointsEarned). Pattern Walton/Pritzker famiglie + Robinhood Cortex education + Acorns gamification.
- **Paper portfolio**: sandbox trading virtuale `PaperPortfolio` con leaderboard (`paperLeaderboard()` sort `currentValue desc` top 20). Trade BUY/SELL con avgPrice update logica + max 500 trades retained.
- **Sub-account training wheel**: capitale reale limitato `SubAccount` con `dailyTradeLimit`, `monthlyTradeLimit`, `allowedAssetClasses[]`, `forbiddenAssetClasses[]`, `approvalThreshold`. Per heir/figli sotto soglia.

## 2bis · Knowledge Base

### Pattern architetturali
- **Metadata vs Encryption boundary chiaro** (`document-vault.service.ts:17-22`): esplicita "cifratura at-rest e' gestita dallo storage layer; questo service memorizza solo l'algoritmo dichiarato per audit". Service NON cifra/decifra. `encryption` field è label dichiarativa (default `AES_256_GCM`). Confronta con `valoswiss-vault-pii` (apps/vault-api separata) che gestisce envelope encryption KEK+DEK reale.
- **Sharing dual-axis user+branch** (`document-vault.service.ts:135-150`): array `sharedWithUserIds` + `sharedWithBranches` (entrambi `string[]`). Branch = ramo familiare (es. `branch:family-rossi-genitori` vs `branch:family-rossi-figli`). Permission check non implementato in service (delegato a future middleware o check in caller).
- **Access tracking transparent** (`document-vault.service.ts:80-94`): `getDoc()` in single transaction increment + return DTO. Permette analytics "doc più letti" ma anche audit "chi ha scaricato cosa quando".
- **Reapable lifecycle** (`document-vault.service.ts:161-171`): `listReapable()` query `status: 'ACTIVE' AND retentionUntil <= NOW()`. Sort asc per processare i più vecchi prima. Cap 200 per batch.
- **NextGen multi-persona visibility** (`nextgen-academy.controller.ts:18-30`): `@PersonaConditional` decora con personas che vedono il modulo: `NEXTGEN_HEIR`, `RETAIL_CLIENT`, `AFFLUENT_CLIENT`, `UHNW_CLIENT`, `FAMILY_OFFICE_PRINCIPAL`, `FAMILY_OFFICE_STAFF`, `ADVISOR`, `RELATIONSHIP_MANAGER`, `SUPERVISOR_PLATFORM`. SUPERVISOR vede sempre.
- **Paper Portfolio modes** (`nextgen-academy.service.ts:225-240`): `mode: 'NORMAL'|'LEAGUE'`. League → `leagueRank` calcolato. Trade validation: BUY checks `currentValue ≥ cost`, SELL checks position quantity sufficient.
- **Course visibility per pack** (`nextgen-academy.service.ts:100-110`): `visibleToPacks: string[]` filtra corsi per persona pack. Empty = visibile a tutti. Filter post-fetch (Prisma non supporta efficient array contains in this case).
- **Slug auto-generated** (`nextgen-academy.service.ts:415-421`): `slugify()` lowercase + `[^a-z0-9]+ → -` + max 80 char. Idempotent.
- **DTO Mapping consistente** (`document-vault.service.ts:22-54` + `nextgen-academy.service.ts:16-76`): `toDocDto`, `toMsgDto`, `toCourseDto`, `toProgressDto`, `toPaperDto`, `toSubAccountDto` — tutte le entity Prisma → DTO esposti via API. `Date.toISOString()` su tutte le date.
- **Trade BUY/SELL atomic JSONB update** (`nextgen-academy.service.ts:255-285`): `positions[]` + `trades[]` aggiornati in una sola transaction Prisma. `trades.slice(-500)` cap retention contro JSONB bloat.

### Decisioni storiche
- **Commit `8ed6f37` (feat slice-1-4)**: introdotti i 16 nuovi domain modules — incluso `document-vault` (Fase 2 Operational Moat) e `nextgen-academy` (Fase 3 Differentiation). Schema, registry, sidebar.
- **Decisione 2026-04-23 (handoff Fase 2)**: Document Vault deliberatamente metadata-only — la cifratura è layer separato (`apps/vault-api` envelope encryption KEK+DEK gestito da `valoswiss-vault-pii`). Questo permette deploy Fase 2 senza dipendenza vault-api ready.
- **Decisione 2026-04-24 (handoff Fase 3)**: NextGen Academy come sub-app dedicata al `$84T great wealth transfer`. Tre verticali: education (corsi+streak), paper trading (Robinhood Cortex pattern), sub-account training wheel (capitale reale limitato per heir).
- **Pattern Citi Private Bank Vault + Aleta + Masttro**: sharing per branch family + secure messaging legato ai documenti. Modello consolidato fintech UHNWI per multi-generation governance.
- **Pattern Walton/Pritzker + Robinhood Cortex + Acorns**: NextGen multi-livello — corsi educational (Walton/Pritzker), paper trading sandbox (Robinhood), gamification streak/points (Acorns).

### Edge cases noti
- **Document senza `clientId` né `familyGroupId`** (`document-vault.service.ts:60-80`): documento "globale" (es. brochure tenant). `listDocs()` senza filter li ritorna comunque. Pattern usato per OfficeDocument-style content.
- **Retention NULL** (`document-vault.service.ts:120-128`): documento "perpetuo", non finisce mai in reapable list. Default per documenti governance critici.
- **Trade BUY senza capitale sufficiente** (`nextgen-academy.service.ts:262-265`): throw `BadRequestException('insufficient virtual capital')`. Frontend deve gestire UX prima di chiamare API.
- **Trade SELL senza quantity sufficiente** (`nextgen-academy.service.ts:268-273`): throw `BadRequestException('not enough quantity to sell')`.
- **Course completed before enroll** (`nextgen-academy.service.ts:139-152`): `enroll()` idempotente — se progress esiste già, ritorna existing senza recreate. `updateProgress()` con `progressPct ≥ 100` → status `COMPLETED` + `completedAt: now()` + increment `completionCount` + assign `pointsEarned = course.pointsReward`.
- **Trades cap** (`nextgen-academy.service.ts:274`): `trades.slice(-500)` — solo ultimi 500 trades retained per portafoglio (anti-bloat JSONB).
- **Message thread null** (`document-vault.service.ts:200-210`): `threadId` opzionale. Senza thread = messaggio standalone (es. notifica documento upload pending).
- **Sub-account approvalThreshold null** (`nextgen-academy.service.ts:355-365`): nessuna soglia approvazione → tutti i trade passano (potential moral hazard se accidentale).

### Bug ricorrenti
- **Sharing user removed → orphan permission** (`document-vault.service.ts:135-150` schema array `sharedWithUserIds`): se userId rimosso da User table ma resta nell'array, doc accessibile a userId fantasma con stesso valore. Cleanup periodico raccomandato (cron mensile + Prisma cascade).
- **Family Group rinominato** (`document-vault.service.ts:140-148`): `sharedWithBranches[]` contiene string identifier. Se branch slug cambia in family-group module senza migration → permission silently broken. Mitigation: usare ID stabili in branches, non slug.
- **Reapable lista non processata** (`document-vault.service.ts:161-171`): senza cron scheduled cleanup, documenti restano `ACTIVE` con `retentionUntil` passato. Endpoint solo lista, non auto-archive. **Workaround**: aggiungere cron `0 3 * * *` chiama `/reapable` + batch update status `ARCHIVED`.
- **Paper Portfolio leaderboard staleness** (`nextgen-academy.service.ts:280-300`): `currentValue` aggiornato solo a trade. Se mercato muove ma utente non trade, leaderboard `currentValue` resta vecchio. Pattern aspettato per simulazione (no real-time mark-to-market).
- **Trade SELL drift decimale** (`nextgen-academy.service.ts:263-265`): `positions[idx].quantity` può essere number con drift decimale (BUY 10.000001, SELL 10 → resta 0.000001). Strict `<` check blocca SELL su qty corretta. Fix: epsilon tolerance `+ 0.0001`.

## 3 · SSOT — File fonte verità

| Cosa | Path assoluto |
|------|---------------|
| Document Vault service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/document-vault/document-vault.service.ts` |
| Document Vault controller | `/Users/crisescla/git/valoswiss/apps/api/src/modules/document-vault/document-vault.controller.ts` |
| NextGen Academy service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/nextgen-academy/nextgen-academy.service.ts` |
| NextGen Academy controller | `/Users/crisescla/git/valoswiss/apps/api/src/modules/nextgen-academy/nextgen-academy.controller.ts` |
| Schema DB | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (`VaultDocument`, `VaultMessage`, `AcademyCourse`, `AcademyProgress`, `PaperPortfolio`, `SubAccount`) |
| Magic Upload (upstream) | `/Users/crisescla/git/valoswiss/apps/api/src/modules/magic-upload/magic-upload.service.ts` |
| Lockdown policy doc | `/Users/crisescla/git/valoswiss/docs/MODULE-LOCKDOWN-POLICY.md` (documentVault è DAEO TOP-5) |

## 4 · API & contracts

### Document Vault
| Endpoint | Method | Auth | Note |
|----------|--------|------|------|
| `/document-vault/documents` | GET | JWT + persona | filter `clientId`, `familyGroupId`, `category`, `limit` (max 500) |
| `/document-vault/documents/reapable` | GET | JWT + persona | docs con `retentionUnti

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