SmartReports/docs/superpowers/specs/2026-07-21-underlying-only-chart-design.md

# Design: grafico standalone per singolo sottostante (senza certificato)

**Data**: 2026-07-21
**Stato**: approvato, in attesa di implementazione

## Obiettivo

Aggiungere un endpoint che generi un grafico semplificato mostrando **solo l'andamento storico prezzo** di un sottostante, identificato da `IDUnderlyings` — senza passare da un ISIN certificato e senza alcun riferimento a strike/barriere/trigger (che esistono solo nel contesto di un certificato).

Caso d'uso: preview rapida dell'andamento di un sottostante indipendente da qualunque certificato collegato.

## Architettura

Stessa pipeline di `/api/chart/{isin}` e `/api/chart/v2/{isin}`, ma senza contesto certificato:

```
GET /api/chart/underlying/{idUnderlyings}?width=&height=&format=
  → ChartController.GenerateChartUnderlying(idUnderlyings, width, height, format)
    → IUnderlyingChartDataService.GetChartDataAsync(idUnderlyings)
        → SP cedlab_Chart_UnderlyingOnly @IDUnderlyings
    → SkiaChartRendererV2 (nuovo metodo per serie singola)
    → PNG/JPEG bytes → risposta inline, oppure wrap in PDF (riuso WrapPngInPdf esistente)
```

## Componenti nuovi

### 1. Modello — `Models/UnderlyingChartModels.cs`

```csharp
public class UnderlyingChartData
{
    public int IDUnderlyings { get; set; }
    public string Nome { get; set; } = string.Empty; // ticker/nome per il titolo
    public List<UnderlyingChartPoint> Points { get; set; } = new();
}

public class UnderlyingChartPoint
{
    public DateTime Date { get; set; }
    public decimal Px { get; set; }
}
```

### 2. Servizio dati — `Services/Implementations/UnderlyingChartDataService.cs` + `IUnderlyingChartDataService`

- Chiama la SP `cedlab_Chart_UnderlyingOnly @IDUnderlyings`.
- Popola `UnderlyingChartData` con i punti prezzo grezzi (non normalizzati a %, a differenza di v2 che divide per Strike/Nominal — qui non c'è contesto certificato per farlo).
- Registrato in `Program.cs` come `AddScoped<IUnderlyingChartDataService, UnderlyingChartDataService>()`.

### 3. Stored Procedure — `docs/sql/cedlab_Chart_UnderlyingOnly.sql`

```sql
CREATE OR ALTER PROCEDURE [dbo].[cedlab_Chart_UnderlyingOnly]
    @IDUnderlyings INT
AS
BEGIN
    SET NOCOUNT ON;

    DECLARE @AdjustedPrices BIT;
    SELECT @AdjustedPrices = ISNULL(AdjustedPrices, 0)
    FROM dbo.Underlyings
    WHERE IDUnderlyings = @IDUnderlyings
      AND deleted = 0
      AND sospeso = 0;

    IF @AdjustedPrices IS NULL RETURN; -- non trovato / cancellato / sospeso

    ;WITH Ranked AS
    (
        SELECT
            p.Px_date,
            CASE WHEN @AdjustedPrices = 0 THEN p.Px_close ELSE p.Px_closeadj END AS Px,
            ROW_NUMBER() OVER (ORDER BY p.Px_date DESC) AS rn
        FROM dbo.Prices p
        WHERE p.UnderlyingsID = @IDUnderlyings
          AND (p.Px_low IS NOT NULL OR p.Px_high IS NOT NULL OR
               p.Px_open IS NOT NULL OR p.Px_close IS NOT NULL)
    )
    SELECT
        /* TODO: verificare colonna nome/ticker corretta in dbo.Underlyings prima di eseguire */
        u.Ticker AS Nome,
        r.Px_date,
        r.Px
    FROM Ranked r
    CROSS JOIN (SELECT TOP 1 * FROM dbo.Underlyings WHERE IDUnderlyings = @IDUnderlyings) u
    WHERE r.rn <= 350
    ORDER BY r.Px_date ASC;
END
GO
```

> **Nota**: colonna `u.Ticker` è placeholder — il nome effettivo della colonna in `dbo.Underlyings` (Ticker / TickerBB / Nome / Description...) va confermato prima di applicare lo script al DB, come già fatto per `cedlab_Chart_AllSeriesV2.sql`.

### 4. Renderer — nuovo metodo in `SkiaChartRendererV2`

- Firma indicativa: `RenderSingleSeriesToPng(UnderlyingChartData data, int width, int height, bool jpeg)`.
- Riusa griglia, assi X con intervalli mensili adattivi (12m/6m/3m/1m) e stile generale di V2.
- Una sola linea (colore nero o `AccentBlue`, spessore 2px).
- Titolo in alto = `data.Nome`.
- **Nessuna legenda** (una sola serie non la richiede).
- Nessuna barriera/strike/trigger disegnati (non esiste contesto certificato).

### 5. Controller — nuova route in `ChartController.cs` esistente

```
[HttpGet("underlying/{idUnderlyings}")]
public async Task<IActionResult> GenerateChartUnderlying(
    int idUnderlyings,
    [FromQuery] int width = 1100,
    [FromQuery] int height = 700,
    [FromQuery] string format = "png")
```

- `idUnderlyings <= 0` → `400 BadRequest`.
- Nessun punto prezzo trovato → `404 NotFound` con messaggio esplicativo.
- Formati supportati: `png` (default), `jpg`/`jpeg`, `pdf` (via `WrapPngInPdf` esistente, riuso invariato).
- **Non supportato**: `jpgEnc` e `?save=true` — dipendono dall'alias-certificato (`rpt_CertificatesChartsAlias`) che non esiste per un sottostante puro senza contesto certificato.
- Eccezioni → `500` loggato, stesso pattern try/catch di v1/v2.

## Error handling

| Caso | Risposta |
|------|----------|
| `idUnderlyings <= 0` | 400 |
| Sottostante non trovato / `deleted=1` / `sospeso=1` | 404 |
| Nessun prezzo disponibile | 404 |
| Eccezione runtime | 500 (loggato) |

## Cache

Nessuna cache introdotta per questo endpoint — coerente con `/api/chart/{isin}` e `/api/chart/v2/{isin}`, che non cachano l'immagine (solo il PDF del report principale usa cache). Fuori scope.

## Fuori scope

- Parametro `?save=true` (nessun path di salvataggio dedicato per sottostanti puri).
- Formato `jpgEnc` (nessun alias-certificato applicabile).
- Barriere/strike/trigger/scenari — richiedono contesto certificato, non disponibile con solo `IDUnderlyings`.
- Normalizzazione a percentuale (richiede uno strike/nominal di riferimento, assente qui).