feat: implement v0.4.0 - Reports, Charts, Comparison, Dark Mode, E2E Testing

Backend (@backend-dev): - Add ReportService with PDF/CSV generation (reportlab, pandas) - Implement Report API endpoints (POST, GET, DELETE, download) - Add ReportRepository and schemas - Configure storage with auto-cleanup (30 days) - Rate limiting: 10 downloads/minute - Professional PDF templates with charts support Frontend (@frontend-dev): - Integrate Recharts for data visualization - Add CostBreakdown, TimeSeries, ComparisonBar charts - Implement scenario comparison page with multi-select - Add dark/light mode toggle with ThemeProvider - Create Reports page with generation form and list - Add new UI components: checkbox, dialog, tabs, label, skeleton - Implement useComparison and useReports hooks QA (@qa-engineer): - Setup Playwright E2E testing framework - Create 7 test spec files with 94 test cases - Add visual regression testing with baselines - Configure multi-browser testing (Chrome, Firefox, WebKit) - Add mobile responsive tests - Create test fixtures and helpers - Setup GitHub Actions CI workflow Documentation (@spec-architect): - Create detailed kanban-v0.4.0.md with 27 tasks - Update progress.md with v0.4.0 tracking - Create v0.4.0 planning prompt Features: ✅ PDF/CSV Report Generation ✅ Interactive Charts (Pie, Area, Bar) ✅ Scenario Comparison (2-4 scenarios) ✅ Dark/Light Mode Toggle ✅ E2E Test Suite (94 tests) Dependencies added: - Backend: reportlab, pandas, slowapi - Frontend: recharts, date-fns, @radix-ui/react-checkbox/dialog/tabs - Testing: @playwright/test 27 tasks completed, 100% v0.4.0 implementation
2026-04-07 16:11:47 +02:00
parent 311a576f40
commit a5fc85897b
63 changed files with 9218 additions and 246 deletions
--- a/prompt/prompt-v0.4.0-planning.md
+++ b/prompt/prompt-v0.4.0-planning.md
@@ -0,0 +1,483 @@
+# Prompt: Pianificazione v0.4.0 - Reports, Charts & Comparison
+
+> **Progetto:** mockupAWS - Backend Profiler & Cost Estimator  
+> **Versione Target:** v0.4.0  
+> **Focus:** Report Generation, Data Visualization, Scenario Comparison  
+> **Stima Tempo:** 2-3 settimane  
+> **Priorità:** P1 (High)
+
+---
+
+## 🎯 Obiettivi v0.4.0
+
+### Goals Principali
+1. **Report Generation** - Generazione report PDF e CSV professionali
+2. **Data Visualization** - Grafici interattivi con Recharts
+3. **Scenario Comparison** - Confronto side-by-side tra scenari multipli
+4. **Dark/Light Mode** - Toggle tema UI completo
+5. **Testing E2E** - Setup testing end-to-end con Playwright
+
+### Metriche di Successo
+- [ ] Report PDF generati in <3 secondi
+- [ ] CSV export funzionante con tutti i dati
+- [ ] 3+ tipi di grafici interattivi
+- [ ] Confronto 2-4 scenari simultaneamente
+- [ ] Code coverage >70%
+- [ ] Zero regressioni v0.3.0
+
+---
+
+## 📋 Feature Breakdown
+
+### 1. Report Generation System 📝
+
+#### Backend (BE-RPT-001 → BE-RPT-005)
+
+**BE-RPT-001: Report Service Implementation**
+- Implementare `ReportService` con metodi:
+  - `generate_pdf(scenario_id: UUID) -> Report`
+  - `generate_csv(scenario_id: UUID) -> Report`
+  - `compile_metrics(scenario_id: UUID) -> dict`
+- Librerie: `reportlab` (PDF), `pandas` (CSV)
+- Template PDF con logo, header, footer, pagine numerate
+- Includere:
+  - Summary scenario (nome, regione, periodo, stato)
+  - Cost breakdown per servizio (SQS, Lambda, Bedrock)
+  - Metriche aggregate (totali, medie, picchi)
+  - Top 10 logs più costosi
+  - PII violations summary
+  - Grafici embedded (se PDF lo supporta)
+
+**BE-RPT-002: Report Generation API**
+- Endpoint: `POST /api/v1/scenarios/{id}/reports`
+- Request body:
+  ```json
+  {
+    "format": "pdf" | "csv",
+    "include_logs": boolean,
+    "date_from": "ISO8601" | null,
+    "date_to": "ISO8601" | null,
+    "sections": ["summary", "costs", "metrics", "logs", "pii"]
+  }
+  ```
+- Response: `202 Accepted` con `report_id`
+- Background task per generazione (Celery oppure async FastAPI)
+- Progress tracking via `GET /api/v1/reports/{id}/status`
+
+**BE-RPT-003: Report Download API**
+- Endpoint: `GET /api/v1/reports/{id}/download`
+- Response: File stream con headers corretti
+- Supporto `Content-Disposition: attachment`
+- Mime types: `application/pdf`, `text/csv`
+- Rate limiting: 10 download/minuto
+
+**BE-RPT-004: Report Storage**
+- Tabella `reports` già esistente
+- Salvare file in filesystem (o S3 in futuro)
+- Path: `./storage/reports/{scenario_id}/{report_id}.{format}`
+- Cleanup automatico dopo 30 giorni (configurabile)
+- Max file size: 50MB
+
+**BE-RPT-005: Report Templates**
+- Template HTML per PDF (usare Jinja2 + WeasyPrint oppure ReportLab diretto)
+- Stile professionale coerente con brand
+- Header con logo mockupAWS
+- Colori coerenti (primario: #0066CC)
+- Font: Inter o Roboto
+- Tabelle formattate con zebra striping
+
+#### Frontend (FE-RPT-001 → FE-RPT-004)
+
+**FE-RPT-001: Report Generation UI**
+- Nuova pagina: `/scenarios/:id/reports`
+- Sezione "Generate Report" con form:
+  - Select formato (PDF/CSV toggle)
+  - Checkbox: include_logs, sections
+  - Date range picker (optional)
+  - Preview dati che saranno inclusi
+- Bottone "Generate" con loading state
+- Toast notification quando report pronto
+
+**FE-RPT-002: Reports List**
+- Tabella reports generati per scenario
+- Colonne: Data, Formato, Dimensione, Stato, Azioni
+- Azioni: Download, Delete, Rigenera
+- Badge stato: Pending, Processing, Completed, Failed
+- Sorting per data (default: newest first)
+- Pagination se necessario
+
+**FE-RPT-003: Report Download Handler**
+- Download file con nome appropriato: `{scenario_name}_YYYY-MM-DD.{format}`
+- Axios con `responseType: 'blob'`
+- Creare ObjectURL per trigger download
+- Cleanup dopo download
+- Error handling con toast
+
+**FE-RPT-004: Report Preview**
+- Preview CSV in tabella (primi 100 record)
+- Info box con summary prima di generare
+- Stima dimensione file
+- Costo stimato basato su metriche
+
+---
+
+### 2. Data Visualization 📊
+
+#### Frontend (FE-VIZ-001 → FE-VIZ-006)
+
+**FE-VIZ-001: Recharts Integration**
+- Installare: `recharts`, `date-fns`
+- Setup tema coerente con Tailwind/shadcn
+- Color palette per grafici (primario, secondario, accenti)
+- Responsive containers
+
+**FE-VIZ-002: Cost Breakdown Chart**
+- Tipo: Pie Chart o Donut Chart
+- Dati: Costo per servizio (SQS, Lambda, Bedrock)
+- Percentuali visualizzate
+- Legend interattiva (toggle servizi)
+- Tooltip con valori esatti ($)
+- Posizione: Dashboard e Scenario Detail
+
+**FE-VIZ-003: Time Series Chart**
+- Tipo: Area Chart o Line Chart
+- Dati: Metriche nel tempo (requests, costi cumulativi)
+- X-axis: Timestamp
+- Y-axis: Valore (count o $)
+- Multi-line per diversi tipi di metriche
+- Zoom e pan (se supportato da Recharts)
+- Posizione: Scenario Detail (tab "Metrics")
+
+**FE-VIZ-004: Comparison Bar Chart**
+- Tipo: Grouped Bar Chart
+- Dati: Confronto metriche tra scenari
+- X-axis: Nome scenario
+- Y-axis: Valore metrica
+- Selettore metrica: Costo totale, Requests, SQS blocks, Tokens
+- Posizione: Compare Page
+
+**FE-VIZ-005: Metrics Distribution Chart**
+- Tipo: Histogram o Box Plot (se Recharts supporta)
+- Dati: Distribuzione dimensioni log, tempi risposta
+- Posizione: Scenario Detail (tab "Analysis")
+
+**FE-VIZ-006: Dashboard Overview Charts**
+- Mini charts nella lista scenari (sparklines)
+- Ultimi 7 giorni di attività
+- Quick stats con trend indicator (↑ ↓)
+
+---
+
+### 3. Scenario Comparison 🔍
+
+#### Backend (BE-CMP-001 → BE-CMP-003)
+
+**BE-CMP-001: Comparison API**
+- Endpoint: `POST /api/v1/scenarios/compare`
+- Request body:
+  ```json
+  {
+    "scenario_ids": ["uuid1", "uuid2", "uuid3"],
+    "metrics": ["total_cost", "total_requests", "sqs_blocks", "tokens"]
+  }
+  ```
+- Response:
+  ```json
+  {
+    "scenarios": [...],
+    "comparison": {
+      "total_cost": { "baseline": 100, "variance": [0, +15%, -20%] },
+      "metrics": [...]
+    }
+  }
+  ```
+- Max 4 scenari per confronto
+- Validazione: tutti scenari esistono e user ha accesso
+
+**BE-CMP-002: Delta Calculation**
+- Calcolare variazione percentuale vs baseline (primo scenario)
+- Evidenziare miglioramenti/peggioramenti
+- Ordinare scenari per costo totale
+- Export comparison come CSV/PDF
+
+**BE-CMP-003: Comparison Cache**
+- Cache risultati per 5 minuti (in-memory)
+- Cache key: hash degli scenario_ids ordinati
+
+#### Frontend (FE-CMP-001 → FE-CMP-004)
+
+**FE-CMP-001: Comparison Selection UI**
+- Checkbox multi-selezione nella lista scenari
+- Bottone "Compare Selected" (enabled quando 2-4 selezionati)
+- Modal confirmation con lista scenari
+- Visualizzazione "Comparison Mode" indicator
+
+**FE-CMP-002: Compare Page**
+- Nuova route: `/compare`
+- Layout side-by-side (2 colonne per 2 scenari, 4 per 4 scenari)
+- Responsive: su mobile diventa scroll orizzontale
+- Header con nome scenario, regione, stato
+- Summary cards affiancate
+
+**FE-CMP-003: Comparison Tables**
+- Tabella dettagliata con metriche affiancate
+- Color coding: verde (migliore), rosso (peggiore), grigio (neutro)
+- Delta column con trend arrow
+- Export comparison button
+
+**FE-CMP-004: Visual Comparison**
+- Grouped bar chart per confronto visivo
+- Highlight scenario selezionato
+- Toggle metriche da confrontare
+
+---
+
+### 4. Dark/Light Mode Toggle 🌓
+
+#### Frontend (FE-THM-001 → FE-THM-004)
+
+**FE-THM-001: Theme Provider Setup**
+- Theme context o Zustand store
+- Persistenza in localStorage
+- Default: system preference (media query)
+- Toggle button in Header
+
+**FE-THM-002: Tailwind Dark Mode Configuration**
+- Aggiornare `tailwind.config.js`:
+  ```js
+  darkMode: 'class'
+  ```
+- Wrapper component con `dark` class sul root
+- Transition smooth tra temi
+
+**FE-THM-003: Component Theme Support**
+- Verificare tutti i componenti shadcn/ui supportino dark mode
+- Aggiornare classi custom per dark variant:
+  - `bg-white` → `bg-white dark:bg-gray-900`
+  - `text-gray-900` → `text-gray-900 dark:text-white`
+  - Bordi, shadow, hover states
+
+**FE-THM-004: Chart Theming**
+- Recharts tema dark (colori assi, grid, tooltip)
+- Colori serie dati visibili su entrambi i temi
+- Background chart trasparente o temizzato
+
+---
+
+### 5. Testing E2E Setup 🧪
+
+#### QA (QA-E2E-001 → QA-E2E-004)
+
+**QA-E2E-001: Playwright Setup**
+- Installare: `@playwright/test`
+- Configurare `playwright.config.ts`
+- Scripts: `test:e2e`, `test:e2e:ui`, `test:e2e:debug`
+- Setup CI (GitHub Actions oppure locale)
+
+**QA-E2E-002: Test Scenarios**
+- Test: Creazione scenario completo
+- Test: Ingestione log e verifica metriche
+- Test: Generazione e download report
+- Test: Navigazione tra pagine
+- Test: Responsive design (mobile viewport)
+
+**QA-E2E-003: Test Data**
+- Fixtures per scenari di test
+- Seed database per test
+- Cleanup dopo ogni test
+- Parallel execution config
+
+**QA-E2E-004: Visual Regression**
+- Screenshot testing per UI critica
+- Baseline images in repo
+- Fallimento test se diff > threshold
+
+---
+
+## 🎨 UI/UX Requirements
+
+### Design Principles
+- **Consistency**: Usare stessi pattern v0.3.0
+- **Feedback**: Loading states, toast notifications, progress indicators
+- **Accessibility**: WCAG 2.1 AA compliance
+- **Mobile**: Responsive design per tutte le feature
+
+### Componenti UI da Aggiungere
+- `DateRangePicker` - Per filtro report
+- `FileDownload` - Componente download con progress
+- `ComparisonCard` - Card per confronto scenari
+- `ChartContainer` - Wrapper responsive per Recharts
+- `ThemeToggle` - Toggle dark/light mode
+
+### Animazioni
+- Page transitions (React Router + Framer Motion opzionale)
+- Chart animations (Recharts built-in)
+- Toast slide-in
+- Loading skeletons
+
+---
+
+## 🏗️ Technical Architecture
+
+### Backend Changes
+```
+src/
+├── api/v1/
+│   └── reports.py              # NUOVO: Report endpoints
+├── services/
+│   └── report_service.py       # NUOVO: PDF/CSV generation
+├── core/
+│   └── storage.py              # NUOVO: File storage abstraction
+└── tasks/                      # NUOVO: Background tasks
+    └── report_tasks.py
+```
+
+### Frontend Changes
+```
+frontend/src/
+├── pages/
+│   ├── Reports.tsx             # NUOVO: Reports management
+│   └── Compare.tsx             # NUOVO: Scenario comparison
+├── components/
+│   ├── charts/                 # NUOVO: Chart components
+│   │   ├── CostBreakdown.tsx
+│   │   ├── TimeSeries.tsx
+│   │   └── ComparisonChart.tsx
+│   ├── reports/                # NUOVO: Report components
+│   │   ├── ReportGenerator.tsx
+│   │   └── ReportList.tsx
+│   └── ui/
+│       └── theme-toggle.tsx    # NUOVO
+├── hooks/
+│   ├── useReports.ts           # NUOVO
+│   └── useComparison.ts        # NUOVO
+└── lib/
+    └── theme.ts                # NUOVO: Theme utilities
+```
+
+---
+
+## 📅 Timeline Suggerita (2-3 settimane)
+
+### Week 1: Foundation & Reports
+- **Giorno 1-2**: BE-RPT-001, BE-RPT-002 (Report service e API)
+- **Giorno 3**: BE-RPT-003, FE-RPT-001, FE-RPT-002 (Download e UI)
+- **Giorno 4**: BE-RPT-004, BE-RPT-005 (Storage e templates)
+- **Giorno 5**: Testing reports, bug fixing
+
+### Week 2: Charts & Comparison
+- **Giorno 6-7**: FE-VIZ-001 → FE-VIZ-004 (Recharts integration)
+- **Giorno 8**: BE-CMP-001, BE-CMP-002 (Comparison API)
+- **Giorno 9**: FE-CMP-001 → FE-CMP-004 (Comparison UI)
+- **Giorno 10**: FE-VIZ-005, FE-VIZ-006 (Additional charts)
+
+### Week 3: Polish & Testing
+- **Giorno 11-12**: FE-THM-001 → FE-THM-004 (Dark mode)
+- **Giorno 13**: QA-E2E-001 → QA-E2E-004 (Testing setup)
+- **Giorno 14**: Bug fixing, performance optimization, documentation
+- **Giorno 15**: Final review, demo, release v0.4.0
+
+---
+
+## ✅ Acceptance Criteria
+
+### Report Generation
+- [ ] PDF generato correttamente con tutte le sezioni richieste
+- [ ] CSV contiene tutti i log e metriche in formato tabellare
+- [ ] Download funziona su Chrome, Firefox, Safari
+- [ ] File size < 50MB per scenari grandi
+- [ ] Report deleted dopo 30 giorni (cleanup)
+
+### Charts
+- [ ] Tutti i grafici sono responsive (resize corretto)
+- [ ] Tooltip mostra dati corretti
+- [ ] Animazioni smooth (no jank)
+- [ ] Funzionano in entrambi i temi (dark/light)
+- [ ] Performance: <100ms per renderizzare
+
+### Comparison
+- [ ] Confronto 2-4 scenari simultaneamente
+- [ ] Variazioni percentuali calcolate correttamente
+- [ ] UI responsive su mobile
+- [ ] Export comparison disponibile
+- [ ] Color coding intuitivo
+
+### Dark Mode
+- [ ] Toggle funziona istantaneamente
+- [ ] Persistenza dopo refresh
+- [ ] Tutti i componenti visibili in entrambi i temi
+- [ ] Charts adeguatamente temizzati
+- [ ] Nessun contrasto illeggibile
+
+### Testing
+- [ ] E2E tests passano in CI
+- [ ] Coverage >70% (backend)
+- [ ] Visual regression baseline stabilita
+- [ ] Zero regressioni v0.3.0
+- [ ] Documentazione testing aggiornata
+
+---
+
+## 🚧 Rischi e Mitigazioni
+
+| Rischio | Probabilità | Impatto | Mitigazione |
+|---------|-------------|---------|-------------|
+| ReportLab complesso | Media | Alto | Usare WeasyPrint (HTML→PDF) come alternativa |
+| Performance charts con molti dati | Media | Medio | Virtualization, data sampling, pagination |
+| Dark mode inconsistente | Bassa | Medio | Audit visivo completo, design tokens |
+| E2E tests flaky | Media | Medio | Retry logic, deterministic selectors, wait conditions |
+| Scope creep | Alta | Medio | Strict deadline, MVP first, nice-to-have in backlog |
+
+---
+
+## 📝 Notes per Implementazione
+
+### Libraries Consigliate
+```bash
+# Backend
+pip install reportlab pandas xlsxwriter  # Reports
+pip install celery redis                  # Background tasks (optional)
+
+# Frontend
+npm install recharts date-fns             # Charts
+npm install @playwright/test              # E2E testing
+npm install zustand                       # State management (optional, for theme)
+```
+
+### Pattern da Seguire
+- **Report Generation**: Async task con status polling
+- **Charts**: Container/Presentational pattern
+- **Comparison**: Derive state, non duplicare dati
+- **Theme**: CSS variables + Tailwind dark mode
+
+### Performance Considerations
+- Lazy load chart components
+- Debounce resize handlers
+- Virtualize long lists (reports)
+- Cache comparison results
+- Optimize re-renders (React.memo)
+
+---
+
+## 🎯 Definition of Done
+
+- [ ] Tutti i task P1 completati
+- [ ] Code review passato
+- [ ] Tests passanti (unit + integration + e2e)
+- [ ] Documentation aggiornata (README, API docs)
+- [ ] Demo funzionante
+- [ ] CHANGELOG.md aggiornato
+- [ ] Tag v0.4.0 creato
+- [ ] Deploy su staging verificato
+
+---
+
+**Assegnato a:** @frontend-dev (lead), @backend-dev (supporto API), @qa-engineer (testing)  
+**Reviewer:** @spec-architect  
+**Deadline:** 3 settimane dalla data di inizio  
+**Dependencies:** v0.3.0 completata (✅)
+
+---
+
+*Prompt generato per pianificazione v0.4.0*  
+*Data: 2026-04-07*