# Grafico Standalone Sottostante (senza certificato) Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Aggiungere l'endpoint `GET /api/chart/underlying/{idUnderlyings}` che genera un grafico con solo la linea prezzo storico di un sottostante, senza alcun contesto certificato (no strike/barriere/legenda).

**Architecture:** Stessa pipeline di `/api/chart/v2/{isin}` ma senza certificato: nuova SP `cedlab_Chart_UnderlyingOnly`, nuovo servizio dati `UnderlyingChartDataService`, nuovo metodo statico `RenderSingleSeriesToPng` in `SkiaChartRendererV2` (riusa i suoi helper privati per griglia/assi), nuova route in `ChartController` esistente che riusa `WrapPngInPdf` già presente.

**Tech Stack:** ASP.NET Core 8, `Microsoft.Data.SqlClient`, SkiaSharp.

Spec di riferimento: `docs/superpowers/specs/2026-07-21-underlying-only-chart-design.md`.

---

## Task 1: Stored Procedure `cedlab_Chart_UnderlyingOnly`

**Files:**
- Create: `docs/sql/cedlab_Chart_UnderlyingOnly.sql`

- [ ] **Step 1: Scrivere lo script SQL**

```sql
USE [FirstSolutionDB]
GO

-- ============================================================
-- SP: cedlab_Chart_UnderlyingOnly
-- Restituisce lo storico prezzi di UN SOLO sottostante, senza
-- alcun contesto certificato (nessuno strike/barriera/trigger).
-- Usata da UnderlyingChartDataService per il grafico standalone
-- sottostante.
--
-- Output (Px_date ASC, TOP 350 più recenti):
--   Nome     VARCHAR  -- "{Name} ({Ticker_bbg})", uguale su ogni riga
--   Px_date  DATE
--   Px       DECIMAL  -- Px_close o Px_closeadj in base ad AdjustedPrices
-- ============================================================

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
        u.Name + ' (' + u.Ticker_bbg + ')' 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
```

- [ ] **Step 2: Commit**

```bash
git add docs/sql/cedlab_Chart_UnderlyingOnly.sql
git commit -m "docs: add cedlab_Chart_UnderlyingOnly SP script"
```

> **Nota per l'utente**: questo script va eseguito manualmente sul DB `FirstSolutionDB` prima di testare l'endpoint (Task 5). Nessun task successivo lo esegue automaticamente.

---

## Task 2: Modelli dati

**Files:**
- Create: `CertReports.Syncfusion/Models/UnderlyingChartModels.cs`

- [ ] **Step 1: Scrivere il file dei modelli**

```csharp
namespace CertReports.Syncfusion.Models;

/// <summary>
/// Singolo punto prezzo per il grafico standalone sottostante
/// (da SP cedlab_Chart_UnderlyingOnly).
/// </summary>
public class UnderlyingChartPoint
{
    public DateTime Date { get; set; }
    public decimal Px { get; set; }
}

/// <summary>
/// Dati completi per il grafico standalone di un sottostante,
/// senza alcun contesto certificato.
/// </summary>
public class UnderlyingChartData
{
    public int IDUnderlyings { get; set; }

    /// <summary>Titolo del grafico: "{Name} ({Ticker_bbg})".</summary>
    public string Nome { get; set; } = string.Empty;

    public List<UnderlyingChartPoint> Points { get; set; } = new();
}
```

- [ ] **Step 2: Build per verificare che compili**

Run: `dotnet build CertReports.Syncfusion`
Expected: `Build succeeded. 0 Error(s)`

- [ ] **Step 3: Commit**

```bash
git add CertReports.Syncfusion/Models/UnderlyingChartModels.cs
git commit -m "feat: add UnderlyingChartData model"
```

---

## Task 3: Servizio dati `UnderlyingChartDataService`

**Files:**
- Create: `CertReports.Syncfusion/Services/Implementations/UnderlyingChartDataService.cs`
- Modify: `CertReports.Syncfusion/Program.cs`

- [ ] **Step 1: Scrivere il servizio**

