# Prompt: Kickoff v0.4.0 - Implementazione Reports, Charts & Comparison

> **Progetto:** mockupAWS - Backend Profiler & Cost Estimator  
> **Versione Target:** v0.4.0  
> **Data Kickoff:** 2026-04-07  
> **Deadline:** 2-3 settimane  
> **Stato:** 🚀 Pronta per inizio implementazione

---

## 🎯 Contesto e Stato Attuale

### ✅ Cosa è stato completato (v0.3.0)
- **Backend v0.3.0:** Database PostgreSQL, API CRUD scenari, Ingest, Metrics, autenticazione base
- **Frontend v0.3.0:** React + Vite + TypeScript, Dashboard, Scenario Detail/Edit, API integration
- **DevOps:** Docker Compose, PostgreSQL container
- **Documentazione:** PRD, Architecture, Kanban, Progress tracking

### 📋 Cosa è pronto per v0.4.0
- **Pianificazione completa:** `prompt/prompt-v0.4.0-planning.md` con 27 task dettagliati
- **Kanban:** `export/kanban-v0.4.0.md` con priorità e dipendenze
- **Architecture:** Pattern definiti, librerie scelte, API specs

---

## 🚀 OBIETTIVO: Implementare v0.4.0

### Goals
1. **Report Generation System** - PDF/CSV professionali con download
2. **Data Visualization** - Grafici interattivi (Pie, Area, Bar) con Recharts
3. **Scenario Comparison** - Confronto multi-scenario side-by-side
4. **Dark/Light Mode** - Toggle tema completo per tutta l'app
5. **E2E Testing** - Suite Playwright con 94+ test cases

### Metriche di Successo
- [ ] Report PDF generati in <3 secondi
- [ ] 3+ tipi di grafici funzionanti e responsive
- [ ] Confronto 2-4 scenari simultaneamente
- [ ] Dark mode applicabile a tutti i componenti
- [ ] E2E tests passanti su Chromium (priorità)
- [ ] Code coverage >70%

---

## 👥 ASSEGNAZIONE TASK

### @backend-dev - Backend Report Generation (5 task)

**Priorità P1 - Week 1 Focus**

#### BE-RPT-001: Report Service Implementation
**File:** `src/services/report_service.py` (creare)
- [ ] Metodo `generate_pdf(scenario_id: UUID) -> Report`
  - Usare `reportlab` per PDF
  - Template professionale: header con logo, footer con pagine, tabelle zebra
  - Sezioni: scenario summary, cost breakdown (SQS/Lambda/Bedrock), metrics aggregate, top 10 logs, PII violations
- [ ] Metodo `generate_csv(scenario_id: UUID) -> Report`
  - Usare `pandas` per CSV
  - Tutti i campi dei logs inclusi
- [ ] Metodo `compile_metrics(scenario_id: UUID) -> dict`
  - Aggregare dati da scenario_logs e scenario_metrics
  - Calcolare totali, medie, percentuali
- [ ] Metodo `cleanup_old_reports()`
  - Rimozione automatica file >30 giorni

**Test:** Verificare generazione PDF/CSV funzioni correttamente

#### BE-RPT-002: Report Generation API
**File:** `src/api/v1/reports.py` (creare)
- [ ] Endpoint `POST /api/v1/scenarios/{id}/reports`
  - Request body: `{format: "pdf"|"csv", include_logs: bool, date_from?: string, date_to?: string, sections: string[]}`
  - Response: `202 Accepted` con `{report_id: uuid, status: "pending"}`
  - Implementare come background task async
- [ ] Endpoint `GET /api/v1/reports/{id}/status`
  - Response: `{report_id, status: "pending"|"processing"|"completed"|"failed", progress: number, message: string}`
- [ ] Endpoint `GET /api/v1/scenarios/{id}/reports` (list)
  - Query params: page, page_size
  - Response: lista reports con metadata

**Integrazione:** Aggiornare `src/api/v1/__init__.py` per includere router

