docs: add implementation plan for standalone underlying chart endpoint

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
2026-07-21 10:25:36 +02:00
parent d15af22a2a
commit a03a437f1a
1 changed files with 577 additions and 0 deletions
--- a/docs/superpowers/plans/2026-07-21-underlying-only-chart.md
+++ b/docs/superpowers/plans/2026-07-21-underlying-only-chart.md
@@ -0,0 +1,577 @@
 # 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 |