```csharp
using CertReports.Syncfusion.Models;
using Microsoft.Data.SqlClient;
using System.Data;

namespace CertReports.Syncfusion.Services.Implementations;

/// <summary>
/// Recupera i dati per il grafico standalone di un singolo sottostante
/// (nessun contesto certificato). SP utilizzata: cedlab_Chart_UnderlyingOnly.
/// </summary>
public interface IUnderlyingChartDataService
{
    Task<UnderlyingChartData?> GetChartDataAsync(int idUnderlyings);
}

public class UnderlyingChartDataService : IUnderlyingChartDataService
{
    private readonly string _connectionString;
    private readonly ILogger<UnderlyingChartDataService> _logger;

    public UnderlyingChartDataService(IConfiguration config, ILogger<UnderlyingChartDataService> logger)
    {
        _connectionString = config.GetConnectionString("CertDb")
            ?? throw new InvalidOperationException("ConnectionString 'CertDb' non configurata.");
        _logger = logger;
    }

    public async Task<UnderlyingChartData?> GetChartDataAsync(int idUnderlyings)
    {
        await using var conn = new SqlConnection(_connectionString);
        await conn.OpenAsync();

        await using var cmd = new SqlCommand("cedlab_Chart_UnderlyingOnly", conn)
            { CommandType = CommandType.StoredProcedure };
        cmd.Parameters.AddWithValue("@IDUnderlyings", idUnderlyings);

        var result = new UnderlyingChartData { IDUnderlyings = idUnderlyings };

        await using var r = await cmd.ExecuteReaderAsync();
        while (await r.ReadAsync())
        {
            if (result.Points.Count == 0)
                result.Nome = ToStr(r, "Nome");

            result.Points.Add(new UnderlyingChartPoint
            {
                Date = r.GetDateTime(r.GetOrdinal("Px_date")),
                Px   = Convert.ToDecimal(r.GetValue(r.GetOrdinal("Px"))),
            });
        }

        if (result.Points.Count == 0)
        {
            _logger.LogWarning(
                "Nessun prezzo trovato per il sottostante {IDUnderlyings} (non trovato, cancellato, sospeso, o senza storico prezzi)",
                idUnderlyings);
            return null;
        }

        _logger.LogInformation(
            "Dati grafico sottostante caricati per {IDUnderlyings}: {Points} punti",
            idUnderlyings, result.Points.Count);

        return result;
    }

    private static string ToStr(SqlDataReader r, string column)
    {
        int ord = r.GetOrdinal(column);
        return r.IsDBNull(ord) ? string.Empty : r.GetString(ord);
    }
}
```

- [ ] **Step 2: Registrare il servizio in Program.cs**

In `CertReports.Syncfusion/Program.cs`, subito dopo la riga 37 (`builder.Services.AddScoped<IChartDataServiceV2, ChartDataServiceV2>();`):

```csharp
builder.Services.AddScoped<IUnderlyingChartDataService, UnderlyingChartDataService>();
```

- [ ] **Step 3: Build per verificare che compili**

Run: `dotnet build CertReports.Syncfusion`
Expected: `Build succeeded. 0 Error(s)`

- [ ] **Step 4: Commit**

```bash
git add CertReports.Syncfusion/Services/Implementations/UnderlyingChartDataService.cs CertReports.Syncfusion/Program.cs
git commit -m "feat: add UnderlyingChartDataService and DI registration"
```

---

## Task 4: Renderer — `RenderSingleSeriesToPng` in `SkiaChartRendererV2`

**Files:**
- Modify: `CertReports.Syncfusion/Services/Implementations/SkiaChartRendererV2.cs`

Il file espone già come `private static` tutti gli helper necessari (`CreateFont`, `DrawGrid`, `DateToX`, `ValueToY`, `XAxisIntervalMonths`, `XAxisStart`). Il nuovo metodo pubblico va aggiunto nella stessa classe per poterli riusare senza cambiarne la visibilità.

- [ ] **Step 1: Aggiungere il metodo `RenderSingleSeriesToPng`**

Inserire subito dopo la chiusura del metodo `RenderToPng` esistente (dopo la riga `return imgData.ToArray();` e la relativa `}` di chiusura, prima del blocco `// Titolo`):

