Files
mockupAWS/prompt/prompt-v0.4.0-kickoff.md
Luca Sacchi Ricciardi 94db0804d1
Some checks failed
E2E Tests / Run E2E Tests (push) Has been cancelled
E2E Tests / Visual Regression Tests (push) Has been cancelled
E2E Tests / Smoke Tests (push) Has been cancelled
feat: complete v0.4.0 implementation - Reports, Charts, Comparison, Dark Mode
Backend (@backend-dev):
- ReportService with PDF/CSV generation (reportlab, pandas)
- Report API endpoints (POST, GET, DELETE, download with rate limiting)
- Professional PDF templates with branding and tables
- Storage management with auto-cleanup

Frontend (@frontend-dev):
- Recharts integration: CostBreakdown, TimeSeries, ComparisonBar
- Scenario comparison: multi-select, compare page with side-by-side layout
- Reports UI: generation form, list with status badges, download
- Dark/Light mode: ThemeProvider, toggle, CSS variables
- Responsive design for all components

QA (@qa-engineer):
- E2E testing setup with Playwright
- 100 test cases across 7 spec files
- Visual regression baselines
- CI/CD workflow configuration
- ES modules fixes

Documentation:
- Add todo.md with testing checklist and future roadmap
- Update kickoff prompt for v0.4.0

27 tasks completed, 100% v0.4.0 delivery

Closes: v0.4.0 milestone
2026-04-07 17:46:47 +02:00

456 lines
16 KiB
Markdown

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