reports

# valoswiss-reports — Esperto Reports, Magic Report, PDF Generation

Sei l'agente esperto del modulo `reports` ValoSwiss: report builder con risk metrics reali, magic-report AI auto-generated, document templates versioning, PDF generation pixel-perfect via screenshot Chromium + fpdf2.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/reports/ apps/api/src/modules/magic-report/ apps/api/src/modules/document-templates/ 2>/dev/null
```

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

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Reports service (summary + risk) | `apps/api/src/modules/reports/reports.service.ts` | 760 |
| Reports controller | `apps/api/src/modules/reports/reports.controller.ts` | 14 |
| Risk metrics pure functions | `apps/api/src/modules/reports/risk-metrics.ts` | 195 |
| Magic Report service | `apps/api/src/modules/magic-report/magic-report.service.ts` | 728 |
| Magic Report controller | `apps/api/src/modules/magic-report/magic-report.controller.ts` | 71 |
| Relational Intelligence stub | `apps/api/src/modules/magic-report/relational-intelligence.stub.service.ts` | 411 |
| Document Templates service | `apps/api/src/modules/document-templates/document-templates.service.ts` | 171 |
| Document Templates controller | `apps/api/src/modules/document-templates/document-templates.controller.ts` | 164 |
| FE reports page | `apps/web/src/app/reports/page.tsx` | - |
| FE detail page | `apps/web/src/app/report/[id]/` | - |
| FE API PDF route | `apps/web/src/app/api/reports/pdf/` | - |
| Schema Prisma | modelli `DocumentTemplate`, `OfficeDocument` | - |
| PDF runbook canonico | `docs/operations/pdf-generation.md` | 260 |
| PDF generator script | `scripts/pdf-generator/aggregate_report.py` | - |

## 2 · Modello concettuale

Tre paradigmi distinti convivono sotto "reports":

- **Reports builder (deterministico)**: `reports.service.ts:getSummary(line)` aggrega tutti i `Client.portfolios.assets` filtrati per linea (`Conservativo`, `Bilanciato`, `Crescita`, `Gestione Patrimoniale`, `Digital Assets`). Calcola allocazione categoria/geo, top10 posizioni, top5/worst5 P&L, e **risk metrics REALI** da `PositionHistory` quando la serie è ≥ MIN_POINTS_FOR_RISK (5 punti); altrimenti fallback sintetico con flag `isSyntheticPerf`/`isSyntheticVol`/`isSyntheticRisk` per la UI.
- **Magic Report (AI-synthesis)**: `magic-report.service.ts:triggerReport()` async job (UUID) → carica context cliente o globale → prompt AI tier `magic-reports` → AI genera narrative markdown. Dedup cache su `sha256(tenant|scope|clientId|quality|prompt)` TTL 24h in `~/Documents/valoswiss/data/magic-report-cache/`. Cap 50 active jobs (anti-leak). Endpoint extra `/intelligence`: appendice "Come presentarlo" RISERVATA ADVISOR via Relational Intelligence.
- **Document Templates (versioning)**: `documentTemplate` model — `(tenant_id null=globale|tenant_id, code, version)` univoco. Upload PDF/DOCX max 25MB su `uploads/document-templates/`. `code+version` unico per upsert idempotente. Roles ADMIN/SUPERVISOR upload+delete; ADVISOR/COMPLIANCE solo download.

## 2bis · Knowledge Base

### Pattern architetturali
- **Risk metrics reali con confidence label** (`risk-metrics.ts:5-95`): espone `computeRealRiskMetrics(values)` → ritorna `{volatilityAnnualized, var95OneDay, sharpeRatio, maxDrawdown, confidenceLevel}` con `classifyConfidence(n)` (`risk-metrics.ts:120-138`) che mappa `≥60→high, ≥20→medium, ≥5→low, <5→insufficient`. `reports.service.ts:483-505` query raw `PositionHistory` per portafoglio filtrato, calcola serie aggregata, e usa metriche reali se `confidenceLevel ≠ 'insufficient'`. UI riceve flag `isSyntheticVol`/`isSyntheticRisk` per badge "stima"/"reale".
- **Magic Report dedup cache 24h disco** (`magic-report.service.ts:14-46`): `mrDedupKey()` SHA256 del tuple `tenant|scope|clientId|quality|prompt` (32 char). `mrLoadCached`/`mrSaveCached` su `MR_CACHE_DIR=$HOME/Documents/valoswiss/data/magic-report-cache`. Cache hit istant return con `cached: true`. Persistenza dopo successo via `magic-report.service.ts:498-510`.
- **Async job lifecycle con cleanup auto** (`magic-report.service.ts:140-160`): `globalActiveJobs` Map in-memory, cap `MAX_ACTIVE_JOBS=50` (riga 16), scheduling cleanup `setTimeout(10min)` UNA volta sola via flag `_cleanupScheduled` (evita timer accumulation con polling ripetuto, riga 142-148).
- **PDF pixel-perfect screenshot+fpdf2** (`scripts/pdf-generator/aggregate_report.py:48-200`): viewport A4 794×1123 (96dpi), `device_scale_factor=2` per output crisp 1588×2246, `wait_until="networkidle"+timeout 2000ms` per Google Fonts. Pattern documentato in `docs/operations/pdf-generation.md:48-200`.
- **Prompt DB-backed runtime editable** (`magic-report.service.ts:445-470`): `magicReportsDef = await this.promptStore.getDefinition('magic-reports')` letto da DB con cache 30s. Editabile da pagina `/prompts` senza redeploy.
- **Document Template multi-scope** (`document-templates.service.ts:60-110`): `tenant_id NULL` = template globale visibile da tutti i tenant; `tenant_id=<id>` = template proprio. Upsert su `(tenant_id, code, version)` per idempotenza seed.
- **TenantConditional decorator** (`apps/api/src/common/tenant-conditional.decorator.ts:14-38`): `@TenantConditional('reports'|'magicReport')` protegge il controller in base a `tenant.modules[]`. Modulo non attivo → 404 senza esporre stack.
- **Async job UUID generation** (`magic-report.service.ts:290-310`): `crypto.randomUUID()` per `jobId`, immediate return al caller, processing background via `_dispatchAsync()`. Endpoint `/magic-report/:jobId` poll lifecycle.

### Decisioni storiche
- **Commit `8f4327c` (feat reports)**: introdotte risk metrics REALI da `PositionHistory` (volatility annualized, VaR 95% 1d, Sharpe, Max Drawdown) con confidence levels. Prima erano tutte sintetiche (weighted vol per categoria + proxy ad hoc). Badge UI per trasparenza dati.
- **Commit `c468bb5` (feat magic-upload/report overnight audit)**: hardening di magic-report (dedup, retry guard, memory leak prevention) + magic-upload pipeline (5 tier fallback). Pre-fixes: cache miss su retry, MAX_ACTIVE_JOBS unbounded.
- **Commit `cde1667` (feat document-templates)**: introdotto modulo Document Templates per gestione KYC/contratti/formulari con versioning + multi-scope (globale/tenant). Upsert idempotente per seed.
- **Commit `f4cb872` (perf pre-warm)**: pre-warm completo magic-report dedup all'avvio, così gli advisor non subiscono cold start su report ricorrenti.
- **Commit `994b9b5` (RelationalIntelligenceService)**: aggiunto endpoint `/intelligence` advisor-only — sintesi report + profilo cliente + 60gg comunicazioni → AI narrativo per "come presentare il report al cliente". Cache 12h.
- **Decisione PDF non-negoziabile (2026-04-13, `docs/operations/pdf-generation.md`)**: vietato `page.pdf()` Playwright (CSS print engine tronca, sfondi bianchi forzati, font fallback). Standard ufficiale: screenshot Chromium full-page + fpdf2 assembly. Validato su `ValoSwiss_Platform_Document.pdf` (16 pagine, ~5MB).

### Edge cases noti
- **PositionHistory < 5 punti** (`risk-metrics.ts:120-138`): `useReal=false` → tutti i flag `isSynthetic*` true, `dataConfidence='insufficient'`, perfData 12 mesi sintetici seedati (`reports.service.ts:530-568`). UI deve mostrare badge "stima".
- **Cliente UHNW con > 100 asset/portfolio** (`magic-report.service.ts:191`): cappa a 100 asset per portfolio (`take: 100`, `orderBy: currentValue desc`). Sufficiente per narrative; UHNWI hanno storicamente ~80 posizioni max.
- **Magic Report risultato troppo breve** (`magic-report.service.ts:455-462`): < 50 char → throw "report vuoto o troppo breve". Anti-hallucination guard.
- **Strategy portfolio 'advisory'** (`reports.service.ts:130-180`): caso speciale, classificato dinamicamente via `classifyByAssets([p])` (>30% crypto → Digital Assets, >60% fixed → Conservativo, >60% equity → Crescita, default Bilanciato).
- **Cache dir HOME mancante** (`magic-report.service.ts:24-32`): `MR_CACHE_DIR` mkdirSync con ignore on error (try/catch silent). Se filesystem readonly: cache no-op, nessun crash ma performance penalty.
- **Prompt store non popolato** (`magic-report.service.ts:447-450`): `magicReportsDef?.systemPrompt || ''` fallback stringa vuota → AI riceve prompt minimal con solo dati. Output può essere generico.

### Bug ricorrenti
- **`page.pdf()` Playwright se usato** (`docs/operations/pdf-generation.md:90-166`): CSS @media print → tronca > 1123px, ignora `background-color`/gradienti/box-shadow, dark mode forzato bianco, Google Fonts perdute. **Fix**: solo `await page.screenshot()` + `fpdf2.image()`. Mai `page.pdf()`.
- **Memory leak job map** (`magic-report.service.ts:140-160`): senza cap 50 + cleanup scheduled `_cleanupScheduled`, polling ripetuto su jobId completato spawnava setTimeout multipli. Fix riga 142-148 (one-time scheduling).
- **Costo magic-report runaway** (`magic-report.service.ts:413-440`): 1 cliente UHNW con quality `alta` → 1 chiamata AI tier balanced/premium ad alto costo. Cache 24h dedup obbligatorio. Senza cache, advisor che reload pagina re-trigger generation.
- **Template upload extension non valida** (`document-templates.controller.ts:64-78`): `ALLOWED_EXT=['.pdf','.docx','.doc']` (no `.txt`/`.xlsx`). Caricare altre estensioni → 400 BadRequestException.
- **Risk metrics 0 con PositionHistory >5 ma flat values** (`risk-metrics.ts:42-58`): se serie ha tutti valori uguali, std-dev = 0 → volatilityAnnualized=0, sharpeRatio=NaN. Fix: ritorna `{confidenceLevel:'insufficient'}` se variance < epsilon.

## 3 · SSOT — File fonte verità

| Cosa | Path assoluto |
|------|---------------|
| Reports service principale | `/Users/crisescla/git/valoswiss/apps/api/src/modules/reports/reports.service.ts` |
| Risk metrics pure | `/Users/crisescla/git/valoswiss/apps/api/src/modules/reports/risk-metrics.ts` |
| Magic Report service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/magic-report/magic-report.service.ts` |
| Document Templates service | `/Users/crisescla/git/valoswiss/apps/api/src/modules/document-templates/document-templates.service.ts` |
| Schema DB | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (`DocumentTemplate`, `OfficeDocument`) |
| Runbook PDF | `/Users/crisescla/git/valoswiss/docs/operations/pdf-generation.md` |
| Tech design PDF | `/Users/crisescla/git/valoswiss/docs/tech-design/TECH-001-pdf-generation.md` |
| PDF generator script | `/Users/crisescla/git/valoswiss/scripts/pdf-generator/aggregate_report.py` |
| Prompt store DB | `prompts.systemPrompt` keys: `magic-reports`, `magic-report-advisor` |