```csharp
    // ═══════════════════════════════════════════════════════════════════
    // Entry point — grafico standalone singolo sottostante (no certificato)
    // ═══════════════════════════════════════════════════════════════════

    public static byte[] RenderSingleSeriesToPng(UnderlyingChartData data, int width = 1100, int height = 700, bool jpeg = false)
    {
        using var surface = SKSurface.Create(new SKImageInfo(width, height));
        var canvas = surface.Canvas;
        canvas.Clear(SKColors.White);

        float titleBottom = DrawUnderlyingTitle(canvas, width, data.Nome);

        float marginLeft   = 70;
        float marginRight  = 40;
        float marginTop    = titleBottom + 10;
        float marginBottom = 45;

        var plotArea = new SKRect(marginLeft, marginTop, width - marginRight, height - marginBottom);

        var points = data.Points.OrderBy(p => p.Date).ToList();
        if (points.Count == 0)
            return Array.Empty<byte>();

        DateTime minDate = points[0].Date;
        DateTime maxDate = points[^1].Date;
        double minY = (double)points.Min(p => p.Px);
        double maxY = (double)points.Max(p => p.Px);
        double range = maxY - minY;
        if (range == 0) range = Math.Max(minY * 0.1, 1);
        double margin = range * 0.1;
        minY -= margin;
        maxY += margin;

        DrawGrid(canvas, plotArea, minDate, maxDate, minY, maxY);
        DrawUnderlyingAxisLabels(canvas, plotArea, minDate, maxDate, minY, maxY);
        DrawUnderlyingSeries(canvas, plotArea, points, minDate, maxDate, minY, maxY);

        using var borderPaint = new SKPaint
        {
            Color = SKColors.Gray, StrokeWidth = 1,
            Style = SKPaintStyle.Stroke, IsAntialias = true,
        };
        canvas.DrawRect(plotArea, borderPaint);

        using var image = surface.Snapshot();
        using var imgData = jpeg
            ? image.Encode(SKEncodedImageFormat.Jpeg, 90)
            : image.Encode(SKEncodedImageFormat.Png, 95);
        return imgData.ToArray();
    }

    private static float DrawUnderlyingTitle(SKCanvas canvas, int width, string nome)
    {
        float y = 15f;
        var boldFont = CreateFont(13f, bold: true);
        using var titlePaint = new SKPaint { Color = TitleColor, IsAntialias = true };
        canvas.DrawText(nome, width / 2f, y + 13, SKTextAlign.Center, boldFont, titlePaint);
        return y + 22 + 5;
    }

    private static void DrawUnderlyingAxisLabels(SKCanvas canvas, SKRect area,
        DateTime minDate, DateTime maxDate, double minY, double maxY)
    {
        var font = CreateFont(11);
        using var paint = new SKPaint { Color = SKColors.DimGray, IsAntialias = true };

        int ySteps = 8;
        for (int i = 0; i <= ySteps; i++)
        {
            double val = maxY - ((maxY - minY) / ySteps) * i;
            float y = area.Top + (area.Height / ySteps) * i;
            canvas.DrawText($"{val:F2}", area.Left - 55, y + 4, SKTextAlign.Left, font, paint);
        }

        double totalDays = (maxDate - minDate).TotalDays;
        int intervalMonths = XAxisIntervalMonths(minDate, maxDate);
        string fmt = totalDays > 365 ? "MMM yy" : "dd/MM/yy";

        if (intervalMonths > 0)
        {
            var d = XAxisStart(minDate, intervalMonths);
            while (d <= maxDate)
            {
                float x = DateToX(d, area, minDate, maxDate);
                if (x >= area.Left && x <= area.Right)
                    canvas.DrawText(d.ToString(fmt), x, area.Bottom + 20, SKTextAlign.Center, font, paint);
                d = d.AddMonths(intervalMonths);
            }
        }
        else
        {
            canvas.DrawText(minDate.ToString("dd/MM/yy"), area.Left,  area.Bottom + 20, SKTextAlign.Left,  font, paint);
            canvas.DrawText(maxDate.ToString("dd/MM/yy"), area.Right, area.Bottom + 20, SKTextAlign.Right, font, paint);
        }
    }

    private static void DrawUnderlyingSeries(SKCanvas canvas, SKRect area,
        List<UnderlyingChartPoint> points,
        DateTime minDate, DateTime maxDate, double minY, double maxY)
    {
        using var paint = new SKPaint
        {
            Color = CertColor, StrokeWidth = 2f,
            Style = SKPaintStyle.Stroke, IsAntialias = true,
            StrokeCap = SKStrokeCap.Round, StrokeJoin = SKStrokeJoin.Round,
        };

        using var path = new SKPath();
        bool first = true;
        foreach (var pt in points)
        {
            float x = DateToX(pt.Date, area, minDate, maxDate);
            float y = ValueToY((double)pt.Px, area, minY, maxY);
            y = Math.Max(area.Top, Math.Min(area.Bottom, y));
            if (first) { path.MoveTo(x, y); first = false; }
            else path.LineTo(x, y);
        }

        canvas.Save();
        canvas.ClipRect(area);
        canvas.DrawPath(path, paint);
        canvas.Restore();
    }
```

