mockupAWS/export/kanban.md

Kanban - mockupAWS

Progetto: mockupAWS - Backend Profiler & Cost Estimator
Versione Target: v0.2.0
Data: 2026-04-07
Principio: Little Often - Task < 2 ore

---

Legenda

• 🔴 TODO - Da fare
• 🟡 IN PROGRESS - In corso
• 🟢 DONE - Completato
• ⚪ BLOCKED - Bloccato

Stime: XS (15-30min) | S (30-60min) | M (1-2h) | L (2-4h) | XL (>4h, da spezzare)

---

🔴 TODO - Fase 1: Database & Backend Core

Database Setup (DB-001 → DB-006)

DB-001: Alembic Setup

Assegnato: @db-engineer
Priorità: Alta
Stima: S

Descrizione: Configurare Alembic per migrazioni database async.

Criteri Done:

• Installare alembic e asyncpg
• Inizializzare alembic init
• Configurare alembic.ini con async URL
• Configurare alembic/env.py per SQLAlchemy 2.0 async
• Testare alembic current (connessione OK)

Files:

• backend/alembic.ini
• backend/alembic/env.py

---

DB-002: Migration - Scenarios Table

Assegnato: @db-engineer
Priorità: Alta
Stima: M
Dipende da: DB-001

Descrizione: Creare migrazione per tabella scenarios con tutti i campi e constraints.

Criteri Done:

• Creare migration 001_create_scenarios_table.py
• Definire tutti i campi (id, name, description, tags, status, region, timestamps, totals)
• Aggiungere constraints (CHK, FK)
• Aggiungere indexes (status, region, created_at, tags)
• Creare trigger updated_at
• Testare alembic upgrade head

SQL Reference: Vedere export/architecture.md sezione 3.2

---

DB-003: Migration - Scenario Logs Table

Assegnato: @db-engineer
Priorità: Alta
Stima: M
Dipende da: DB-002

Descrizione: Creare migrazione per tabella scenario_logs.

Criteri Done:

• Creare migration 002_create_scenario_logs_table.py
• Definire campi (id, scenario_id, timestamps, hash, preview, etc.)
• Aggiungere FK a scenarios con ON DELETE CASCADE
• Aggiungere indexes (scenario_id, received_at, hash, has_pii)
• Testare relazione con scenarios

---

DB-004: Migration - Scenario Metrics Table

Assegnato: @db-engineer
Priorità: Alta
Stima: M
Dipende da: DB-002

Descrizione: Creare migrazione per tabella scenario_metrics (time-series).

Criteri Done:

• Creare migration 003_create_scenario_metrics_table.py
• Definire campi per metriche time-series
• Aggiungere indexes (scenario_id, timestamp, metric_type)
• Testare query aggregazione

---

DB-005: Migration - AWS Pricing Table

Assegnato: @db-engineer
Priorità: Alta
Stima: M
Dipende da: DB-002

Descrizione: Creare migrazione per tabella aws_pricing con storico prezzi.

Criteri Done:

• Creare migration 004_create_aws_pricing_table.py
• Definire campi (service, region, tier, price, unit, dates)
• Aggiungere constraints (price > 0, valid dates)
• Aggiungere unique constraint parziale per active prices
• Testare query get_active_pricing

---

DB-006: Migration - Reports Table

Assegnato: @db-engineer
Priorità: Media
Stima: S
Dipende da: DB-002

Descrizione: Creare migrazione per tabella reports.

Criteri Done:

• Creare migration 005_create_reports_table.py
• Definire campi (format, file_path, metadata)
• Aggiungere indexes

---

DB-007: Seed AWS Pricing Data

Assegnato: @db-engineer
Priorità: Alta
Stima: M
Dipende da: DB-005

Descrizione: Popolare tabella aws_pricing con dati reali.

Criteri Done:

• Creare migration 006_seed_aws_pricing.py (opzionale: file separato)
• Inserire prezzi per us-east-1:
  • SQS: $0.40 per milione richieste
  • Lambda Request: $0.20 per milione
  • Lambda Compute: $0.0000166667 per GB-second
  • Bedrock Claude Input: $0.003 per 1K tokens
  • Bedrock Claude Output: $0.015 per 1K tokens
• Inserire prezzi per eu-west-1 (simili)
• Verificare dati inseriti

Dati: Vedere export/prd.md sezione 4.3

---

Backend - Database Layer (BE-001 → BE-005)

BE-001: Database Connection & Session Management

Assegnato: @backend-dev
Priorità: Alta
Stima: M
Dipende da: DB-001

Descrizione: Configurare SQLAlchemy 2.0 async con gestione sessioni.

Criteri Done:

• Creare backend/src/core/database.py
• Configurare create_async_engine con pool
• Creare AsyncSessionLocal factory
• Creare get_db() dependency per FastAPI
• Testare connessione in test

