Modello Dati Logico¶

Panoramica¶

Questa sezione descrive il modello dati logico dell'applicazione mobile HapGree, definito a partire dai contratti OpenAPI (Specs/OpenApi/OpenApi/src/Models/*.ts), dai DTO generati in hapgree_client e dalle strutture dati utilizzate nei ViewModel e nelle entità applicative in lib/.

Nota di architettura: La persistenza fisica (database relazionale, indici, vincoli di integrità e storicizzazione) è gestita interamente a livello di backend. Il client mobile interagisce con queste entità scambiando DTO di richiesta e modelli di risposta JSON.

Entità Principali¶

`User`¶

Rappresenta il profilo dell'utente autenticato nell'applicazione.

Campi principali: - id: identificativo univoco dell'utente - role: ruolo applicativo - email: indirizzo email - name: nome - lastName: cognome - avatarImageUrl: URL dell'immagine profilo - birthdate: data di nascita

Utilizzo: gestione sessione, profilo utente, associazione a viaggi, consumi, gruppi e certificati di compensazione.

`PhysicalActivity`¶

Rappresenta l'attività fisica giornaliera sincronizzata da Health Connect o Apple Health.

Campi principali: - id: identificativo del record - userId: identificativo dell'utente - steps: numero totale di passi registrati - kilometers: distanza percorsa in chilometri - activityDate: data di riferimento dell'attività

`Travel` / `CreateTravel`¶

Rappresenta una sessione di viaggio registrata manualmente o tramite il tracking automatico GPS.

Campi principali (CreateTravel): - distance: distanza in km - travelReasonType: motivazione dello spostamento (work, personal, ecc.) - vehicleType: tipologia di veicolo (dieselCar, electricCar, ecc.) - avgSpeed: velocità media calcolata - totalTime: durata complessiva dello spostamento - idleTime: tempo trascorso in sosta - drivingScore: indice di efficienza di guida - startLocation / endLocation: coordinate di partenza e arrivo - startTime / endTime: timestamp di inizio e fine - polylineSegments: lista di punti per il tracciamento del percorso sulla mappa

`EnergyBill`¶

Rappresenta una bolletta o un consumo energetico inserito dall'utente.

Campi principali: - id: identificativo univoco del record - userId: utente associato - amountConsumed: valore del consumo energetico - type: fonte energetica (water, gas, electricity) - totalEmission: stima di emissioni CO2 calcolata - startDate / endDate: periodo di riferimento della bolletta

`Food`¶

Rappresenta un singolo alimento o prodotto inserito a catalogo.

Campi principali: - id: identificativo del prodotto - ean: codice a barre (EAN/UPC) - name: denominazione del prodotto - category: categoria alimentare - co2KgForProductKg: fattore di emissione (kg CO2 per kg di prodotto) - emissionCategory: classe Green-Score (a - e) - quantity: quantità / peso acquistato - imageUrl: immagine del prodotto

`FoodReceipt`¶

Rappresenta uno scontrino o un acquisto cumulativo di prodotti alimentari.

Campi principali: - id: identificativo dello scontrino - userId: identificativo dell'utente - foods: lista dei prodotti associati (Food[]) - elementsNumber: numero totale di articoli - cO2Emitted: emissione complessiva associata allo scontrino - type: modalità di inserimento (manual, automatic) - status: stato di elaborazione per scontrini OCR (pending, processed, error) - createdAt: data di registrazione

`Group` e `GroupMembership`¶

Gestiscono la dimensione social, le sfide di gruppo e le classifiche condivise.

Campi principali Group: - id: identificativo univoco del gruppo - ownerId: identificativo del creatore - name: nome del gruppo - description: descrizione del gruppo - tag: codice identificativo univoco per l'invito / accesso - isPrivate: flag di visibilità (pubblico / privato)

Campi GroupMembership: - groupId: riferimento al gruppo - userId: riferimento all'utente - joinStatus: stato di adesione (membro, richiesta pendente)

`ChallengeInstance` e `ChallengeProgress`¶

Gestiscono le sfide (giornaliere, settimanali, mensili) per singoli utenti e gruppi.

Campi principali ChallengeInstance: - id: identificativo della challenge - timeframe: scadenza temporale - reward: punti o badge attribuiti al completamento - category: categoria di riferimento - timeframe_type: cadenza (giorno, settimana, mese) - collected: flag di avvenuto riscatto della ricompensa