Aggiungere anche `using CertReports.Syncfusion.Models;` in cima al file se non già presente (è già presente, riga 1 — nessuna modifica necessaria).

- [ ] **Step 2: Build per verificare che compili**

Run: `dotnet build CertReports.Syncfusion`
Expected: `Build succeeded. 0 Error(s)`

- [ ] **Step 3: Commit**

```bash
git add CertReports.Syncfusion/Services/Implementations/SkiaChartRendererV2.cs
git commit -m "feat: add RenderSingleSeriesToPng for standalone underlying chart"
```

---

## Task 5: Endpoint `GET /api/chart/underlying/{idUnderlyings}`

**Files:**
- Modify: `CertReports.Syncfusion/Controllers/ChartController.cs`

- [ ] **Step 1: Aggiungere il campo del nuovo servizio e iniettarlo nel costruttore**

Modificare l'inizio della classe (righe 20-37):

```csharp
public class ChartController : ControllerBase
{
    private readonly IChartDataService _chartDataService;
    private readonly IChartDataServiceV2 _chartDataServiceV2;
    private readonly IUnderlyingChartDataService _underlyingChartDataService;
    private readonly ILogger<ChartController> _logger;
    private readonly IConfiguration _configuration;

    public ChartController(
        IChartDataService chartDataService,
        IChartDataServiceV2 chartDataServiceV2,
        IUnderlyingChartDataService underlyingChartDataService,
        ILogger<ChartController> logger,
        IConfiguration configuration)
    {
        _chartDataService = chartDataService;
        _chartDataServiceV2 = chartDataServiceV2;
        _underlyingChartDataService = underlyingChartDataService;
        _logger = logger;
        _configuration = configuration;
    }
```

- [ ] **Step 2: Aggiungere la nuova route**

Inserire subito dopo la chiusura del metodo `GenerateChartV2` (dopo la riga `}` che chiude quel metodo, prima del metodo `SaveChartToDiskAsync`):

```csharp
    /// <summary>
    /// Endpoint standalone: grafico con solo la linea prezzo storico di UN sottostante,
    /// identificato da IDUnderlyings — nessun contesto certificato (no strike/barriere/legenda).
    /// Richiede SP cedlab_Chart_UnderlyingOnly nel DB.
    /// Formati supportati: png (default), jpg/jpeg, pdf. Non supporta jpgEnc né ?save=true
    /// (nessun alias-certificato applicabile a un sottostante puro).
    /// </summary>
    [HttpGet("underlying/{idUnderlyings:int}")]
    public async Task<IActionResult> GenerateChartUnderlying(
        int idUnderlyings,
        [FromQuery] int width = 1100,
        [FromQuery] int height = 700,
        [FromQuery] string format = "png")
    {
        if (idUnderlyings <= 0)
            return BadRequest("IDUnderlyings non valido.");

        width  = Math.Clamp(width,  400, 2000);
        height = Math.Clamp(height, 300, 1500);

        try
        {
            var chartData = await _underlyingChartDataService.GetChartDataAsync(idUnderlyings);

            if (chartData == null || chartData.Points.Count == 0)
            {
                return NotFound(new
                {
                    status  = "KO",
                    message = $"Nessun dato per il grafico del sottostante {idUnderlyings}.",
                });
            }

            bool isJpeg = format.Equals("jpg", StringComparison.OrdinalIgnoreCase)
                       || format.Equals("jpeg", StringComparison.OrdinalIgnoreCase);

            byte[] imgBytes = SkiaChartRendererV2.RenderSingleSeriesToPng(chartData, width, height, jpeg: isJpeg);

            if (format.Equals("pdf", StringComparison.OrdinalIgnoreCase))
            {
                byte[] pdfBytes = WrapPngInPdf(imgBytes);
                Response.Headers.Append("Content-Disposition", $"inline; filename=chart_underlying_{idUnderlyings}.pdf");
                return File(pdfBytes, "application/pdf");
            }

            if (isJpeg)
            {
                Response.Headers.Append("Content-Disposition", $"inline; filename=chart_underlying_{idUnderlyings}.jpg");
                return File(imgBytes, "image/jpeg");
            }

            Response.Headers.Append("Content-Disposition", $"inline; filename=chart_underlying_{idUnderlyings}.png");
            return File(imgBytes, "image/png");
        }
        catch (Exception ex)
        {
            _logger.LogError(ex, "Errore generazione chart sottostante per IDUnderlyings {IDUnderlyings}", idUnderlyings);
            return StatusCode(500, new { status = "KO", message = "Errore nella generazione del grafico sottostante." });
        }
    }

```