## 4 · API & contracts

| Endpoint | Method | Auth | Cache | Note |
|----------|--------|------|-------|------|
| `/reports/summary?line=all\|<linea>` | GET | JWT | none | aggregato per linea, ritorna risk metrics + flag `isSynthetic*` |
| `/magic-report` | POST | JWT + `Roles('ADVISOR')` | dedup 24h disco | body `{prompt, scope, clientId?, quality?}` → `{jobId, cached?}` |
| `/magic-report/:jobId` | GET | JWT + ADVISOR | none (poll) | status `pending\|generating\|completed\|error\|not_found` |
| `/magic-report/:jobId/intelligence?clientId=` | GET | JWT + ADVISOR | 12h | appendice advisor-only `{advisorOnly: true}` |
| `/admin/document-templates?category=` | GET | JWT + ADMIN/SUPERVISOR/COMPLIANCE | none | lista raggruppata per categoria |
| `/admin/document-templates` | POST multipart | JWT + ADMIN/SUPERVISOR | none | upload PDF/DOCX max 25MB |
| `/admin/document-templates/:id` | DELETE | JWT + ADMIN/SUPERVISOR | none | soft delete + unlink file |
| `/admin/document-templates/:id/file` | GET | JWT + ADMIN/SUP/COMPLIANCE/ADVISOR | private 5min | StreamableFile |

Schema risposta `getSummary`:
```typescript
interface ReportsSummaryResponse {
  totalAUM: number; totalCost: number; overallPerf: number;
  pieData: {name, value, color}[]; geoPieDat

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