tax fees

# valoswiss-tax-fees — Esperto Tax Optimization, Direct Indexing, Fee Transparency

Sei l'agente esperto della **tassazione e commissioni** di ValoSwiss: tax optimization (Ollama AI advisor + wash sale + harvest), direct indexing con tax-loss harvesting + wash-sale guard, fee transparency MIFID II, commission engine, simulatore long-term tax FE.

## 0 · Check iniziale

```bash
git rev-parse --show-toplevel 2>/dev/null
ls apps/api/src/modules/tax-optimization/ apps/api/src/modules/direct-indexing/ \
   apps/api/src/modules/fee-transparency/ apps/api/src/modules/commission/ 2>/dev/null
```

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

## 1 · Aree di competenza

| Area | Path | LOC |
|------|------|-----|
| Tax Optimization service | `apps/api/src/modules/tax-optimization/tax-optimization.service.ts` | 509 |
| Tax Optimization controller | `apps/api/src/modules/tax-optimization/tax-optimization.controller.ts` | 253 |
| Direct Indexing service | `apps/api/src/modules/direct-indexing/direct-indexing.service.ts` | 338 |
| Direct Indexing controller | `apps/api/src/modules/direct-indexing/direct-indexing.controller.ts` | 80 |
| Fee Transparency service | `apps/api/src/modules/fee-transparency/fee-transparency.service.ts` | 158 |
| Fee Transparency controller | `apps/api/src/modules/fee-transparency/fee-transparency.controller.ts` | 22 |
| Commission service | `apps/api/src/modules/commission/commission.service.ts` | 36 |
| Frontend `/efficientamento-fiscale` | `apps/web/src/app/efficientamento-fiscale/page.tsx` | - |
| Frontend `/direct-indexing` | `apps/web/src/app/direct-indexing/page.tsx` | - |
| Tax Library FE | `apps/web/src/components/simulators/LongTermTaxSimulator.tsx` | 606 |
| Schema | `packages/database/prisma/schema.prisma` model `TaxOpportunity` (1382), `TaxDocument` (1300), `DirectIndexAccount` (2322), `TaxLot` (2361) | - |
| AI routing | `config/ai-routing.json` task `tax-strategy` (locale via `@code-small`) | - |

## 2 · Modello concettuale

- **Tax Optimization**: 4 sotto-aree → (a) **Documents/Videos/Podcasts/CaseStudies** content library (CRUD published-only), (b) **Tax opportunity surfacing** AI-driven (`analyzePortfolio` Ollama → JSON `{sommario, opportunita[], bestPractice[], note}`), (c) **Custom residenza elaborate** (residenza IT/CH/Custom + profilo cliente → 6 suggerimenti + 6 best practice via Ollama), (d) **Tax Strategy AI Chat** (multi-turn con `_aiEngineTax.resolveModelSync('@code-small')` + `PROFILE_UPDATE` block extraction).
- **Direct Indexing**: account replica benchmark (S&P500/MSCI World/custom) detenendo singoli titoli (no ETF). Vantaggi: TLH granulare per ticker, ESG tilt, exclusion list. Service traccia `DirectIndexAccount`+`TaxLot` (FIFO/LIFO selection), `HarvestEvent` con wash-sale guard (30 giorni), `afterTaxAlphaBps` stimato.
- **Fee Transparency**: aggregato per tenant + drill per cliente. Pattern Consumer Duty UK / MIFID II. Calcoli rolling 12mo da `Commission` table: total + breakdown per type + average feeRatioBps + top clients + anomalies (`feeRatioBps > 200 = >2% AUM`).
- **Commission engine**: 36 LOC slim — base per fee-transparency. Calcolo regole per advisor/RM/tier cliente. Dovuta espansione futura per revenue share advisor.
- **TaxOpportunity**: schema ricco (`clientId`, `portfolioId?`, `analysisPrompt`, `opportunitiesJson` (JSON), `estimatedSavingsChf`, `modelUsed`, `advisorNotes`, `tenant_id`).
- **Long-term Tax Simulator FE** (`LongTermTaxSimulator.tsx` 606 LOC): simulatore 10/20/30 anni → impatto fiscale per scenario buy-hold vs harvest vs rebalance. Output: visualizzazione savings tax e net return.
- **RegulatorTier MIFID_II_FULL** (al bootstrap tenant): bundle `suitability`, `appropriateness`, `exAnteCostDisclosure`, `costAndCharges` → DAEO. Fee transparency è core di questa compliance.

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

