# Dividend Section — Design Spec
**Data:** 2026-03-23
**Progetto:** SmartReports / CertReports.Syncfusion
**Stato:** Approvato

---

## Obiettivo

Aggiungere il supporto ai dati dividendi dei sottostanti nel report PDF, attivabile tramite il parametro query `?dividend=true`. Quando attivo, i dati dividendi (già presenti nella SP `rpt_Details_UL_ISIN`) vengono visualizzati in una pagina landscape dedicata con tabella unificata Sottostanti+Dividendi a header raggruppati.

---

## Parametro API

```
?dividend=true   → attiva la pagina dividendi
?dividend=false  → comportamento invariato (default)
```

Disponibile su tutti gli endpoint report esistenti (`/by-isin/{isin}`, `?p=`, `?alias=`, `/download`).

---

## Comportamento

### Con `dividend=false` (default)
Il report è identico a quello attuale. Nessuna modifica visibile.

### Con `dividend=true`
1. La tabella Sottostanti **non viene renderizzata** in Sezione 1 (né in `AnagraficaSectionRenderer` né in `ExpiredAnagraficaSectionRenderer`).
2. Dopo la Sezione 1 (Anagrafica) e prima della Sezione 2 (Eventi) viene inserita una **pagina landscape dedicata** con la tabella unificata Sottostanti+Dividendi.
3. Il resto del report (Eventi, Scenario, Grafico) rimane invariato.

---

## Struttura tabella landscape

Pagina A4 orizzontale (landscape), margini standard (`PdfTheme.PageMargin`).
Larghezza utile calcolata a runtime: `var size = page.GetClientSize(); float w = size.Width - 2 * PdfTheme.PageMargin; float h = size.Height - 2 * PdfTheme.PageMargin - PdfTheme.FooterHeight;` — NON usare costanti hardcoded. Font: `PdfTheme.TableFont` (7pt).

### Header a 2 livelli (colspan)

| Riga 1 | Nome | SOTTOSTANTE (×3) | BARRIERE (×5) | DIVIDENDI (×6) |
|--------|------|------------------|---------------|----------------|
| Riga 2 | — | Strike, Last, % Perf. | Barr.Cap., Buf.Cap., Trig.CPN, Buf.CPN, Trig.AC | Data Stacco, Data Pag., Importo, Rend., Imp.Fut., Rend.Fut. |

- Gruppo **SOTTOSTANTE** + **BARRIERE**: sfondo `#1565C0` (AccentBlue)
- Gruppo **DIVIDENDI**: sfondo `#0A3880` (blu scuro) per differenziazione visiva
- Separatore verticale blu (`#64B5F6`) tra colonna T.AC e colonna Data Stacco
- Colori performance: negativi `NegativeRed`, positivi `PositiveGreen`
- Righe alternate: `TableAltRow`

### Larghezze colonne indicative (totale ~770pt)

| Colonna | Width (pt) |
|---------|-----------|
| Nome | 90 |
| Strike | 50 |
| Last | 50 |
| % Perf. | 46 |
| Barr.Cap. | 50 |
| Buf.Cap. | 46 |
| Trig.CPN | 50 |
| Buf.CPN | 46 |
| Trig.AC | 46 |
| Data Stacco | 54 |
| Data Pag. | 54 |
| Importo | 40 |
| Rend. | 40 |
| Imp.Fut. | 40 |
| Rend.Fut. | 40 |
| **Totale** | **742** |

Le larghezze vengono scalate proporzionalmente: `float scale = w / total;` dove `w` proviene da `page.GetClientSize().Width - 2 * PdfTheme.PageMargin` (calcolato a runtime, non hardcoded).

---

## Mapping dati

I campi dividendi sono già nel modello `Sottostante` (da SP `rpt_Details_UL_ISIN`):

| Colonna PDF | Campo modello |
|-------------|--------------|
| Data Stacco | `DividendExDate` |
| Data Pag. | `DividendPayDate` |
| Importo | `DividendAmount` |
| Rend. | `DividendYield` |
| Imp.Fut. | `DividendFutAmount` |
| Rend.Fut. | `DividendFutYield` |