Codice Target:

# core/database.py
from sqlalchemy.ext.asyncio import create_async_engine, AsyncSession
from sqlalchemy.orm import sessionmaker

engine = create_async_engine(DATABASE_URL, echo=True, future=True)
AsyncSessionLocal = sessionmaker(engine, class_=AsyncSession, expire_on_commit=False)

async def get_db():
    async with AsyncSessionLocal() as session:
        yield session

---

BE-002: SQLAlchemy Models

Assegnato: @backend-dev
Priorità: Alta
Stima: L
Dipende da: BE-001

Descrizione: Creare tutti i modelli SQLAlchemy corrispondenti alle tabelle.

Criteri Done:

• Creare backend/src/models/base.py (Base, TimestampMixin)
• Creare scenario.py (Scenario model)
• Creare scenario_log.py (ScenarioLog model)
• Creare scenario_metric.py (ScenarioMetric model)
• Creare aws_pricing.py (AwsPricing model)
• Creare report.py (Report model)
• Definire tutte le relationships
• Testare models (creazione istanze)

Files:

• backend/src/models/__init__.py
• backend/src/models/base.py
• backend/src/models/scenario.py
• backend/src/models/scenario_log.py
• backend/src/models/scenario_metric.py
• backend/src/models/aws_pricing.py
• backend/src/models/report.py

---

BE-003: Pydantic Schemas

Assegnato: @backend-dev
Priorità: Alta
Stima: M
Dipende da: BE-002

Descrizione: Creare Pydantic schemas per request/response validation.

Criteri Done:

• Creare backend/src/schemas/scenario.py
  • ScenarioCreate, ScenarioUpdate, ScenarioResponse, ScenarioList
• Creare backend/src/schemas/log.py
  • LogIngest, LogResponse
• Creare backend/src/schemas/metric.py
  • MetricSummary, CostBreakdown
• Creare backend/src/schemas/pricing.py
  • PricingResponse, PricingUpdate
• Creare backend/src/schemas/report.py
  • ReportRequest, ReportResponse
• Validators per campi (name not empty, valid region, etc.)

---

Backend - Repository Layer (BE-004 → BE-008)

BE-004: Base Repository

Assegnato: @backend-dev
Priorità: Alta
Stima: M
Dipende da: BE-002

Descrizione: Implementare Base Repository con operazioni CRUD generiche.

Criteri Done:

• Creare backend/src/repositories/base.py
• Implementare BaseRepository class (Generic[T])
• Metodi: get(), list(), create(), update(), delete(), count()
• Supporto per filters e pagination
• Type hints completi

Codice Target:

class BaseRepository(Generic[T]):
    def __init__(self, model: Type[T]):
        self.model = model
    
    async def get(self, db: AsyncSession, id: UUID) -> T | None:
        result = await db.execute(select(self.model).where(self.model.id == id))
        return result.scalar_one_or_none()
    
    async def list(self, db: AsyncSession, skip: int = 0, limit: int = 100, **filters) -> list[T]:
        query = select(self.model)
        for key, value in filters.items():
            query = query.where(getattr(self.model, key) == value)
        query = query.offset(skip).limit(limit)
        result = await db.execute(query)
        return result.scalars().all()

---

BE-005: Scenario Repository

Assegnato: @backend-dev
Priorità: Alta
Stima: M
Dipende da: BE-004

Descrizione: Implementare ScenarioRepository con metodi specifici.

Criteri Done:

• Creare backend/src/repositories/scenario_repo.py
• Estendere BaseRepository
• Metodi specifici:
  • get_by_name()
  • list_by_status()
  • list_by_region()
  • update_status()
  • increment_total_requests()
  • update_total_cost()
• Testare tutti i metodi

---

BE-006: Log Repository

Assegnato: @backend-dev
Priorità: Alta
Stima: S
Dipende da: BE-004

Descrizione: Implementare LogRepository.

Criteri Done:

• Creare backend/src/repositories/log_repo.py
• Metodi specifici:
  • get_by_hash() - per deduplicazione
  • list_by_scenario()
  • count_by_scenario()
  • count_pii_by_scenario()

---

BE-007: Metric Repository

Assegnato: @backend-dev
Priorità: Media
Stima: S
Dipende da: BE-004

Descrizione: Implementare MetricRepository.

Criteri Done:

• Creare backend/src/repositories/metric_repo.py
• Metodi specifici:
  • get_aggregated_by_scenario()
  • list_by_type()
  • get_cost_breakdown()

---

BE-008: Pricing Repository

Assegnato: @backend-dev
Priorità: Alta
Stima: S
Dipende da: BE-004

Descrizione: Implementare PricingRepository.

Criteri Done:

• Creare backend/src/repositories/pricing_repo.py
• Metodi specifici:
  • get_active_by_service_region() - CRITICO per calcolo costi
  • list_active()

---

Backend - Service Layer (BE-009 → BE-014)

BE-009: Cost Calculator Service

Assegnato: @backend-dev
Priorità: Alta
Stima: M
Dipende da: BE-008

Descrizione: Implementare servizio calcolo costi usando prezzi da database.

Criteri Done:

• Creare backend/src/services/cost_calculator.py
• Metodi:
  • calculate_sqs_cost(blocks, region)
  • calculate_lambda_cost(invocations, gb_seconds, region)
  • calculate_bedrock_cost(input_tokens, output_tokens, region)
  • calculate_total_cost(log_entry, region)
• Query pricing repository per prezzi attivi
• Formule corrette (vedi architecture.md)
• Unit tests con mock pricing

---

BE-010: Scenario Service

Assegnato: @backend-dev
Priorità: Alta
Stima: L
Dipende da: BE-005

Descrizione: Implementare ScenarioService con business logic.

Criteri Done:

• Creare backend/src/services/scenario_service.py
• Metodi CRUD:
  • create_scenario(data)
  • get_scenario(id)
  • list_scenarios(filters, pagination)
  • update_scenario(id, data)
  • delete_scenario(id)
• Metodi lifecycle:
  • start_scenario(id) - draft → running
  • stop_scenario(id) - running → completed
  • archive_scenario(id) - completed → archived
• Validazioni (name unique, valid transitions)
• Unit tests

---

BE-011: Ingest Service

Assegnato: @backend-dev
Priorità: Alta
Stima: L
Dipende da: BE-006, BE-009

Descrizione: Implementare IngestService per elaborazione log.

Criteri Done:

• Creare backend/src/services/ingest_service.py
• Metodi:
  • ingest_log(scenario_id, log_data) - MAIN METHOD
  • validate_scenario(scenario_id) - check status == running
  • process_log(log_data) - calcola metriche
  • persist_log(scenario_id, processed_log) - salva su DB
  • update_scenario_metrics(scenario_id, metrics)
• Integrare PII detection
• Integrare token counting
• Integrare SQS block calculation
• Integrare cost calculator
• Transaction management (DB commit)

---

BE-012: PII Detector Service

Assegnato: @backend-dev
Priorità: Media
Stima: S
Dipende da: None

Descrizione: Implementare servizio rilevamento PII (estrazione da main.py attuale).

Criteri Done:

• Creare backend/src/services/pii_detector.py
• Pattern regex per:
  • Email
  • SSN (opzionale)
  • Credit card (opzionale)
  • Phone (opzionale)
• Metodo detect(message) -> dict
• Unit tests con vari input

---

BE-013: Report Service (Base)

Assegnato: @backend-dev
Priorità: Media
Stima: M
Dipende da: BE-007

Descrizione: Implementare ReportService per generazione CSV.

Criteri Done:

• Creare backend/src/services/report_service.py
• Metodi:
  • generate_csv(scenario_id) - CSV export
  • compile_metrics(scenario_id) - aggrega dati
• CSV format con headers
• Unit tests

---

BE-014: Tokenizer Service (Refactor)

Assegnato: @backend-dev
Priorità: Bassa
Stima: XS
Dipende da: None

Descrizione: Refactor profilera esistente in servizio.

Criteri Done:

• Creare backend/src/services/tokenizer_service.py
• Spostare logica da src/profiler.py
• Mantenere encoding cl100k_base

---

Backend - API Layer (BE-015 → BE-020)

BE-015: API Dependencies & Error Handling

Assegnato: @backend-dev
Priorità: Alta
Stima: M
Dipende da: None

Descrizione: Configurare FastAPI dependencies e exception handlers.

Criteri Done:

• Creare backend/src/api/deps.py
  • get_db() - DB session
  • get_current_scenario() - scenario validation
• Creare backend/src/core/exceptions.py
  • AppException base
  • NotFoundException
  • ValidationException
  • ConflictException
• Creare exception handlers in main.py
• Global error response format

---

BE-016: Scenarios API Endpoints

Assegnato: @backend-dev
Priorità: Alta
Stima: L
Dipende da: BE-010, BE-015

Descrizione: Implementare tutti gli endpoint CRUD per scenari.

Criteri Done:

• Creare backend/src/api/v1/scenarios.py
• Endpoints:
  • POST /api/v1/scenarios - Create
  • GET /api/v1/scenarios - List (con pagination, filters)
  • GET /api/v1/scenarios/{id} - Get detail
  • PUT /api/v1/scenarios/{id} - Update
  • DELETE /api/v1/scenarios/{id} - Delete
  • POST /api/v1/scenarios/{id}/start - Start
  • POST /api/v1/scenarios/{id}/stop - Stop
  • POST /api/v1/scenarios/{id}/archive - Archive