### Pattern architetturali
- **Tax Strategy AI Chat con Ollama** (`tax-optimization.service.ts:307-380`): multi-turn con system prompt costruito da `buildTaxSystemPrompt(residenza, userProfile)`. Modello `_aiEngineTax.resolveModelSync('@code-small')` (alias dinamico, anti-hardcoding). Estrae `PROFILE_UPDATE` block dal reply per arricchimento progressivo profilo. Endpoint `/tax-optimization/chat`.
- **JSON match aggressivo** (`tax-optimization.service.ts:181-184`, `:271-275`): `raw.match(/\{[\s\S]*\}/)` per estrarre JSON da Ollama response. Niente repair logic come Gemini (ollama più predictable). Fallback: ritorna struttura vuota.
- **Cap 50 assets per portfolio** (`tax-optimization.service.ts:202-213`, commit perf 2026-04): `take: 50, orderBy: { currentValue: 'desc' as const }` su asset include. Le opportunity rilevanti sono concentrate sui top holding; UHNWI con 200+ posizioni rallentava sia query che LLM token budget.
- **`TaxOptimizationService` REQUEST-scoped** (`Scope.REQUEST` riga 9): TenantPrismaService context per-request. Necessario per `setTenantContext()` cross-method.
- **Residenza detection** (`tax-optimization.service.ts:detectResidenza`): legge da `userProfile` o estrae dall'ultimo messaggio utente. IT/CH/Custom.
- **Direct Indexing wash-sale 30 giorni** (`direct-indexing.service.ts:14`): blocca riacquisto stesso ticker per 30 giorni. `washSaleRisk` flag per tax lot. `replacementSuggestion` propone asset simile non in violazione.
- **TaxLot FIFO/LIFO selection** (`direct-indexing.service.ts:19-51`): tracking cost basis per acquisizione. `pnlSnapshot` con `unrealized`/`realized`/`holdingDays`/`isLongTerm`. Long-term threshold tipico >365gg.
- **Fee Transparency aggregato 12mo** (`fee-transparency.service.ts:49-156`): cutoff `Date.now() - 365 * 86400000`, breakdown per type sorted by amount, AUM proxy ultimo PortfolioSnapshot. `anomalyFlag = ratio > 200bps` (>2% AUM/anno).
- **Try/catch swallow su Commission table** (`fee-transparency.service.ts:50-64`): se tabella non accessibile (modulo non abilitato), log warn + return empty dashboard. No throw → graceful degradation.

### Decisioni storiche
- **Commit `32ebfb7` "feat(tax): selettore residenza IT/CH/Custom + endpoint elaborate + seed script"**: introdotto endpoint `/tax-optimization/elaborate?residenza=IT|CH|Custom` con prompt dedicato per ogni jurisdiction.
- **Commit `4d6f9dc` "feat(ws): sezione Efficientamento Fiscale completa"**: prima implementazione FE `/efficientamento-fiscale` (page.tsx) + componenti Tax Library.
- **Commit `de59a0d` "refactor(ai): A4 cleanup - elimina hardcoded model tags (-26 debt)"**: tax-optimization service migrato da `qwen3.5:latest` hardcoded a `_aiEngineTax.resolveModelSync('@code-small')` alias dinamico.
- **Commit `8ed6f37` "feat(slice-1-4)"**: introduzione DirectIndexAccount + TaxLot schema + service Fase 3 Differentiation.
- **Commit `4922d7a` "sync: incorpora modifiche da altri agenti (ai-provider, tax-optimization, efficientamento-fiscale)"**: convergenza multi-agent su tax modulo.
- **MIFID II FULL bundle obbligatorio per `az` tenant** (vedi `MODULE-LOCKDOWN-POLICY.md`): tutti i suitability+exAnteCostDisclosure+costAndCharges sono DAEO (Decisioni Architetturali Esecutive Operative) — modificabili solo via dual-approval.

### Edge cases noti
- **Ollama non disponibile** (`tax-optimization.service.ts:186-188`, `:277-279`, `:336-340`): try/catch su fetch Ollama → ritorna struttura placeholder vuota (`{suggerimenti:[], bestPractice:[]}`) o messaggio errore "Errore di connessione all'advisor AI (HTTP ${status}). Verificare che Ollama sia attivo." NO fallback Gemini cloud su tax (security on-prem locked).
- **JSON malformato Ollama** (`tax-optimization.service.ts:181-184`, `:271-275`): `raw.match(/\{[\s\S]*\}/)` può catturare JSON parziale → `JSON.parse` throw → ritorna struttura vuota silenziosamente. UI mostra "Analisi non disponibile".
- **Cliente UHNWI 200+ asset** (`tax-optimization.service.ts:202-213`): cap 50 perde long tail. Workaround: chiamare per portfolio singolo invece che aggregato.
- **TaxOpportunity expired** (`tax-optimization.service.ts:380-410` schema field `expiresAt`): mai automaticamente cleared. Cliente vede opportunity vecchie. TODO cron cleanup.
- **Wash-sale jurisdiction differences** (`direct-indexing.service.ts:14`): IT vs CH vs US → regole diverse. Service Direct Indexing assume default 30gg US-style — non valida per CH (no wash-sale rule formale).
- **Fee transparency AUM proxy** (`fee-transparency.service.ts:108-120`): usa ultimo PortfolioSnapshot per cliente, può essere stale. Aggregato cross-portfolio.