Nessuna modifica al data service o alle stored procedure.

---

## Componenti da modificare / creare

### 1. `CertificateReportData` (Models/CertificateModels.cs)
Aggiungere proprietà:
```csharp
public bool ShowDividend { get; set; } = false;
```

### 2. `ReportController` (Controllers/ReportController.cs)
Leggere il parametro `dividend` da query string e impostare `data.ShowDividend`.

### 3. `PdfCacheService`
La chiave cache deve includere il flag dividend per evitare collisioni:
- `{isin}` — no branding, no dividend
- `{isin}:branded` — branding, no dividend
- `{isin}:dividend` — no branding, dividend
- `{isin}:branded:dividend` — branding + dividend

### 4. `AnagraficaSectionRenderer`
Condizione nel metodo `Render()`: se `data.ShowDividend == true`, saltare il blocco "SEZIONE C: SOTTOSTANTI".

### 5. `ExpiredAnagraficaSectionRenderer`
Stessa condizione: se `data.ShowDividend == true`, saltare il blocco "SEZIONE C: SOTTOSTANTI".

### 6. `DividendSectionRenderer` (nuovo file)
- Classe: `DividendSectionRenderer`
- **Non** implementa `IPdfSectionRenderer` (non partecipa al ciclo ordinato)
- Registrazione: `AddScoped<DividendSectionRenderer>()` in `Program.cs`
- Metodo: `PdfDocument Render(CertificateReportData data)`
- Pagina landscape A4, titolo "Sottostanti e Dividendi", tabella con header a 2 livelli
- Dimensioni pagina: ricavare da `page.GetClientSize()` — `w = size.Width - 2 * PageMargin`, `h = size.Height - 2 * PageMargin - FooterHeight`
- Footer: `PdfTheme.DrawFooter(g, w, h, 1, data.ShowBranding)` — il numero pagina `1` è relativo alla pagina interna del documento parziale, coerente con lo stesso pattern usato da tutti gli altri renderer (la numerazione assoluta è una limitazione nota del sistema di merge)

### 7. `ReportOrchestrator`
- Aggiungere `DividendSectionRenderer dividendRenderer` come parametro del costruttore, accanto a `ExpiredAnagraficaSectionRenderer expiredRenderer` già presente — stesso pattern di iniezione diretta
- In entrambi i flussi (attivo ed expired): se `data.ShowDividend == true`, chiamare `dividendRenderer.Render(data)` e inserire il `PdfDocument` risultante nella lista documenti da mergiare **subito dopo** il documento della Sezione 1 (Anagrafica), prima di tutti gli altri

---

## Note implementative

- **Header colspan su PdfGrid**: Syncfusion `PdfGrid` non supporta nativamente colspan negli header. Implementare i due livelli di header come righe manuali disegnate con `DrawRectangle` + `DrawString` (seguire il pattern di `AnagraficaSectionRenderer.DrawEmittenteTable` per le altezze delle righe header: `rh = PdfTheme.RowHeight`). Riga 1 (gruppi): altezza `rh`; riga 2 (sotto-colonne): altezza `rh`. La `PdfGrid` dati viene disegnata a `y` iniziale = `y + rh * 2`. Le larghezze delle singole colonne nella riga 2 devono sommarsi esattamente alle larghezze dei gruppi in riga 1 per allineamento corretto.
- **Colori negativi/positivi**: applicare `ColorPerformanceCell` su % Perf., Buf.Cap., Buf.CPN, Rend., Rend.Fut. — stessa logica di `AnagraficaSectionRenderer`.
- **Valori assenti**: celle dividendo vuote mostrano `"—"`.
- Il parametro `dividend` è indipendente da `branding` — entrambi possono essere attivi contemporaneamente.

---

## Non in scope

- Modifiche alle stored procedure o al data service
- Nuove colonne nel modello `Sottostante`
- Modifiche al grafico o agli eventi
- Paginazione automatica della tabella dividendi (assumiamo max ~20 sottostanti per certificato)