- [ ] **Step 3: Build per verificare che compili**

Run: `dotnet build CertReports.Syncfusion`
Expected: `Build succeeded. 0 Error(s)`

- [ ] **Step 4: Commit**

```bash
git add CertReports.Syncfusion/Controllers/ChartController.cs
git commit -m "feat: add GET /api/chart/underlying/{idUnderlyings} endpoint"
```

---

## Task 6: Verifica manuale end-to-end

**Prerequisito**: lo script `docs/sql/cedlab_Chart_UnderlyingOnly.sql` (Task 1) deve essere già stato eseguito manualmente sul DB `FirstSolutionDB`. Serve inoltre un `IDUnderlyings` reale con storico prezzi in `dbo.Prices` — recuperabile con una query come `SELECT TOP 5 IDUnderlyings, Name, Ticker_bbg FROM dbo.Underlyings WHERE deleted = 0 AND sospeso = 0`.

Non esistono test automatici nel progetto (vedi CLAUDE.md) — questa verifica è manuale, come per gli altri endpoint chart.

- [ ] **Step 1: Avviare il progetto in locale**

Run: `dotnet run --project CertReports.Syncfusion`
Expected: log di avvio Kestrel con l'URL locale (es. `https://localhost:XXXX`), nessuna eccezione.

- [ ] **Step 2: Testare il caso positivo (PNG)**

Aprire nel browser (sostituire `{porta}` e `{idUnderlyings}` con valori reali):
`https://localhost:{porta}/api/chart/underlying/{idUnderlyings}`

Expected: immagine PNG con una sola linea nera, titolo `{Name} ({Ticker_bbg})` in alto, assi con date e valori prezzo (non percentuale), nessuna legenda.

- [ ] **Step 3: Testare formato PDF**

`https://localhost:{porta}/api/chart/underlying/{idUnderlyings}?format=pdf`

Expected: PDF landscape con l'immagine centrata, apribile senza errori.

- [ ] **Step 4: Testare caso 404 (sottostante inesistente)**

`https://localhost:{porta}/api/chart/underlying/999999999`

Expected: risposta HTTP 404 con body JSON `{"status":"KO","message":"Nessun dato per il grafico del sottostante 999999999."}`.

- [ ] **Step 5: Testare caso 400 (id non valido)**

`https://localhost:{porta}/api/chart/underlying/0`

Expected: risposta HTTP 400.

- [ ] **Step 6: Arrestare il server**

Interrompere il processo `dotnet run` (Ctrl+C nel terminale in cui è in esecuzione).

- [ ] **Step 7: Aggiornare CLAUDE.md**

In `CertReports.Syncfusion/CLAUDE.md` (root repo), sezione `## API Endpoints`, aggiungere la riga:

```
- `GET /api/chart/underlying/{idUnderlyings}[?format=png|jpg|jpeg|pdf&width=&height=]` — grafico standalone di un solo sottostante (nessun contesto certificato, no strike/barriere/legenda)
```

- [ ] **Step 8: Commit**

```bash
git add CertReports.Syncfusion/CLAUDE.md
git commit -m "docs: document GET /api/chart/underlying/{idUnderlyings} endpoint"
```

---

## Riepilogo copertura spec

| Requisito spec | Task |
|---|---|
| SP `cedlab_Chart_UnderlyingOnly` con nome `{Name} ({Ticker_bbg})` | Task 1 |
| Modello `UnderlyingChartData` | Task 2 |
| Servizio dati + DI | Task 3 |
| Renderer solo linea prezzo, titolo, no legenda/barriere | Task 4 |
| Endpoint `GET /api/chart/underlying/{idUnderlyings}`, formati png/jpg/jpeg/pdf, no jpgEnc/save | Task 5 |
| Error handling 400/404/500 | Task 5 |
| Verifica end-to-end e doc | Task 6 |