Campi ChallengeProgress: - challengeId: identificativo della sfida - userId: utente associato - progress: percentuale di completamento (0.0 - 1.0)

`CompensationProject` e `CompensationCertificate`¶

Gestiscono il catalogo dei progetti ecologici e i relativi certificati di compensazione rilasciati.

Campi CompensationProject: - id: identificativo del progetto - title: nome del progetto - description: descrizione e obiettivi ecologici - imageUrl: immagine di copertina

Campi CompensationCertificate: - id: identificativo del certificato - userId: utente titolare - projectId: progetto associato - amount: importo versato (EUR) - compensatedKg: quantità di CO2 compensata (kg) - downloadUrl: URL per scaricare il documento ufficiale - createdAt: timestamp di rilascio

Diagramma Relazionale (ER Logico)¶

erDiagram
    USER ||--o{ PHYSICAL_ACTIVITY : records
    USER ||--o{ TRAVEL : performs
    USER ||--o{ ENERGY_BILL : uploads
    USER ||--o{ FOOD_RECEIPT : creates
    FOOD_RECEIPT ||--|{ FOOD : contains
    USER ||--o{ GROUP_MEMBERSHIP : joins
    GROUP ||--o{ GROUP_MEMBERSHIP : has_members
    USER ||--o{ GROUP : owns
    GROUP ||--o{ CHALLENGE_INSTANCE : hosts
    USER ||--o{ CHALLENGE_PROGRESS : progresses
    CHALLENGE_INSTANCE ||--o{ CHALLENGE_PROGRESS : tracks
    USER ||--o{ COMPENSATION_CERTIFICATE : receives
    COMPENSATION_PROJECT ||--o{ COMPENSATION_CERTIFICATE : certifies

    USER {
        int id PK
        int role
        string email
        string name
        string lastName
        string avatarImageUrl
        date birthdate
    }

    PHYSICAL_ACTIVITY {
        int id PK
        int userId FK
        int steps
        float kilometers
        date activityDate
    }

    TRAVEL {
        int id PK
        int userId FK
        float distance
        string travelReasonType
        string vehicleType
        float avgSpeed
        int totalTime
        int idleTime
        float drivingScore
        datetime startTime
        datetime endTime
    }

    ENERGY_BILL {
        int id PK
        int userId FK
        float amountConsumed
        string type
        float totalEmission
        date startDate
        date endDate
    }

    FOOD_RECEIPT {
        int id PK
        int userId FK
        string type
        string status
        float cO2Emitted
        int elementsNumber
        date createdAt
    }

    FOOD {
        int id PK
        string ean
        string name
        string category
        float co2KgForProductKg
        string emissionCategory
        float quantity
    }

    GROUP {
        int id PK
        int ownerId FK
        string name
        string description
        string tag
        bool isPrivate
    }

    GROUP_MEMBERSHIP {
        int groupId FK
        int userId FK
        string joinStatus
    }

    CHALLENGE_INSTANCE {
        int id PK
        string timeframe
        int reward
        string category
        string timeframe_type
        bool collected
    }

    CHALLENGE_PROGRESS {
        int challengeId FK
        int userId FK
        float progress
    }

    COMPENSATION_PROJECT {
        int id PK
        string title
        string description
        string imageUrl
    }

    COMPENSATION_CERTIFICATE {
        int id PK
        int userId FK
        int projectId FK
        float amount
        float compensatedKg
        string downloadUrl
        datetime createdAt
    }

Modelli di Aggregazione e Read-Model¶

Oltre alle entità operative sopra riportate, l'app consuma DTO composti ottimizzati per il rendering dei cruscotti:

UserDashboard: include i totali emessi/risparmiati (Stats) e la scomposizione per categoria (weekBreakdown);
RecentActivity: feed paginato delle ultime attività registrate su tutte le categorie;
LeaderBoard: graduatorie e punteggi per utenti e gruppi con filtri temporali.

Modello Dati Logico¶

Panoramica¶

Entità Principali¶

User¶

PhysicalActivity¶

Travel / CreateTravel¶

EnergyBill¶

Food¶

FoodReceipt¶

Group e GroupMembership¶

ChallengeInstance e ChallengeProgress¶

CompensationProject e CompensationCertificate¶