Vai al contenuto

Setup dell'Ambiente Locale

Obiettivo

Questa guida fornisce i passaggi necessari per configurare ed eseguire l'applicazione mobile HapGree in locale su emulatori o dispositivi fisici.

Prerequisiti

Assicurarsi di avere installato:

  • Git (con supporto ai submodule)
  • Flutter SDK (Dart SDK ^3.5.4 su canale stable)
  • Android Studio con Android SDK e build tools configurati
  • Xcode 15+ e CocoaPods (per sviluppo e test su iOS / macOS)
  • Docker (necessario solo se si intende rigenerare il client Dart da OpenAPI)

Architettura e connessione al Backend

La nostra applicazione mobile non si connette direttamente a un database relazionale.

Per testare l'app con dati dinamici in locale:

  1. Avviare l'istanza del backend HapGree (in locale sulla macchina di sviluppo o puntando all'ambiente di test dev).
  2. Configurare l'host in lib/Configuration.dart.
  3. Eseguire l'app con il flavor desiderato.

Guida rapida al setup

1. Clonare il repository con i submodule

La repository include il submodule per le specifiche OpenAPI:

git clone <repository-url>
cd HapGree
git submodule update --init --recursive

Perché è necessario il submodule?
La cartella Specs/OpenApi/OpenApi contiene la specifica OpenAPI da cui è generato il client Dart hapgree_client (libs/hapgree-client).

2. Configurare i file locali di sviluppo

lib/Configuration.dart

Questo file definisce i parametri di rete utilizzati dal flavor local.

Creare o modificare lib/Configuration.dart con la seguente configurazione di base:

import 'configuration/ApiServerConfig.dart';

ApiServerConfig config = ApiServerConfig(
  host: "10.0.2.2:3000",
  isHttps: false,
);

Note sull'host: - 10.0.2.2 è l'alias standard per raggiungere il localhost della macchina host da emulatore Android. - Se si utilizza un dispositivo fisico o un simulatore iOS, sostituire con l'indirizzo IP locale della macchina (es. 192.168.1.X:3000) o localhost:3000.

android/key.properties

Il file android/app/build.gradle legge questo file per la firma dei build Android.

Per eseguire in modalità debug è possibile utilizzare un keystore locale di sviluppo. La struttura attesa del file android/key.properties è:

keyAlias=<nome_alias>
keyPassword=<password_chiave>
storeFile=<percorso_file_keystore>
storePassword=<password_keystore>

3. Installare le dipendenze

Dalla root del progetto eseguire:

flutter pub get

Per l'ambiente iOS:

cd ios
pod install
cd ..

4. Verifica dell'ambiente

Verificare che la toolchain Flutter sia correttamente configurata:

flutter doctor -v

Esecuzione dell'applicazione per Flavor

Android - Flavor local

Esegue l'app puntando all'host locale definito in lib/Configuration.dart e ai servizi Firebase di sviluppo:

flutter run --flavor local -t lib/main.dart

Android - Flavor dev

Esegue l'app puntando all'ambiente di collaudo (https://api-testing.hapgree.com):

flutter run --flavor dev -t lib/main.dart

Android - Flavor prod

Esegue l'app puntando all'ambiente di produzione (https://api.hapgree.com):

flutter run --flavor prod -t lib/main.dart

iOS

Per eseguire l'app su iOS:

  1. Aprire il workspace: open ios/Runner.xcworkspace
  2. Selezionare lo scheme desiderato (dev o prod)
  3. Avviare il build da Xcode oppure tramite Flutter: 
    flutter run --flavor dev -t lib/main.dart

Servizi e prerequisiti per il test end-to-end

Per eseguire e testare tutti i flussi applicativi:

  • Backend HapGree raggiungibile;
  • Progetto Firebase configurato e raggiungibile;
  • Google Maps API Key attiva;
  • Health Connect (Android) o Apple Health (iOS) con permessi abilitati per i flussi fitness;
  • Configurazione sandbox PayPal attiva lato backend per i flussi di compensazione.

Rigenerazione del Client API

Se le specifiche OpenAPI in Specs/OpenApi/OpenApi vengono aggiornate, possiamo rigenerare il package libs/hapgree-client:

  • Windows: 
    Scripts\DartCodeGeneration\RunDartCodegen.bat
  • macOS / Linux: 
    ./Scripts/DartCodeGeneration/RunDartCodegen.sh

Risoluzione problemi frequenti (Troubleshooting)

Impossibile raggiungere il backend in locale

  • Verificare che il backend sia attivo e in ascolto sulla porta indicata.
  • Controllare lib/Configuration.dart: su emulatore Android usare 10.0.2.2, su simulatore iOS localhost, su device reale l'IP locale.
  • Verificare che isHttps sia impostato su false se il backend locale non usa certificati SSL.

Errore di signing in Android build

  • Verificare la presenza e i percorsi del keystore all'interno di android/key.properties.

I dati di passi / distanza non compaiono

  • Assicurarsi di aver concesso i permessi per ACTIVITY_RECOGNITION e Health Connect su Android, o i permessi Motion/Health su iOS.
  • Verificare che l'app Health Connect / Apple Health contenga dati registrati per la giornata odierna.

Il tracking automatico non registra sessioni

  • Verificare che i permessi di localizzazione siano impostati su "Consenti sempre" (background location).
  • Controllare che le notifiche siano abilitate (necessarie per il foreground service Android).
  • Ispezionare la chiave driving_history in SharedPreferences per verificare le sessioni bufferizzate in attesa di sincronizzazione.

Criteri di verifica del setup locale

Il setup locale è completato correttamente quando:

  1. L'applicazione compila e si avvia su emulatore o dispositivo;
  2. Il login e il caricamento della dashboard avvengono con successo;
  3. I flussi principali di categoria (mobilità, cibo, energia) caricano i dati dal backend senza errori di bootstrap.