#### BE-RPT-003: Report Download API
**File:** Modificare `src/api/v1/reports.py`
- [ ] Endpoint `GET /api/v1/reports/{id}/download`
  - File streaming con `StreamingResponse`
  - Headers: `Content-Type` (application/pdf o text/csv), `Content-Disposition: attachment`
  - Rate limiting: 10 download/minuto (usare slowapi)
- [ ] Endpoint `DELETE /api/v1/reports/{id}`
  - Cancellare record DB e file fisico

**Test:** Verificare download funzioni, rate limiting attivo

#### BE-RPT-004: Report Storage
**File:** Modificare `src/core/config.py`, creare directory
- [ ] Path storage: `./storage/reports/{scenario_id}/{report_id}.{format}`
- [ ] Creare directory se non esiste
- [ ] Max file size: 50MB (configurabile in Settings)
- [ ] Cleanup job: eseguire `cleanup_old_reports()` periodicamente

#### BE-RPT-005: PDF Templates
**File:** `src/services/report_templates/` (creare directory)
- [ ] Template base con:
  - Header: logo mockupAWS (placeholder), titolo report
  - Colori: primario #0066CC, grigio #F5F5F5 per sfondi
  - Font: Helvetica/Arial (standard ReportLab)
  - Tabelle: zebra striping, bordi sottili
  - Footer: "Pagina X di Y", data generazione
- [ ] Stili definiti in `styles.py`

**Output atteso:** PDF professionale e leggibile

---

### @frontend-dev - Frontend Implementation (18 task)

**Priorità P1 - Week 1-2, Priorità P2 - Week 2-3**

#### FE-VIZ-001: Recharts Integration (Setup)
**File:** Installazioni e config
- [ ] Installare: `npm install recharts date-fns`
- [ ] Creare `src/components/charts/ChartContainer.tsx` (wrapper responsive)
- [ ] Definire color palette per charts (coerente con Tailwind)
- [ ] Setup tema per dark mode

#### FE-VIZ-002: Cost Breakdown Chart
**File:** `src/components/charts/CostBreakdown.tsx`
- [ ] Componente Pie/Donut chart
- [ ] Props: `data: Array<{service: string, cost: number, percentage: number}>`
- [ ] Legend interattiva (toggle servizi)
- [ ] Tooltip con valori esatti in $
- [ ] Responsive (usa ChartContainer)
- [ ] **Posizione:** Integrare in Dashboard e ScenarioDetail

#### FE-VIZ-003: Time Series Chart
**File:** `src/components/charts/TimeSeries.tsx`
- [ ] Componente Area/Line chart
- [ ] Props: `data: Array<{timestamp: string, value: number}>`, `series: Array<{key: string, name: string, color: string}>`
- [ ] Multi-line support (diverse metriche)
- [ ] X-axis: timestamp formattato (date-fns)
- [ ] **Posizione:** Tab "Metrics" in ScenarioDetail

#### FE-VIZ-004: Comparison Bar Chart
**File:** `src/components/charts/ComparisonBar.tsx`
- [ ] Componente Grouped Bar chart
- [ ] Props: `scenarios: Array<Scenario>`, `metric: string`
- [ ] Selettore metrica (dropdown)
- [ ] Colori diversi per ogni scenario
- [ ] **Posizione:** Compare page

#### FE-VIZ-005 & 006: Additional Charts (P2)
- [ ] Metrics Distribution (istogramma) - se Recharts supporta
- [ ] Dashboard sparklines (mini charts)

#### FE-CMP-001: Comparison Selection UI
**File:** Modificare `src/pages/ScenariosPage.tsx`
- [ ] Aggiungere checkbox multi-selezione in ogni riga scenario
- [ ] Stato: `selectedScenarios: string[]`
- [ ] Bottone "Compare Selected" (disabled se <2 o >4 selezionati)
- [ ] Mostrare contatore "2-4 scenarios selected"
- [ ] Modal confirmation con lista scenari selezionati
- [ ] Click su "Compare" naviga a `/compare?ids=id1,id2,id3`

