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:

  {
    "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:

  {
    "scenario_ids": ["uuid1", "uuid2", "uuid3"],
    "metrics": ["total_cost", "total_requests", "sqs_blocks", "tokens"]
  }
  

• Response:

  {
    "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:

  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

# 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