• Integrare schemas per request/response
• Integration tests

---

BE-017: Ingest API Endpoint (Refactor)

Assegnato: @backend-dev
Priorità: Alta
Stima: M
Dipende da: BE-011, BE-016

Descrizione: Aggiornare endpoint /ingest esistente per usare database.

Criteri Done:

• Refactor backend/src/api/v1/ingest.py
• Aggiungere header X-Scenario-ID required
• Validare scenario esiste e status == running
• Usare IngestService per elaborazione
• Rimuovere stato in-memory (mantenere solo per cache)
• Response 202 Accepted con log_id
• Integration tests

---

BE-018: Metrics API Endpoint

Assegnato: @backend-dev
Priorità: Alta
Stima: M
Dipende da: BE-017

Descrizione: Implementare endpoint metrics per scenari.

Criteri Done:

• Creare backend/src/api/v1/metrics.py
• Endpoints:
  • GET /api/v1/scenarios/{id}/metrics - Summary metrics
  • GET /api/v1/scenarios/{id}/metrics/costs - Cost breakdown
  • GET /api/v1/scenarios/{id}/metrics/timeseries - Time series
• Aggregare dati da scenario_logs e scenario_metrics
• Integration tests

---

BE-019: Pricing API Endpoints (Admin)

Assegnato: @backend-dev
Priorità: Media
Stima: S
Dipende da: BE-016

Descrizione: Implementare endpoint per gestione prezzi.

Criteri Done:

• Creare backend/src/api/v1/pricing.py
• Endpoints:
  • GET /api/v1/pricing - List
  • POST /api/v1/pricing - Create (admin)
  • PUT /api/v1/pricing/{id} - Update (admin)
• Integration tests

---

BE-020: Reports API Endpoint

Assegnato: @backend-dev
Priorità: Media
Stima: S
Dipende da: BE-013

Descrizione: Implementare endpoint report generation.

Criteri Done:

• Creare backend/src/api/v1/reports.py
• Endpoints:
  • POST /api/v1/scenarios/{id}/reports - Generate
  • GET /api/v1/reports/{id}/download - Download
• Supporto format CSV (PDF future)
• Integration tests

---

Testing (QA-001 → QA-005)

QA-001: Unit Tests - Services

Assegnato: @qa-engineer + @backend-dev
Priorità: Alta
Stima: L
Dipende da: BE-009, BE-010, BE-011

Descrizione: Scrivere unit tests per tutti i services.

Criteri Done:

• tests/unit/test_cost_calculator.py
• tests/unit/test_scenario_service.py
• tests/unit/test_ingest_service.py
• tests/unit/test_pii_detector.py
• Mock repositories per isolamento
• Coverage > 80% per service

---

QA-002: Integration Tests - API

Assegnato: @qa-engineer + @backend-dev
Priorità: Alta
Stima: L
Dipende da: BE-016, BE-017, BE-018

Descrizione: Scrivere integration tests per API endpoints.

Criteri Done:

• tests/integration/test_api_scenarios.py
• tests/integration/test_api_ingest.py
• tests/integration/test_api_metrics.py
• Test database con rollback per test
• Test fixtures per dati

---

QA-003: E2E Test - Full Flow

Assegnato: @qa-engineer
Priorità: Media
Stima: M
Dipende da: QA-002

Descrizione: Test end-to-end del flusso completo.

Criteri Done:

• tests/e2e/test_full_flow.py
• Flow: Create → Start → Ingest 10 logs → Get Metrics → Stop
• Verifica costi calcolati correttamente

---

🟡 IN PROGRESS

Vuoto - In attesa inizio Fase 1

---

🟢 DONE

Vuoto - Progetto appena iniziato

---

⚪ BLOCKED

Vuoto - Nessun blocco attuale

---

📊 Summary

Fase	Task Totali	Completati	In Progress	Todo
Fase 1 - Database	7	0	0	7
Fase 1 - Backend DB	5	0	0	5
Fase 1 - Backend Repo	5	0	0	5
Fase 1 - Backend Service	6	0	0	6
Fase 1 - Backend API	6	0	0	6
Fase 1 - Testing	3	0	0	3
TOTALE	32	0	0	32

---

🎯 Priorità per Sprint 1 (Week 1)

Goal: Database pronto e API base funzionanti

1. DB-001 → DB-003 (Database setup e prime 2 tabelle)
2. BE-001 → BE-003 (Connessione e models)
3. BE-004 → BE-005 (Base repo e scenario repo)
4. BE-009 (Cost calculator - critico)
5. BE-015 → BE-016 (API base e scenarios CRUD)

---

Documento creato da @spec-architect
Versione: 1.0
Data: 2026-04-07