#### FE-CMP-002: Compare Page
**File:** `src/pages/Compare.tsx` (creare)
- [ ] Route: `/compare`
- [ ] Leggere query param `ids` (comma-separated UUIDs)
- [ ] Layout responsive:
  - Desktop: 2-4 colonne side-by-side
  - Tablet: 2 colonne + scroll
  - Mobile: scroll orizzontale o accordion
- [ ] Header per ogni scenario: nome, regione, stato badge
- [ ] Summary cards: total cost, requests, SQS blocks, tokens

#### FE-CMP-003: Comparison Tables
**File:** Modificare `src/pages/Compare.tsx`
- [ ] Tabella dettagliata con metriche affiancate
- [ ] Colonne: Metrica | Scenario 1 | Scenario 2 | ... | Delta
- [ ] Color coding:
  - Verde: valore migliore (es. costo minore)
  - Rosso: valore peggiore
  - Grigio: neutro
- [ ] Calcolo delta percentuale vs baseline (primo scenario)
- [ ] Export comparison button (CSV)

#### FE-CMP-004: Visual Comparison
**File:** Integrare in `src/pages/Compare.tsx`
- [ ] Includere ComparisonBar chart
- [ ] Toggle metriche da confrontare
- [ ] Highlight scenario selezionato on hover

#### FE-RPT-001: Report Generation UI
**File:** `src/pages/Reports.tsx` (creare)
- [ ] Route: `/scenarios/:id/reports`
- [ ] Sezione "Generate Report":
  - Toggle formato: PDF / CSV
  - Checkbox: include_logs
  - Date range picker (opzionale, default: tutto)
  - Selezione sezioni: summary, costs, metrics, logs, pii
  - Preview: conteggio logs che saranno inclusi
- [ ] Bottone "Generate" con loading state
- [ ] Toast notification quando report pronto (polling su status)

#### FE-RPT-002: Reports List
**File:** Modificare `src/pages/Reports.tsx`
- [ ] Tabella reports già generati
- [ ] Colonne: Data, Formato, Dimensione, Stato, Azioni
- [ ] Badge stato: 🟡 Pending / 🟢 Completed / 🔴 Failed
- [ ] Azioni: Download (icona), Delete (icona cestino), Regenerate
- [ ] Sorting per data (newest first)
- [ ] Empty state se nessun report

#### FE-RPT-003: Report Download Handler
**File:** Hook o utility
- [ ] Funzione `downloadReport(reportId: string, filename: string)`
- [ ] Axios con `responseType: 'blob'`
- [ ] Creare ObjectURL e trigger download
- [ ] Cleanup dopo download
- [ ] Error handling con toast

#### FE-RPT-004: Report Preview (P2)
**File:** Modificare `src/pages/Reports.tsx`
- [ ] Preview CSV: mostrare prime 10 righe in tabella
- [ ] Info box con summary prima di generare
- [ ] Stima dimensione file

#### FE-THM-001: Theme Provider Setup
**File:** `src/providers/ThemeProvider.tsx` (creare)
- [ ] Context: `{ theme: 'light'|'dark'|'system', setTheme: fn }`
- [ ] Persistenza in localStorage
- [ ] Default: 'system' (usa media query prefers-color-scheme)
- [ ] Effetto: applica classe 'dark' o 'light' al root

#### FE-THM-002: Tailwind Dark Mode Config
**File:** `tailwind.config.js`, `src/index.css`
- [ ] Aggiungere `darkMode: 'class'` in tailwind.config.js
- [ ] Definire CSS variables per colori temizzabili
- [ ] Transition smooth tra temi (300ms)

#### FE-THM-003: Component Theme Support
**File:** Tutti i componenti UI
- [ ] Verificare tutti i componenti shadcn/ui supportino dark mode
- [ ] Aggiornare classi custom:
  - `bg-white` → `bg-white dark:bg-gray-900`
  - `text-gray-900` → `text-gray-900 dark:text-white`
  - `border-gray-200` → `border-gray-200 dark:border-gray-700`
- [ ] Testare ogni pagina in entrambi i temi

#### FE-THM-004: Theme Toggle Component
**File:** `src/components/ui/theme-toggle.tsx` (creare)
- [ ] Toggle button con icona sole/luna
- [ ] Dropdown: Light / Dark / System
- [ ] Posizione: Header (vicino ad altre icone)
- [ ] Stato attivo evidenziato

