Variabili d'Ambiente e Configurazioni¶

Panoramica della configurazione¶

Nel nostro progetto non utilizziamo un file .env classico (basato ad esempio su librerie come flutter_dotenv, String.fromEnvironment o variabili d'ambiente di sistema).

Abbiamo invece strutturato la configurazione di runtime e build-time distribuendola tra:

flavor Flutter / Android (appFlavor, productFlavors);
file di configurazione Dart (lib/Configuration.dart e lib/configuration/ApiServerConfig.dart);
file di configurazione nativi (AndroidManifest.xml, Info.plist);
configurazioni Firebase (google-services.json, firebase_options_dev.dart, firebase_options_prod.dart);
configurazione di signing Android (android/key.properties).

La tabella seguente riepiloga tutte le variabili e configurazioni necessarie per eseguire e compilare l'applicazione nei vari ambienti.

Tabella di configurazione¶

Nome	Tipo di dato	Descrizione e scopo	Obbligatoria in dev
`appFlavor`	`String` (`prod` \| `dev` \| `local`)	Seleziona l'ambiente applicativo, le opzioni Firebase e l'host API tramite `ApiServerConfig.dart` e `InitializeFirebaseApp.dart`.	Sì
`config.host`	`String`	Host API utilizzato nel flavor `local`; definito in `lib/Configuration.dart` (es. `10.0.2.2:3000` per emulatore Android).	Sì, se si usa `local`
`config.isHttps`	`bool`	Definisce se il client deve comporre le chiamate API in `http://` o `https://` per il flavor `local`.	Sì, se si usa `local`
`DEEP_LINK_HOST`	`String`	Placeholder nel manifest Android per App Links / Universal Links (`api-testing.hapgree.com` per `dev`/`local`, `api.hapgree.com` per `prod`).	Sì
`com.google.android.geo.API_KEY`	`String`	API key Google Maps configurata in `AndroidManifest.xml` e `Info.plist` per il rendering mappe e geolocalizzazione.	Sì
`google-services.json`	`JSON file`	Configurazione Firebase Android per i flavor `dev`, `prod` e `local`.	Sì
`DefaultFirebaseOptions`	`Generated Dart config`	Configurazione Firebase di runtime (`firebase_options_dev.dart` e `firebase_options_prod.dart`). Il flavor `local` riutilizza la configurazione `dev`.	Sì
`keyAlias`	`String`	Alias della chiave del keystore, letto da `android/key.properties` per il signing Android.	Opzionale in debug locale, necessaria per build firmate
`keyPassword`	`String`	Password della chiave del keystore Android.	Opzionale in debug locale, necessaria per build firmate
`storeFile`	`String` path	Percorso del file keystore letto da `android/key.properties`.	Opzionale in debug locale, necessaria per build firmate
`storePassword`	`String`	Password dello store del keystore Android.	Opzionale in debug locale, necessaria per build firmate

Dettaglio implementativo¶

Selezione dell'ambiente API¶

I file coinvolti sono:

lib/configuration/ApiServerConfig.dart
lib/Configuration.dart

La logica di risoluzione degli endpoint è la seguente:

prod -> punta a https://api.hapgree.com (HTTPS attivo)
dev -> punta a https://api-testing.hapgree.com (HTTPS attivo)
local -> utilizza l'istanza config definita in lib/Configuration.dart

Configurazione Firebase¶

I file coinvolti sono:

lib/utils/firebase/InitializeFirebaseApp.dart
lib/firebase_options_dev.dart
lib/firebase_options_prod.dart

Comportamento per flavor:

prod -> inizializza Firebase con le opzioni di produzione (firebase_options_prod.dart)
dev -> inizializza Firebase con le opzioni di sviluppo (firebase_options_dev.dart)
local -> inizializza Firebase riutilizzando le opzioni di sviluppo (firebase_options_dev.dart)

Deep link Android¶

I file coinvolti sono:

android/app/build.gradle
android/app/src/main/AndroidManifest.xml

In ciascun flavor impostiamo la variabile manifestPlaceholders = [DEEP_LINK_HOST: "..."], che viene iniettata nell'intent-filter HTTPS del manifest per gestire l'apertura automatica dell'app dai link web.

Google Maps API Key¶

I file coinvolti sono:

Android: android/app/src/main/AndroidManifest.xml
iOS: ios/Runner/Info.plist

La chiave Google Maps è inserita nei file di configurazione nativi delle rispettive piattaforme.

Configurazioni esterne al client mobile¶

Le seguenti configurazioni non risiedono nel client mobile ma sono gestite centralmente a livello di backend o infrastruttura:

Parametri di connessione al database (host, credenziali, pool);
Segreti e webhook PayPal;
Secret server-side di Firebase;
Configurazione remota / feature flag centralizzati.

Note e punti di attenzione¶

Centralizzazione segreti: Le chiavi e le configurazioni sono attualmente collocate nei file nativi e di configurazione Dart dedicati.
Isolamento flavor local: Il flavor local utilizza API locali ma si appoggia al progetto Firebase di sviluppo (dev).
Restrizioni API Key: La chiave Google Maps nei manifest nativi deve essere opportunamente protetta tramite restrizioni di package name (Android SHA-1) e Bundle ID (iOS) sulla Google Cloud Console.