mockupAWS/prompt/prompt-v0.4.0-planning.md

# 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*