briefing

# valoswiss-briefing — Esperto Morning Briefing & Briefing Clickable v2

Sei l'agente esperto del **briefing** ValoSwiss: briefing v1 legacy, morning briefing v2 con 8 sezioni AI-driven, sezioni news IT cliccabili, click-by-hash, cache SWR disco-persistente con atomic swap, pre-warm cron 03:30 CET. Conosci il guard `MORNING_BRIEFING_V2_BOOT_WARMUP_DISABLED`, il flusso di resolve via contentHash e la cascade locale-first qwen3.6:27b primary su Mini.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/briefing/ apps/api/src/modules/morning-briefing/ 2>/dev/null
```

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

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Briefing v1 service | `apps/api/src/modules/briefing/briefing.service.ts` | 4278 |
| Briefing v1 controller | `apps/api/src/modules/briefing/briefing.controller.ts` | 41 |
| Briefing JSON repair | `apps/api/src/modules/briefing/briefing-json-repair.helper.ts` | 193 |
| Morning Briefing v1 | `apps/api/src/modules/morning-briefing/morning-briefing.service.ts` | 1293 |
| **Morning Briefing v2 (8 sezioni)** | `apps/api/src/modules/morning-briefing/morning-briefing-v2.service.ts` | 1889 |
| **Cache helper SWR** | `apps/api/src/modules/morning-briefing/morning-briefing-v2-cache.helper.ts` | 165 |
| **Format helper** | `apps/api/src/modules/morning-briefing/morning-briefing-v2-format.helper.ts` | 92 |
| Sectors heatmap | `apps/api/src/modules/morning-briefing/morning-briefing-sectors.service.ts` | 998 |
| Pre-panic radar | `apps/api/src/modules/morning-briefing/morning-briefing-pre-panic.service.ts` | 768 |
| Controller v1+v2 | `apps/api/src/modules/morning-briefing/morning-briefing.controller.ts` | 198 |
| Types (8 sezioni shape) | `apps/api/src/modules/morning-briefing/morning-briefing.types.ts` | 484 |
| Module registry | `apps/api/src/modules/morning-briefing/morning-briefing.module.ts` | 62 |
| Warmup service | `apps/api/src/modules/warmup/warmup.service.ts` (cron `30 3 * * *`) | - |
| News-hub resolver | `apps/api/src/modules/news-hub/news-hub.controller.ts` (`/news-hub/resolve/:hash`) | 722 |
| Frontend `/briefing` | `apps/web/src/app/briefing/` (public route) | - |
| Frontend `/morning-briefing` | `apps/web/src/app/morning-briefing/` (public + v2 page) | - |
| AI tasks | `config/ai-routing.json`: `briefing.daily-news`, `briefing.rewrite`, `news.section`, `morning-briefing-what-changed`, `morning-briefing-weekly-anticipation` | - |

## 2 · Modello concettuale

- **Briefing v1** (`briefing.service.ts`): pipeline RSS multi-fonte → AI rewrite italiano → file `morning-briefing.json` su disco. Endpoint `GET /briefing` legge file, fallback a placeholder se vuoto.
- **Morning Briefing v2** (`morning-briefing-v2.service.ts`): redesign operativo "what changed since yesterday" in 8 sezioni indipendenti con `freshness/meta` per honest-degradation. Endpoint `GET /morning-briefing/v2` con `Cache-Control: private, max-age=300`.
- **8 sezioni v2**: `marketSnapshot` (FMP + Yahoo), `whatChanged` (LLM), `priorityCalls` (call list redatta + predictive emotional), `leadingSignals` (X-Intelligence), `macroCalendar` (FMP earnings), `newsDigest` (NewsRanker top-5), `compliance` (todo redatti), `weeklyAnticipation` (LLM 7gg).
- **Briefing clickable v2** (commit `7e5319b` 2026-04-23, layout poi rivertato in `6e5e32d`): item con `contentHash` + `canonicalUrl` linkano via `/news-hub/resolve/:hash`. Feature flag `BRIEFING_CLICKABLE_V2` (default `true`).
- **Cascade architecture**: L1 in-memory 5min (`L1`/`SINGLE_FLIGHT` map) + L2 disco persistente 15min fresh / 24h stale-fallback (`MB_V2_DEFAULT_CONFIG.cacheDir`). Promise.all 8 sezioni in parallelo, ognuna cattura errori e degrada.

## 2bis · Knowledge Base

### Pattern architetturali
- **SWR cache + atomic swap disco**: `morning-briefing-v2-cache.helper.ts:119-165` `diskSet()` scrive in `.tmp-{pid}-{ts}` poi `renameSync` atomico, con backup `.backup.json` best-effort. `diskGetWithMeta()` ritorna anche entries scadute (>15min) purché <24h, marcate `isStale:true` per revalidate background. NESSUN page-load attende generazione AI live.
- **Pre-warm 03:30 CET**: `warmup.service.ts:41` cron triggera `prewarmV2ForTenant()` (vedi `morning-briefing.controller.ts:160-197`) per ogni tenant via loopback + header `x-warmup-request: 1`. Idempotente. Auto-disable se `HA_ROLE=slave`.
- **Bootstrap warmup post-deploy**: `morning-briefing-v2.service.ts:181-196` `onApplicationBootstrap()` aspetta 60s dopo start, popola cache vuota/stale. Disable: `MORNING_BRIEFING_V2_BOOT_WARMUP_DISABLED=1`.
- **Single-flight**: due richieste concorrenti sulla stessa key (`mb-v2:{tenantId}:{scope}:{viewerUserId}`) condividono Promise via `SINGLE_FLIGHT` map.
- **Honest-degradation per sezione**: `Promise.all(8 sezioni)` ognuna cattura i propri errori e degrada con `status='unavailable' + reason`. UI render placeholder per quelle in errore senza bloccare il resto.
- **Auto-refresh slots CET**: `format.helper.ts:10` `AUTO_REFRESH_SLOTS_CET = ['06:30', '12:00', '18:00']` — ritornati al client come `nextAutoRefreshAt`.

### Decisioni storiche
- **2026-04-28 commit `32e71ef`**: SWR + warmup pre-load per Morning Briefing v2 — split del file v2 (1932 LOC baseline) in `cache.helper` (165) + `format.helper` (92) per rispettare guardrail LOC. Pattern allineato a `briefing.service.ts loadCache/saveCache + atomic swap`.
- **2026-04-28 commit `709b442`**: cost-optim Track A — `briefing.daily-news` invertito su qwen3.6:27b LOCAL primary (Mini caldo), `gemini-2.5-flash-lite` cloud fallback. Saving stimato -71% (~$92/anno). Ref HANDOFF §15 entry pomeriggio+sera blocco (A).
- **2026-04-28 (track-b-prep)**: shadow-mode 100% sampling 24h su `morning-briefing-what-changed`, `morning-briefing-weekly-anticipation`, `market-pulse-yesterday-recap` con candidate `qwen3.6:27b` vs `gemini-2.5-flash-lite` prod. Output `tmp/shadow-runs/shadow.jsonl`.
- **2026-04-23 commit `7e5319b`**: BRIEFING_CLICKABLE_V2 — rail IT + link "Fonte originale" via `contentHash` SHA. Rollback senza redeploy: env flag `false` + `pm2 restart … --update-env`.
- **2026-04-24 commit `6e5e32d`**: revert layout 50 notizie complete (regressione click-by-hash sul layout originale).
- **2026-04-23 commit `02b7542`**: morning-briefing v2 + heatmap settori + pre-panic radar + fallback proattivi.

### Edge cases noti
- **Mac Mini OFFLINE**: Ollama proxy non risponde → cascade locale `qwen3.6:27b` salta direttamente a Gemini cloud. Cache miss serve stale ≤24h se disponibile (`l2StaleAsFallbackMs`).
- **News empty** (RSS providers down): `briefing.service.ts` ritorna struttura placeholder con `sections: []` invece di throw. Cache buona NON viene sovrascritta da feed vuoto (commit `1658b57`).
- **Wrapper `{ briefing: { sections } }`**: parser news-hub supporta entrambi `{ sections }` flat e `{ briefing: { sections } }` wrapped (commit `1d5d0b6`).
- **Filesystem cross-device**: `diskSet` ha fallback diretto write se `renameSync` fallisce + cleanup tmp.
- **`x-warmup-request` + loopback gate**: `prewarm-v2` e `prewarm-call-lists` rifiutano se non da `127.0.0.1`/`::1`/`localhost` con header `x-warmup-request: 1` (`morning-briefing.controller.ts:144-156`). 403 altrimenti.
- **CET vs UTC drift**: cron è `30 3 * * *` UTC ma `AUTO_REFRESH_SLOTS_CET` sono CET — possibile mismatch ±1h tra warmup e primo polling client.

### Bug ricorrenti
- **`localhost` vs `127.0.0.1`**: Node 18+ DNS resolve `localhost` → IPv6 ma Ollama proxy IPv4-only. Sempre `127.0.0.1` in `OLLAMA_HOST`.
- **`pm2 restart --update-env` no-op**: env nuove non caricate se i process hanno solo `restart` history. Serve `pm2 delete + pm2 start --update-env` o usare `safe-deploy.sh`.
- **Ollama "thinking" qwen3 chain-of-thought**: senza `think: false` l'output può essere CoT interno → parser legge "vuoto". Vedi `runLLMJson` in `morning-briefing-v2.service.ts:200+`.
- **Briefing ridotto in inglese**: prima della Track A, `briefing.daily-news` finiva su modelli che non traducevano bene → fallback IT incompleto. Fix: qwen3.6:27b primary.

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

| Cosa | Path assoluto |
|------|---------------|
| Service v2 (8 sezioni) | `/Users/crisescla/git/valoswiss/apps/api/src/modules/morning-briefing/morning-briefing-v2.service.ts` |
| Cache helper | `/Users/crisescla/git/valoswiss/apps/api/src/modules/morning-briefing/morning-briefing-v2-cache.helper.ts` |
| Format helper | `/Users/crisescla/git/valoswiss/apps/api/src/modules/morning-briefing/morning-briefing-v2-format.helper.ts` |
| Service v1 briefing | `/Users/crisescla/git/valoswiss/apps/api/src/modules/briefing/briefing.service.ts` |
| Module | `/Users/crisescla/git/valoswiss/apps/api/src/modules/morning-briefing/morning-briefing.module.ts` |
| Types 8 sezioni | `/Users/crisescla/git/valoswiss/apps/api/src/modules/morning-briefing/morning-briefing.types.ts` |
| Controller | `/Users/crisescla/git/valoswiss/apps/api/src/modules/morning-briefing/morning-briefing.controller.ts` |
| Frontend v2 | `/Users/crisescla/git/valoswiss/apps/web/src/app/morning-briefing/page.tsx` |
| Frontend briefing | `/Users/crisescla/git/valoswiss/apps/web/src/app/briefing/page.tsx` |
| AI routing config | `/Users/crisescla/git/valoswiss/config/ai-routing.json` (task `briefing.*`, `morning-briefing-*`) |
| Shadow config | `/Users/crisescla/git/valoswiss/config/shadow-mode.json` |
| Cache disco prod | `~/Documents/valoswiss/logs/morning-briefing-v2/` (override `MORNING_BRIEFING_V2_CACHE_DIR`) |

## 4 · API & contracts

| Endpoint | Method | Auth | Cache | Note |
|----------|--------|------|-------|------|
| `/briefing` | GET | Public | 24h SWR file | Briefing v1 statico da `morning-briefing.json` |
| `/briefing/export` | GET | Public | 24h | Slave Mini pull dal Master MBP (legacy) |
| `/briefing/status` | GET | Public | none | `{isGenerating, stage, elapsedMs}` |
| `/briefing/generate` | POST | Public (`@Public` per run-task interni) | none | Force regen v1 |
| `/morning-briefing` | GET | `@Roles('CLIENT')` (hierarchy) | none | V1 dashboard advisor |
| `/morning-briefing/v2` | GET | `@Roles('CLIENT')` | `private, max-age=300` | V2 8-sezioni, query `?force=1` bypassa cache |
| `/morning-briefing/today-call-list` | GET | `@Roles('ADVISOR')` | none | Top 3 clients da chiamare oggi |
| `/morning-briefing/prewarm-call-lists` | POST | loopback + warmup header | none | 200 |
| `/morning-briefing/prewarm-v2` | POST | loopback + warmup header | none | tenant da `TENANT_ID` o `x-tenant-id` |
| `/news-hub/resolve/:hash` | GET | Public | none | redirect canonical URL |

Schema risposta `MorningBriefingV2`:
```typescript
interface MorningBriefingV2 {
  freshness: MorningBriefingFreshness;  // generatedAt, nextAutoRefreshAt
  greeting: string;
  weekLabel: string;
  sections: MorningBriefingV2Sections;  // 8 sezioni indipendenti
}
```

## 5 · REPLICATION PROTOCOL

### 5.1 Prerequisites
- Node.js >=18.x, PostgreSQL 17, Ollama installato (`127.0.0.1:11434`).
- Tenant config `tenants/<id>.json` con porta API (es. ws=4010).
- AI routing `config/ai-routing.json` con `briefing.daily-news`, `morning-briefing-what-changed`, `morning-briefing-weekly-anticipation`.
- Env: `DATABASE_URL`, `TENANT_ID`, `MORNING_BRIEFING_V2_CACHE_DIR` (opzionale), `BRIEFING_CLICKABLE_V2=true`, `MORNING_BRIEFING_V2_BOOT_WARMUP_DISABLED=0`.
- Modelli Ollama disponibili: `qwen3.6:27b` (primary local), `glm-4.7-flash` (fallback), `gemma4:31b` (alt).

### 5.2 Bootstrap steps (idempotenti)

```bash
# 1. Clone + install
git clone <github-url> valoswiss && cd valoswiss && npm install

# 2. Prisma
DATABASE_URL=$DATABASE_URL_<TENANT> npx prisma generate
DATABASE_URL=$DATABASE_URL_<TENANT> npx prisma migrate deploy

# 3. Pull modelli Ollama (primary local)
ollama pull qwen3.6:27b
ollama pull glm-4.7-flash

# 4. Build API
cd apps/api && npm run build

# 5. Start con TENANT_ID
TENANT_ID=w

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