docs: add README with project overview and architecture

2026-03-20 17:48:03 +01:00
parent 783339cd0c
commit a1ec6157f3
1 changed files with 116 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,116 @@
+# SmartReports
+
+Generatore di report PDF per certificati finanziari strutturati, sviluppato in ASP.NET Core 8 con libreria Syncfusion PDF (Community License) e SkiaSharp per i grafici.
+
+## Caratteristiche principali
+
+- Generazione PDF multi-sezione da dati SQL Server
+- Grafico performance sottostanti (SkiaSharp → PNG in memoria)
+- Footer con branding opzionale e hyperlink cliccabile
+- Cache in memoria per ISIN già generati
+- Endpoint per PDF inline, download e grafico standalone
+- Supporto Docker
+
+## Stack tecnologico
+
+| Componente | Tecnologia |
+|-----------|-----------|
+| Framework | ASP.NET Core 8 |
+| PDF | Syncfusion PDF v33 (Community License) |
+| Grafici | SkiaSharp |
+| Database | SQL Server (Microsoft.Data.SqlClient v5) |
+| Runtime | .NET 8 |
+
+## Struttura del report
+
+| Sezione | Contenuto |
+|---------|-----------|
+| **1 — Anagrafica** | Header con Tipologia / Data / Bid / Ask, caratteristiche prodotto, analisi KV, tabella sottostanti |
+| **2 — Eventi** | Lista eventi cedole e autocall (tabella landscape multi-pagina) |
+| **3 — Scenario** | Scenari di rendimento (opzionale) |
+| **4 — Grafico** | Performance storica dei sottostanti |
+
+## API Endpoints
+
+```
+GET /api/report/by-isin/{ISIN}          → PDF inline
+GET /api/report?p={isin_cifrato}        → PDF inline (ISIN cifrato)
+GET /api/report?alias={id}             → PDF inline (alias)
+GET /api/report/download?p={...}       → PDF come allegato
+
+GET /api/chart/{isin}                  → Grafico standalone (PNG/PDF)
+GET /health                            → Health check DB + chart service
+```
+
+Tutti gli endpoint report accettano `?branding=true` per aggiungere il footer "Powered by Smart Roots".
+
+## Avvio locale
+
+```bash
+# Restore e build
+dotnet restore
+dotnet build
+
+# Run
+dotnet run --project CertReports.Syncfusion
+# → https://localhost:{porta}/api/report/by-isin/{ISIN}
+```
+
+## Avvio con Docker
+
+```bash
+docker-compose up --build
+# → http://localhost:5080/api/report/by-isin/{ISIN}
+```
+
+## Configurazione
+
+| File | Scopo |
+|------|-------|
+| `appsettings.json` | Connection string (`CertDb`), Syncfusion license key, CryptoSettings passphrase, cache TTL |
+| `appsettings.Development.json` | Override per sviluppo locale (non deve contenere `ConnectionStrings`) |
+
+**Connection string SQL Server:**
+```json
+"ConnectionStrings": {
+  "CertDb": "Data Source=tcp:IP;Initial Catalog=FirstSolutionDB;User Id=...;Password=...;Encrypt=False;"
+}
+```
+
+## Aggiungere una nuova sezione PDF
+
+1. Implementare `IPdfSectionRenderer`
+2. Impostare `SectionName` e `Order`
+3. Registrare in `Program.cs`:
+   ```csharp
+   builder.Services.AddScoped<IPdfSectionRenderer, NuovaSezione>();
+   ```
+L'orchestratore la include automaticamente ordinandola per `Order`.
+
+## Tema grafico
+
+Tutto il tema (colori, font, layout, brush/pen) è centralizzato in `CertReports.Syncfusion/Helpers/PdfTheme.cs`.
+
+| Colore | Hex | Utilizzo |
+|--------|-----|---------|
+| AccentBlue | `#1565C0` | Titoli, header tabelle, valori chiave |
+| NegativeRed | `#CC0000` | Valori negativi |
+| PositiveGreen | `#2E7D32` | Valori positivi |
+
+## Architettura
+
+```
+HTTP (ISIN) → ReportController → ReportOrchestrator
+    ├── CertificateDataService   (SP → anagrafica, sottostanti, eventi, scenario)
+    ├── AnagraficaSectionRenderer  → PdfDocument (Sezione 1)
+    ├── EventiSectionRenderer      → PdfDocument (Sezione 2)
+    ├── ScenarioSectionRenderer    → PdfDocument (Sezione 3, opzionale)
+    ├── ChartDataService           (SP → dati grafico)
+    ├── SkiaChartRenderer          → PNG in memoria
+    ├── ChartSectionRenderer       → PdfDocument (Sezione 4)
+    └── PdfMergerService           → byte[] → Response
+```
+
+---
+
+*Sviluppato da [Smart Roots](https://www.smart-roots.net)*