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

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:

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