**Aggiuntivi:**
- [ ] Chart theming (Recharts supporta temi)
- [ ] Toast notifications (sonner già supporta dark mode)

---

### @qa-engineer - E2E Testing (4 task)

**Priorità P3 - Week 2-3 (dopo che FE/BE sono stabili)**

#### QA-E2E-001: Playwright Setup
**File:** Configurazioni
- [ ] Verificare `@playwright/test` installato
- [ ] Verificare `playwright.config.ts` configurato:
  - Test directory: `e2e/`
  - Base URL: `http://localhost:5173`
  - Browsers: Chromium (priority), Firefox, WebKit
  - Screenshots on failure: true
  - Video: on-first-retry
- [ ] Scripts NPM funzionanti:
  - `npm run test:e2e`
  - `npm run test:e2e:ui`
  - `npm run test:e2e:debug`

#### QA-E2E-002: Test Implementation
**File:** `frontend/e2e/*.spec.ts` (verificare/esistono già)
- [ ] `scenario-crud.spec.ts` - 11 tests
  - Create, edit, delete scenarios
  - Validation errori
- [ ] `ingest-logs.spec.ts` - 9 tests
  - Ingest logs, verify metrics update
  - PII detection verification
- [ ] `reports.spec.ts` - 10 tests
  - Generate PDF/CSV reports
  - Download reports
  - Verify file contents
- [ ] `comparison.spec.ts` - 16 tests
  - Select multiple scenarios
  - Navigate to compare page
  - Verify comparison data
- [ ] `navigation.spec.ts` - 21 tests
  - All routes accessible
  - 404 handling
  - Mobile responsive
- [ ] `visual-regression.spec.ts` - 18 tests
  - Screenshot testing
  - Dark/light mode consistency

**Verificare:** Tutti i test siano deterministici (no flaky tests)

#### QA-E2E-003: Test Data & Fixtures
**File:** `frontend/e2e/fixtures/`, `utils/`
- [ ] `test-scenarios.ts` - Dati scenari di test
- [ ] `test-logs.ts` - Dati logs di test
- [ ] `test-helpers.ts` - API utilities (createScenario, cleanup, etc.)
- [ ] Database seeding prima dei test
- [ ] Cleanup dopo ogni test suite

#### QA-E2E-004: Visual Regression & CI
**File:** GitHub Actions, screenshots
- [ ] Baseline screenshots in `e2e/screenshots/baseline/`
- [ ] Configurare threshold (20% tolerance)
- [ ] GitHub Actions workflow `.github/workflows/e2e.yml`:
  - Trigger: push/PR to main
  - Services: PostgreSQL
  - Steps: setup, seed DB, run tests, upload artifacts
- [ ] Documentazione in `frontend/e2e/README.md`

---

## 📅 TIMELINE SUGGERITA

### Week 1: Foundation & Reports
- **Giorno 1-2:** @backend-dev BE-RPT-001, @frontend-dev FE-VIZ-001 + FE-THM-001
- **Giorno 3:** @backend-dev BE-RPT-002, @frontend-dev FE-VIZ-002 + FE-VIZ-003
- **Giorno 4:** @backend-dev BE-RPT-003 + BE-RPT-004, @frontend-dev FE-RPT-001 + FE-RPT-002
- **Giorno 5:** @backend-dev BE-RPT-005, @frontend-dev FE-THM-002 + FE-THM-004
- **Weekend:** Testing integrazione, bugfixing

### Week 2: Charts & Comparison
- **Giorno 6-7:** @frontend-dev FE-CMP-001 + FE-CMP-002 + FE-VIZ-004
- **Giorno 8:** @frontend-dev FE-CMP-003 + FE-CMP-004
- **Giorno 9:** @frontend-dev FE-RPT-003 + FE-RPT-004
- **Giorno 10:** @frontend-dev FE-THM-003 (audit tutti componenti)
- **Giorno 11-12:** @frontend-dev Polish, responsive, animazioni