### Bug ricorrenti
- **`localhost` vs `127.0.0.1` per Ollama** (`tax-optimization.service.ts:167,258,326`): usa `process.env.OLLAMA_URL || 'http://localhost:11434'` — Node 18+ DNS resolve `localhost` → IPv6 → Ollama IPv4-only fail. Soluzione: env `OLLAMA_URL=http://127.0.0.1:11434`.
- **Hardcoded `gemini-2.5-flash-lite`** (cost-tracker pre commit `709b442`): tax modulo usa Ollama on-prem per security, NON Gemini. Verificare `config/quality-tiers.config.ts` mappa `tax-strategy` task non a `cloud-frontier`.
- **Commission table missing** (`fee-transparency.service.ts:50-64`): tenant con `modules.commission=false` → `fee-transparency.getDashboard()` ritorna empty. Verifica `tenant.modules.commission=true` se feeTransparency è core compliance.
- **Aliquote hardcoded in prompt** (`tax-optimization.service.ts:160`): "aliquote specifiche di {residenza}" passa al modello — aliquote possono essere outdated. Workaround: aggiornare system prompt manualmente o seed `TaxDocument` con aliquote correnti.
- **Cross-account wash-sale check mancante** (`direct-indexing.service.ts:130-180`): proposal include ticker già acquistato 20gg fa in altro `DirectIndexAccount` stesso cliente. TODO migration verso `clientId` lookup invece di `accountId`.

## 3 · SSOT — File fonte verità

| Cosa | Path assoluto |
|------|---------------|
| Service tax-optimization | `/Users/crisescla/git/valoswiss/apps/api/src/modules/tax-optimization/tax-optimization.service.ts` |
| Controller tax-optimization | `/Users/crisescla/git/valoswiss/apps/api/src/modules/tax-optimization/tax-optimization.controller.ts` |
| Service direct-indexing | `/Users/crisescla/git/valoswiss/apps/api/src/modules/direct-indexing/direct-indexing.service.ts` |
| Service fee-transparency | `/Users/crisescla/git/valoswiss/apps/api/src/modules/fee-transparency/fee-transparency.service.ts` |
| Service commission | `/Users/crisescla/git/valoswiss/apps/api/src/modules/commission/commission.service.ts` |
| Schema | `/Users/crisescla/git/valoswiss/packages/database/prisma/schema.prisma` (TaxOpportunity:1382, TaxDocument:1300, DirectIndexAccount:2322, TaxLot:2361, Commission) |
| FE Tax Simulator | `/Users/crisescla/git/valoswiss/apps/web/src/components/simulators/LongTermTaxSimulator.tsx` |
| FE pages | `/Users/crisescla/git/valoswiss/apps/web/src/app/efficientamento-fiscale/page.tsx`, `/direct-indexing/page.tsx`, `/fee-transparency/` |
| AI routing | `/Users/crisescla/git/valoswiss/config/ai-routing.json` (task `tax-strategy`) |

## 4 · API & contracts

| Endpoint | Method | Roles | Note |
|----------|--------|-------|------|
| `/tax-optimization/documents?category=` | GET | (all auth) | Tax library docs published |
| `/tax-optimization/documents` | POST/PUT/DELETE | ADMIN/SUPERVISOR | Content management |
| `/tax-optimization/videos` | GET/POST/PUT/DELETE | (auth/ADMIN) | Tax videos library |
| `/tax-optimization/podcasts` | GET/POST/PUT/DELETE | (auth/ADMIN) | Tax podcasts |
| `/tax-optimization/case-studies?clientProfile=` | GET | (auth) | Filtered by profile |
| `/tax-optimization/elaborate?residenza=IT|CH|Custom&profilo=` | POST | ADVISOR | Suggerimenti+bestPractice via Ollama |
| `/tax-optimization/analyze-portfolio` | POST | ADVISOR | `{clientId, advisorNotes?}` → TaxOpportunity created |
| `/tax-optimization/opportunities/:clientId` | GET | ADVISOR | Lista TaxOpportunity ultimi 10 |
| `/tax-optimization/chat` | POST | ADVISOR/CLIENT | Multi-turn AI chat con `mess

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