### Week 3: Testing & Polish
- **Giorno 13-14:** @qa-engineer QA-E2E-001 + QA-E2E-002 (setup e test principali)
- **Giorno 15:** @qa-engineer QA-E2E-003 + QA-E2E-004 (fixtures e CI)
- **Giorno 16:** Bugfixing cross-team
- **Giorno 17:** Performance optimization
- **Giorno 18:** Final review, documentation update
- **Giorno 19-21:** Buffer per imprevisti

---

## 🔧 CONSEGNE (Deliverables)

### Backend (@backend-dev)
- [ ] `src/services/report_service.py` con metodi PDF/CSV
- [ ] `src/api/v1/reports.py` con 5 endpoints
- [ ] `src/schemas/report.py` con Pydantic models
- [ ] `src/repositories/report.py` con metodi DB
- [ ] Directory `storage/reports/` funzionante
- [ ] Test manuale: generazione PDF/CSV funziona

### Frontend (@frontend-dev)
- [ ] 4 Chart components funzionanti e responsive
- [ ] Compare page con confronto 2-4 scenari
- [ ] Reports page con generazione e download
- [ ] Dark mode applicato a tutta l'app
- [ ] Tutte le pagine responsive (mobile, tablet, desktop)

### QA (@qa-engineer)
- [ ] 94+ test cases passanti
- [ ] Test suite stabile (no flaky tests)
- [ ] CI/CD pipeline funzionante
- [ ] Documentazione testing completa

---

## 📋 DIPENDENZE CRITICHE

```
BE-RPT-001 → BE-RPT-002 → BE-RPT-003
     ↓              ↓              ↓
FE-RPT-001 → FE-RPT-002 → FE-RPT-003

FE-VIZ-001 → Tutti i charts

FE-CMP-001 → FE-CMP-002 → FE-CMP-003

FE-THM-001 → FE-THM-002 → FE-THM-003
```

**Note:** Frontend può iniziare FE-VIZ e FE-THM in parallelo al backend.

---

## ✅ DEFINITION OF DONE

Per ogni task:
- [ ] Codice scritto seguendo pattern esistenti
- [ ] TypeScript: nessun errore di tipo (`npm run build` passa)
- [ ] Backend: API testate con curl/Postman
- [ ] Frontend: Componenti visualizzabili e funzionanti
- [ ] Responsive design verificato
- [ ] Error handling implementato
- [ ] Code commentato dove necessario

Per la release v0.4.0:
- [ ] Tutti i task P1 completati
- [ ] Test E2E passanti su Chromium
- [ ] Documentazione aggiornata (README, API docs)
- [ ] CHANGELOG.md aggiornato
- [ ] Commit e push effettuati
- [ ] Tag v0.4.0 creato (opzionale)

---

## 🆘 SUPPORTO

**Se bloccati:**
1. Consultare `prompt/prompt-v0.4.0-planning.md` per dettagli
2. Verificare `export/kanban-v0.4.0.md` per dipendenze
3. Chiedere a @spec-architect per decisioni architetturali
4. Consultare codice v0.3.0 per pattern esistenti

**Risorse utili:**
- ReportLab docs: https://docs.reportlab.com/
- Recharts docs: https://recharts.org/
- Playwright docs: https://playwright.dev/
- shadcn/ui: https://ui.shadcn.com/

---

## 🎯 COMANDO DI INIZIO

Per ogni agente, iniziare con:

```bash
# @backend-dev
cd /home/google/Sources/LucaSacchiNet/mockupAWS
# Iniziare da BE-RPT-001

# @frontend-dev  
cd /home/google/Sources/LucaSacchiNet/mockupAWS/frontend
npm run dev
# Iniziare da FE-VIZ-001 e FE-THM-001 in parallelo

# @qa-engineer
cd /home/google/Sources/LucaSacchiNet/mockupAWS/frontend
# Iniziare da QA-E2E-001 (verifica setup esistente)
```

---

**In bocca al lupo team! 🚀**

*Prompt kickoff generato il 2026-04-07*  
*Inizio implementazione v0.4.0*