Compare commits
1
Commits
main
..
7c6cf6fd78
| Author | SHA1 | Date | |
|---|---|---|---|
  davideandClaude Sonnet 5
|
7c6cf6fd78 |
No files matched your search
@@ -47,7 +47,6 @@ bash docker/build.sh --release # release → dist/biteplan-release.
|
||||
- **Emulatore**: Android SDK in `/home/davide/android-sdk`; accelerazione hardware via `/dev/kvm` (WSL2 con KVM abilitato).
|
||||
- **AVD `biteplan`**: dedicato a questo progetto (Pixel 6, Android 14, google_apis/x86_64). Non riutilizzare AVD di altri progetti (es. `palladium_wallet`).
|
||||
- **Permessi**: le build Docker girano come root nel volume montato — se `.dart_tool/` o `build/` risultano di proprietà root, serve `sudo chown -R davide:davide .dart_tool build` prima di usare flutter da host.
|
||||
- **Setup e uso dell'emulatore Android** (installazione SDK, creazione AVD, comandi `adb`, troubleshooting): [docs/emulatore.md](docs/emulatore.md).
|
||||
|
||||
## Build e firma
|
||||
|
||||
@@ -56,7 +55,6 @@ bash docker/build.sh --release # release → dist/biteplan-release.
|
||||
- **Keystore**: `docker/biteplan.jks` è in `.gitignore`; da ottenere dall'autore o generare con `keytool`. Password via `BITEPLAN_KEYSTORE_PASS` (mai hardcoded); alias: `biteplan`
|
||||
- **applicationId**: `com.davide.biteplan` — non cambiare, garantisce aggiornamento diretto dalla v1.2.1
|
||||
- **versionCode**: letto da `pubspec.yaml` (`version: X.Y.Z+BUILD`); BUILD deve essere sempre crescente
|
||||
- **kAppVersion**: `lib/core/constants/app_constants.dart` duplica la versione di `pubspec.yaml` a mano (nessuna sincronizzazione automatica) — aggiornarla ad ogni bump di versione, altrimenti l'update checker confronta contro il valore sbagliato
|
||||
|
||||
## Architettura
|
||||
|
||||
@@ -66,7 +64,6 @@ Feature-first sotto `lib/features/` (meal_planner, converter, shopping_list, gui
|
||||
lib/
|
||||
├── app.dart # MaterialApp + NavigationBar; in initState chiama UpdateService.checkUpdate() e mostra showUpdateDialog()
|
||||
├── core/constants/app_constants.dart # kDayIds, kMealSlots, kStorageKey*, kAppVersion
|
||||
├── core/theme/app_theme.dart # ThemeData Material 3, seed color 0xFF2d6a4f
|
||||
├── shared/
|
||||
│ ├── services/storage_service.dart # wrapper SharedPreferences (load/save)
|
||||
│ ├── services/update_service.dart # checkUpdate() → GitHub API; isNewer(), parseTagName() (@visibleForTesting)
|
||||
@@ -89,7 +86,7 @@ lib/
|
||||
|
||||
## Testing
|
||||
|
||||
184 test unit + widget in `test/` (rispecchia la struttura di `lib/`), più un integration test in `integration_test/app_test.dart`. I test unit/widget non richiedono device. Coverage ~93% su `lib/` (esclusi per scelta: `main.dart`, il percorso camera di `qr_scan_page`). Dettaglio di cosa è coperto/escluso e come lanciare la suite: [docs/testing.md](docs/testing.md).
|
||||
184 test unit + widget in `test/` (rispecchia la struttura di `lib/`), più un integration test in `integration_test/app_test.dart`. I test unit/widget non richiedono device. Coverage ~93% su `lib/` (esclusi per scelta: `main.dart`, il percorso camera di `qr_scan_page`).
|
||||
|
||||
- Storage isolato con `SharedPreferences.setMockInitialValues({})`
|
||||
- Widget test: estensione `pumpApp` in `test/helpers/pump_app.dart`
|
||||
|
||||
@@ -2,29 +2,9 @@
|
||||
|
||||
App Android per la gestione della dieta quotidiana — pianificazione pasti, conversione crudo/cotto e lista della spesa.
|
||||
|
||||
> Un'unica app per pianificare la settimana, sapere quanto pesare crudo o cotto e non dimenticare cosa comprare.
|
||||
## Funzionalità
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Overview
|
||||
|
||||
BitePlan nasce per unire in un'unica app tre attività che di solito richiedono strumenti
|
||||
separati: pianificare i pasti della settimana, convertire i pesi degli alimenti tra crudo e
|
||||
cotto (utile per chi segue una dieta con quantità espresse in una delle due forme), e tenere
|
||||
una lista della spesa sincronizzata con quanto pianificato.
|
||||
|
||||
- **Problema risolto**: evitare di ricalcolare a mano le rese di cottura e di dimenticare
|
||||
ingredienti quando si fa la spesa.
|
||||
- **Perché esiste**: progetto personale dell'autore, pensato per un uso quotidiano reale.
|
||||
- **Limiti noti**: i coefficienti di resa sono medie indicative (vedi
|
||||
[docs/conversioni.md](docs/conversioni.md)); il piano pasti si condivide tra dispositivi
|
||||
solo via QR code, senza account né sincronizzazione cloud; nessuna build iOS.
|
||||
|
||||
## Features
|
||||
|
||||
### Piano pasti
|
||||
### Piano Pasti
|
||||
- Pianificazione settimanale su 7 giorni × 3 pasti (colazione, pranzo, cena)
|
||||
- Card accordion per giorno, giorno corrente aperto di default
|
||||
- Aggiunta e rimozione di voci per ogni pasto
|
||||
@@ -48,32 +28,7 @@ una lista della spesa sincronizzata con quanto pianificato.
|
||||
- All'avvio controlla silenziosamente l'ultima release su GitHub
|
||||
- Se disponibile una versione più recente, mostra un dialog con link diretto al download dell'APK
|
||||
|
||||
## Architecture
|
||||
|
||||
Feature-first sotto `lib/features/`, ognuna con modelli, provider (state management) e
|
||||
presentation; persistenza su `SharedPreferences`. Dettaglio del flusso dati per feature in
|
||||
[docs/architettura.md](docs/architettura.md).
|
||||
|
||||
```text
|
||||
biteplan/
|
||||
├── lib/
|
||||
│ ├── app.dart # MaterialApp + navigazione
|
||||
│ ├── core/ # costanti, tema
|
||||
│ ├── shared/ # servizi e widget condivisi
|
||||
│ └── features/
|
||||
│ ├── meal_planner/
|
||||
│ ├── converter/
|
||||
│ ├── shopping_list/
|
||||
│ └── guide/
|
||||
├── assets/data/conversions.json
|
||||
├── android/ # progetto nativo (MethodChannel in Kotlin)
|
||||
├── test/ # unit + widget test
|
||||
├── integration_test/
|
||||
├── docs/ # guida utente, architettura, fonti conversioni
|
||||
└── docker/ # build APK headless, test riproducibili
|
||||
```
|
||||
|
||||
## Requisiti e dipendenze
|
||||
## Stack
|
||||
|
||||
| Livello | Tecnologia |
|
||||
|---|---|
|
||||
@@ -83,7 +38,14 @@ biteplan/
|
||||
| QR code | qr_flutter + mobile_scanner |
|
||||
| Build APK | Docker (headless) |
|
||||
|
||||
Requisiti host per lo sviluppo:
|
||||
## Guida rapida
|
||||
|
||||
1. **Prima volta**: segui [Requisiti host](#requisiti-host) e [Installazione passo passo](#installazione-passo-passo) per installare Flutter, Android SDK ed emulatore.
|
||||
2. **Sviluppo quotidiano**: vedi [Sviluppo](#sviluppo) per avviare l'emulatore e lanciare l'app con hot reload.
|
||||
3. **Build APK**: vedi [Build APK](#build-apk) per generare `dist/biteplan-debug.apk` o `-release.apk` via Docker.
|
||||
4. **Provare l'APK buildato sull'emulatore** (senza `flutter run`): vedi [Installare e testare l'APK di debug sull'emulatore](#installare-e-testare-lapk-di-debug-sullemulatore).
|
||||
|
||||
## Requisiti host
|
||||
|
||||
- **Linux x86_64** (Ubuntu/Debian o simili; funziona anche su **WSL2** se il kernel espone `/dev/kvm`)
|
||||
- **KVM** per l'accelerazione hardware — senza, l'emulatore è inutilizzabile. Verifica con:
|
||||
@@ -95,7 +57,7 @@ Requisiti host per lo sviluppo:
|
||||
- **Java 17+** (`sudo apt install openjdk-21-jdk`)
|
||||
- Strumenti di base: `git curl unzip` — e ~15 GB di spazio libero
|
||||
|
||||
## Installazione
|
||||
### Installazione passo passo
|
||||
|
||||
**1. Flutter** (versione pinnata `3.41.9`, la stessa di `.flutter-version`):
|
||||
|
||||
@@ -149,94 +111,129 @@ flutter run
|
||||
> **Nota WSL2**: serve un kernel con KVM abilitato (WSL2 recenti lo hanno di serie —
|
||||
> verifica con `ls /dev/kvm`). La finestra dell'emulatore compare tramite WSLg.
|
||||
|
||||
## Utilizzo
|
||||
## Sviluppo
|
||||
|
||||
Una volta completata l'installazione, il ciclo quotidiano è:
|
||||
|
||||
```bash
|
||||
emulator -avd biteplan &
|
||||
# attendi il boot completo (qualche secondo se l'AVD ha già uno snapshot, 1-2 min altrimenti), poi:
|
||||
flutter run
|
||||
# hot reload con "r", hot restart con "R"
|
||||
# hot reload con "r", hot restart con "R", "q" per terminare
|
||||
```
|
||||
|
||||
Per l'uso dell'app una volta installata, vedi la [guida utente](docs/guida-utente.md).
|
||||
Lancialo da un terminale interattivo (non in background): `r`/`R` leggono da stdin, quindi
|
||||
un processo lanciato senza terminale (es. `nohup ... &`) non risponde all'hot reload.
|
||||
|
||||
### Installare e testare un APK già buildato
|
||||
> **Permessi dopo una build Docker**: `bash docker/build.sh` (vedi [Build APK](#build-apk))
|
||||
> gira come root nel volume montato. Se dopo una build `flutter run` fallisce con errori di
|
||||
> permessi (es. su `android/local.properties`) o Gradle si lamenta di file in `/root/.pub-cache`,
|
||||
> i file sono rimasti di proprietà di root:
|
||||
> ```bash
|
||||
> sudo chown -R $(whoami):$(whoami) android .dart_tool build
|
||||
> rm -rf .dart_tool build && flutter pub get
|
||||
> ```
|
||||
|
||||
Vedi [docker/README.md](docker/README.md) per test e build APK via Docker.
|
||||
|
||||
## Build APK
|
||||
|
||||
```bash
|
||||
bash docker/build.sh # debug → dist/biteplan-debug.apk
|
||||
bash docker/build.sh --release # release → dist/biteplan-release.apk
|
||||
```
|
||||
|
||||
Vedi [docker/README.md](docker/README.md) per i requisiti della firma release.
|
||||
|
||||
## Installare e testare l'APK di debug sull'emulatore
|
||||
|
||||
Una volta creato l'AVD `biteplan` (vedi sopra), per installare e provare un APK di debug
|
||||
già buildato (es. `dist/biteplan-debug.apk` generato da `bash docker/build.sh`) senza
|
||||
passare da `flutter run`:
|
||||
|
||||
**1. Avvia l'emulatore e attendi il boot completo:**
|
||||
|
||||
```bash
|
||||
emulator -avd biteplan &
|
||||
adb wait-for-device
|
||||
# poi attendi che il boot sia terminato (può richiedere 1-2 min al primo avvio):
|
||||
adb shell 'while [ "$(getprop sys.boot_completed)" != "1" ]; do sleep 1; done'
|
||||
```
|
||||
|
||||
**2. Installa l'APK:**
|
||||
|
||||
```bash
|
||||
adb install -r dist/biteplan-debug.apk # -r = reinstalla sovrascrivendo se già presente
|
||||
```
|
||||
|
||||
**3. Avvia l'app:**
|
||||
|
||||
```bash
|
||||
adb shell monkey -p com.davide.biteplan -c android.intent.category.LAUNCHER 1
|
||||
```
|
||||
|
||||
# log in tempo reale
|
||||
**4. Osserva i log in tempo reale (utile per debug):**
|
||||
|
||||
```bash
|
||||
adb logcat --pid=$(adb shell pidof -s com.davide.biteplan)
|
||||
```
|
||||
|
||||
# disinstalla quando hai finito
|
||||
**5. Disinstalla quando hai finito:**
|
||||
|
||||
```bash
|
||||
adb uninstall com.davide.biteplan
|
||||
```
|
||||
|
||||
> Per lo sviluppo iterativo (hot reload) usa `flutter run` — questa procedura serve a
|
||||
> validare l'APK esatto che verrà distribuito.
|
||||
> Per lo sviluppo iterativo (hot reload) usa invece `flutter run` — questa procedura serve
|
||||
> a validare l'APK esatto che verrà distribuito.
|
||||
|
||||
## Test
|
||||
|
||||
Cosa è coperto, cosa no e insidie note: [docs/testing.md](docs/testing.md).
|
||||
La suite copre unit test e widget test. Richiede l'immagine Docker `biteplan-build`
|
||||
(creata automaticamente al primo `bash docker/build.sh`).
|
||||
|
||||
```bash
|
||||
flutter test # tutta la suite (host)
|
||||
flutter test test/features/meal_planner/qr_test.dart # singolo file
|
||||
|
||||
# versione riproducibile via Docker (immagine biteplan-build, creata al primo bash docker/build.sh)
|
||||
# Tutti i test (dalla root del progetto)
|
||||
docker run --rm -v "$(pwd):/workspace" -w /workspace biteplan-build \
|
||||
bash -c "flutter pub get --enforce-lockfile && flutter test"
|
||||
bash -c "flutter pub get && flutter test"
|
||||
|
||||
# Un singolo file
|
||||
docker run --rm -v "$(pwd):/workspace" -w /workspace biteplan-build \
|
||||
bash -c "flutter test test/features/meal_planner/qr_test.dart"
|
||||
```
|
||||
|
||||
Struttura di `test/` (rispecchia `lib/`):
|
||||
### Struttura
|
||||
|
||||
```text
|
||||
```
|
||||
test/
|
||||
├── helpers/pump_app.dart # estensione pumpApp per widget test
|
||||
├── helpers/
|
||||
│ └── pump_app.dart # estensione pumpApp per widget test
|
||||
├── features/
|
||||
│ ├── converter/{models,providers}/
|
||||
│ ├── meal_planner/{models,providers,widgets}/ + qr_test.dart
|
||||
│ └── shopping_list/{models,providers,widgets}/
|
||||
└── shared/{services,widgets}/
|
||||
│ ├── converter/
|
||||
│ │ ├── models/conversion_entry_test.dart
|
||||
│ │ └── providers/converter_provider_test.dart
|
||||
│ ├── meal_planner/
|
||||
│ │ ├── models/meal_plan_test.dart
|
||||
│ │ ├── providers/meal_planner_provider_test.dart
|
||||
│ │ ├── widgets/meal_card_test.dart
|
||||
│ │ └── qr_test.dart
|
||||
│ └── shopping_list/
|
||||
│ ├── models/shopping_item_test.dart
|
||||
│ ├── providers/shopping_list_provider_test.dart
|
||||
│ └── widgets/shopping_item_tile_test.dart
|
||||
└── shared/
|
||||
├── services/
|
||||
│ └── update_service_test.dart # parsing versione e confronto semver
|
||||
└── widgets/
|
||||
└── update_dialog_test.dart # widget test dialog aggiornamento
|
||||
```
|
||||
|
||||
## Build APK
|
||||
|
||||
```bash
|
||||
bash docker/build.sh # debug → dist/biteplan-debug.apk
|
||||
export BITEPLAN_KEYSTORE_PASS=password # richiesto solo per --release
|
||||
bash docker/build.sh --release # release → dist/biteplan-release.apk
|
||||
```
|
||||
|
||||
Vedi [docker/README.md](docker/README.md) per i requisiti della firma release (keystore).
|
||||
|
||||
## Contribuire
|
||||
|
||||
Progetto personale mantenuto da un singolo autore, senza processo di contribuzione formale.
|
||||
Segnalazioni di bug e proposte sono benvenute via [Issues](https://github.com/davide3011/biteplan/issues);
|
||||
per modifiche più ampie apri prima una issue di discussione prima di lavorare a una PR.
|
||||
|
||||
## Documentazione
|
||||
|
||||
- [Guida utente](docs/guida-utente.md)
|
||||
- [Architettura](docs/architettura.md)
|
||||
- [Fonti e documentazione conversioni](docs/conversioni.md)
|
||||
- [Emulatore Android — installazione e uso](docs/emulatore.md)
|
||||
- [Test — cosa è coperto e come lanciarli](docs/testing.md)
|
||||
- [Changelog](CHANGELOG.md)
|
||||
|
||||
## Stato e licenza
|
||||
## Licenza
|
||||
|
||||
Versione corrente: vedi [pubspec.yaml](pubspec.yaml) e [CHANGELOG.md](CHANGELOG.md).
|
||||
Distribuito come APK firmato tramite le [release GitHub](https://github.com/davide3011/biteplan/releases);
|
||||
l'app verifica automaticamente la disponibilità di aggiornamenti all'avvio.
|
||||
|
||||
Rilasciato sotto licenza [EUPL v1.2](LICENSE) — Davide Grilli.
|
||||
[EUPL v1.2](LICENSE) — Davide Grilli
|
||||
@@ -1,83 +0,0 @@
|
||||
# Architettura — BitePlan
|
||||
|
||||
Documento tecnico per chi sviluppa o mantiene l'app: come sono strutturati i dati e come
|
||||
scorrono tra UI, provider e persistenza. Per l'elenco file per file vedi [CLAUDE.md](../CLAUDE.md);
|
||||
per l'uso dell'app vedi [guida-utente.md](guida-utente.md).
|
||||
|
||||
## Pattern generale
|
||||
|
||||
Ogni feature (`meal_planner`, `converter`, `shopping_list`) segue lo stesso schema:
|
||||
|
||||
```
|
||||
Widget (presentation/) → Provider (ChangeNotifier) → StorageService / asset → SharedPreferences
|
||||
↑____________________________notifyListeners()____________________________|
|
||||
```
|
||||
|
||||
Ogni provider espone metodi che mutano lo stato immutabile in memoria, chiamano
|
||||
`notifyListeners()` e poi salvano in modo fire-and-forget (senza `await`, l'UI non aspetta
|
||||
la scrittura su disco). `load()` va chiamato una volta all'avvio (in `main.dart`) prima di
|
||||
usare il provider.
|
||||
|
||||
## Piano pasti (`meal_planner`)
|
||||
|
||||
- **Modello**: `MealPlan` è una mappa `dayId → DayPlan`; `DayPlan` ha tre liste di stringhe
|
||||
(`colazione`, `pranzo`, `cena`). Entrambi sono immutabili: ogni modifica passa da
|
||||
`copyWith`/`withUpdatedDay` e ricostruisce l'oggetto.
|
||||
- **Provider**: `MealPlannerProvider` tiene `_plan` in memoria, la inizializza vuota con
|
||||
`MealPlan.empty(kDayIds)`, la carica da `StorageService` (chiave `meals`, JSON via
|
||||
`toJsonString`/`fromJsonString`). Se il JSON salvato è corrotto, torna a un piano vuoto
|
||||
invece di lanciare un'eccezione.
|
||||
- **Condivisione QR** (`qr_codec.dart`): `buildQrPayload` serializza il piano come
|
||||
`{ "v": 1, "meals": {...} }` e restituisce `null` se supera 2953 byte (capienza QR con error
|
||||
correction L) — la UI mostra un errore in quel caso. `parseMealPlanFromQr` valida
|
||||
struttura e versione prima di ricostruire il `MealPlan`, per non far crashare l'app su un
|
||||
QR malformato o generato da una versione futura.
|
||||
- **Generazione lista spesa**: la pagina piano pasti legge `plan.allItems` e chiama
|
||||
`ShoppingListProvider.addAll(...)` — l'aggregazione duplicati avviene lì, non nel meal
|
||||
planner.
|
||||
|
||||
## Convertitore crudo/cotto (`converter`)
|
||||
|
||||
- **Dati**: `assets/data/conversions.json` è una mappa `alimento → metodo → { yield }`,
|
||||
caricata una sola volta in `ConverterProvider.loadDb()` e appiattita in una lista di
|
||||
`ConversionEntry { food, method, yieldFactor }`.
|
||||
- **Calcolo**: `rawToCooked = raw * yieldFactor`, `cookedToRaw = cooked / yieldFactor`.
|
||||
Il provider arrotonda il risultato a un decimale (`(v * 10).roundToDouble() / 10`).
|
||||
- **Ricerca**: `search(query)` filtra `_db` per sottostringa case-insensitive sul nome
|
||||
alimento; non c'è persistenza, lo stato (`selected`, `grams`, `rawToCooked`) vive solo in
|
||||
memoria e si azzera con `reset()`.
|
||||
- I coefficienti e le fonti sono documentati in [conversioni.md](conversioni.md) — per
|
||||
aggiungerne di nuovi si modifica solo il JSON, non serve toccare il provider.
|
||||
|
||||
## Lista della spesa (`shopping_list`)
|
||||
|
||||
- **Modello**: `ShoppingItem { id, name, checked, quantity }`. `id` è generato come
|
||||
`timestamp_contatore` (non un vero UUID) per garantire unicità anche ad aggiunte multiple
|
||||
nello stesso millisecondo.
|
||||
- **Provider**: `ShoppingListProvider` persiste su chiave `shopping_list` come lista JSON.
|
||||
`pendingItems`/`checkedItems` sono getter derivati, non stato separato.
|
||||
- **`addAll(names)`**: raggruppa i nomi per confronto case-insensitive, somma le occorrenze
|
||||
in `quantity` e salta quelli già presenti nella lista (case-insensitive anche lì) — è il
|
||||
meccanismo dietro "zucchine (x2)" e dietro il "senza duplicati" della generazione lista
|
||||
dal piano pasti.
|
||||
|
||||
## Controllo aggiornamenti
|
||||
|
||||
`UpdateService.checkUpdate()` (chiamato da `app.dart` in `initState`) interroga
|
||||
`GET /repos/davide3011/biteplan/releases/latest` su GitHub con `dart:io HttpClient`
|
||||
(nessun package HTTP aggiuntivo), timeout 5s su connessione e risposta. Confronta il
|
||||
`tag_name` (spogliato del prefisso `v`) con `kAppVersion` via confronto semver a tre
|
||||
componenti (`isNewer`); qualsiasi errore di rete, parsing o timeout fa fallire silenziosamente
|
||||
il controllo (ritorna `null`, nessun dialog). Disabilitato su web (`kIsWeb`).
|
||||
|
||||
`kAppVersion` in `app_constants.dart` **non** è sincronizzato automaticamente con
|
||||
`pubspec.yaml` — va aggiornato a mano ad ogni release, altrimenti il confronto versione è
|
||||
sbagliato.
|
||||
|
||||
## MethodChannel nativo
|
||||
|
||||
Il bottone "Scarica" del dialog di aggiornamento e altri link esterni passano da
|
||||
`UrlLauncherService`, che invoca il canale nativo `com.davide.biteplan/launcher`
|
||||
implementato in Kotlin (`android/app/src/main/kotlin/com/davide/biteplan/MainActivity.kt`)
|
||||
con un `Intent.ACTION_VIEW` — scelta per evitare di aggiungere il package `url_launcher`
|
||||
per un solo caso d'uso.
|
||||
@@ -1,121 +0,0 @@
|
||||
# Emulatore Android — installazione e uso (Ubuntu)
|
||||
|
||||
Guida per chi sviluppa BitePlan su Ubuntu (nativo o WSL2) e deve installare ed usare
|
||||
l'emulatore Android in locale. Per i requisiti generali del progetto vedi [README](../README.md);
|
||||
per la build via Docker vedi [CLAUDE.md](../CLAUDE.md).
|
||||
|
||||
## 1. Prerequisiti
|
||||
|
||||
- **KVM** per l'accelerazione hardware: senza, l'emulatore è troppo lento per essere usabile.
|
||||
|
||||
```bash
|
||||
ls /dev/kvm # deve esistere
|
||||
groups | grep kvm # il tuo utente deve essere nel gruppo kvm
|
||||
```
|
||||
|
||||
Se il gruppo manca:
|
||||
|
||||
```bash
|
||||
sudo usermod -aG kvm $USER
|
||||
# poi rilogin (o riavvia la sessione) perché il gruppo sia effettivo
|
||||
```
|
||||
|
||||
Su **WSL2** serve un kernel con KVM abilitato (le versioni recenti lo hanno di serie).
|
||||
La finestra dell'emulatore compare tramite WSLg.
|
||||
|
||||
- **Java 17+**: `sudo apt install openjdk-21-jdk`
|
||||
- Strumenti di base: `git curl unzip`, e ~15 GB di spazio libero per SDK + system image.
|
||||
|
||||
## 2. Installare Android SDK command-line tools
|
||||
|
||||
```bash
|
||||
mkdir -p ~/android-sdk/cmdline-tools
|
||||
cd ~/android-sdk/cmdline-tools
|
||||
curl -O https://dl.google.com/android/repository/commandlinetools-linux-11076708_latest.zip
|
||||
unzip commandlinetools-linux-11076708_latest.zip && mv cmdline-tools latest
|
||||
rm commandlinetools-linux-11076708_latest.zip
|
||||
|
||||
cat >> ~/.bashrc <<'EOF'
|
||||
export ANDROID_HOME="$HOME/android-sdk"
|
||||
export PATH="$ANDROID_HOME/cmdline-tools/latest/bin:$ANDROID_HOME/platform-tools:$ANDROID_HOME/emulator:$PATH"
|
||||
EOF
|
||||
source ~/.bashrc
|
||||
```
|
||||
|
||||
## 3. Installare i pacchetti SDK e accettare le licenze
|
||||
|
||||
```bash
|
||||
sdkmanager "platform-tools" "emulator" \
|
||||
"platforms;android-34" "build-tools;34.0.0" \
|
||||
"system-images;android-34;google_apis;x86_64"
|
||||
yes | sdkmanager --licenses
|
||||
```
|
||||
|
||||
## 4. Creare l'AVD `biteplan`
|
||||
|
||||
Il progetto usa un AVD dedicato (Pixel 6, Android 14, `google_apis`/x86_64) — non riusare
|
||||
AVD di altri progetti.
|
||||
|
||||
```bash
|
||||
echo "no" | avdmanager create avd -n biteplan \
|
||||
-k "system-images;android-34;google_apis;x86_64" -d pixel_6
|
||||
```
|
||||
|
||||
Verifica che tutto sia a posto con `flutter doctor` (la voce "Android toolchain" deve
|
||||
risultare ✓).
|
||||
|
||||
## 5. Avviare l'emulatore
|
||||
|
||||
```bash
|
||||
emulator -avd biteplan &
|
||||
```
|
||||
|
||||
Il primo boot richiede 1-2 minuti; quelli successivi sono più veloci grazie allo snapshot
|
||||
automatico dello stato. Per lo sviluppo con hot reload, dalla root del progetto:
|
||||
|
||||
```bash
|
||||
flutter run # r = hot reload, R = hot restart
|
||||
```
|
||||
|
||||
### Opzioni utili
|
||||
|
||||
```bash
|
||||
emulator -list-avds # elenca gli AVD disponibili
|
||||
emulator -avd biteplan -no-snapshot-load # forza un cold boot (ignora lo stato salvato)
|
||||
emulator -avd biteplan -wipe-data # resetta l'AVD allo stato di fabbrica
|
||||
```
|
||||
|
||||
## 6. Comandi `adb` quotidiani
|
||||
|
||||
```bash
|
||||
adb devices # emulatori/device collegati
|
||||
adb wait-for-device # attende che l'emulatore sia raggiungibile
|
||||
adb shell 'while [ "$(getprop sys.boot_completed)" != "1" ]; do sleep 1; done' # attende il boot completo
|
||||
|
||||
adb install -r dist/biteplan-debug.apk # installa/reinstalla un APK già buildato
|
||||
adb shell monkey -p com.davide.biteplan -c android.intent.category.LAUNCHER 1 # avvia l'app
|
||||
|
||||
adb logcat --pid=$(adb shell pidof -s com.davide.biteplan) # log in tempo reale dell'app
|
||||
|
||||
adb uninstall com.davide.biteplan # disinstalla
|
||||
```
|
||||
|
||||
> Per lo sviluppo iterativo usa `flutter run` (hot reload); la sequenza `adb install` sopra
|
||||
> serve a validare l'APK esatto che verrà distribuito, senza passare da `flutter run`.
|
||||
|
||||
## 7. Chiudere l'emulatore
|
||||
|
||||
```bash
|
||||
adb -s emulator-5554 emu kill # spegnimento pulito (salva lo snapshot)
|
||||
# oppure chiudi la finestra dell'emulatore
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Sintomo | Causa probabile | Soluzione |
|
||||
|---|---|---|
|
||||
| `emulator: ERROR: x86_64 emulation currently requires hardware acceleration` | KVM non accessibile | Verifica `/dev/kvm` e l'appartenenza al gruppo `kvm` (§1) |
|
||||
| Emulatore lentissimo, UI a scatti | KVM non attivo, o system image ARM su host x86_64 | Usa una system image `x86_64` come da §3, verifica KVM |
|
||||
| Boot bloccato su logo Android per minuti | Cold boot dopo `-wipe-data`, oppure macchina sotto carico | Attendi, è normale al primo avvio; se persiste prova `-no-snapshot-load` |
|
||||
| Finestra emulatore non compare su WSL2 | WSLg non attivo o kernel senza supporto grafico | Aggiorna WSL (`wsl --update`), verifica `echo $DISPLAY` |
|
||||
| `adb: no devices/emulators found` | Emulatore non ancora avviato o non ancora bootato | `adb wait-for-device`, poi ricontrolla con `adb devices` |
|
||||
@@ -1,78 +0,0 @@
|
||||
# Test — BitePlan
|
||||
|
||||
Cosa copre la suite di test, cosa no, e come lanciarla. Per l'architettura del codice
|
||||
testato vedi [architettura.md](architettura.md).
|
||||
|
||||
## Come lanciare i test
|
||||
|
||||
```bash
|
||||
flutter test # tutta la suite unit + widget (host)
|
||||
flutter test test/features/meal_planner/qr_test.dart # singolo file
|
||||
|
||||
# versione riproducibile via Docker (immagine biteplan-build, creata da bash docker/build.sh)
|
||||
docker run --rm -v "$(pwd):/workspace" -w /workspace biteplan-build \
|
||||
bash -c "flutter pub get --enforce-lockfile && flutter test"
|
||||
|
||||
# integration test — richiede un emulatore avviato (vedi docs/emulatore.md)
|
||||
flutter test integration_test/app_test.dart
|
||||
```
|
||||
|
||||
## Struttura
|
||||
|
||||
```text
|
||||
test/
|
||||
├── coverage_helper_test.dart # importa tutta lib/ perché lcov copra anche i file non testati
|
||||
├── helpers/pump_app.dart # estensione pumpApp per i widget test
|
||||
├── features/
|
||||
│ ├── converter/{models,pages,providers}/
|
||||
│ ├── meal_planner/{models,pages,providers,widgets}/ + qr_test.dart
|
||||
│ ├── shopping_list/{models,pages,providers,widgets}/
|
||||
│ └── guide/{pages,widgets}/
|
||||
└── shared/{services,widgets}/
|
||||
```
|
||||
|
||||
184 test unit + widget, coverage ~93% su `lib/`, più `integration_test/app_test.dart`
|
||||
(navigazione tra tab, flussi end-to-end su un emulatore/device reale).
|
||||
|
||||
## Cosa è coperto
|
||||
|
||||
- **Modelli**: serializzazione/deserializzazione, `copyWith`, edge case (`MealPlan`,
|
||||
`DayPlan`, `ConversionEntry`, `ShoppingItem`).
|
||||
- **Provider**: mutazioni di stato, persistenza (fire-and-forget) tramite
|
||||
`StorageService` con `SharedPreferences.setMockInitialValues({})` isolato per test.
|
||||
- **Conversione crudo/cotto**: `rawToCooked`/`cookedToRaw` in `ConversionEntry`.
|
||||
- **QR**: `buildQrPayload`/`parseMealPlanFromQr` in `qr_codec.dart` (payload valido,
|
||||
troppo grande, malformato).
|
||||
- **Update checker**: `isNewer()`, `parseTagName()` (`@visibleForTesting`), dialog di
|
||||
aggiornamento con `MethodChannel` mockato.
|
||||
- **Widget/pagine**: rendering, interazioni utente (tap, form) via `pumpApp`, per tutte
|
||||
le feature (meal_planner, converter, shopping_list, guide).
|
||||
- **Integration test**: navigazione fra i tab e flussi che attraversano più feature,
|
||||
su un device/emulatore reale (non richiesto per lo sviluppo quotidiano).
|
||||
|
||||
## Cosa NON è coperto (per scelta)
|
||||
|
||||
- **`main.dart`**: bootstrap dell'app (setup provider, `runApp`), poco valore nel
|
||||
testarlo isolatamente — è coperto indirettamente dall'integration test.
|
||||
- **Percorso camera di `qr_scan_page`**: l'uso reale della fotocamera per scansionare un
|
||||
QR richiede hardware/permessi non simulabili in un widget test; la logica di parsing
|
||||
(`qr_codec.dart`) è invece testata a parte.
|
||||
- **`UrlLauncherService`**: wrapper sottile sul `MethodChannel` nativo
|
||||
(`com.davide.biteplan/launcher`) che apre un URL nel browser — l'effetto (apertura
|
||||
browser) non è verificabile senza un device reale.
|
||||
|
||||
## Insidie note
|
||||
|
||||
- **Non chiamare `loadDb()`/`load()` dei provider nel body di `testWidgets`**: l'async
|
||||
reale eseguito nella zona `FakeAsync` di `flutter_test` può bloccare la suite (timeout
|
||||
10 min). Vanno chiamati nel `setUp()` — vedi
|
||||
[test/features/converter/pages/converter_page_test.dart](../test/features/converter/pages/converter_page_test.dart).
|
||||
- **Storage isolato**: ogni test che tocca `StorageService`/i provider deve chiamare
|
||||
`SharedPreferences.setMockInitialValues({})` prima di caricare lo stato, altrimenti i
|
||||
test si influenzano a vicenda.
|
||||
- **MethodChannel nei test**: va mockato con
|
||||
`TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger.setMockMethodCallHandler`
|
||||
— vedi [test/shared/widgets/update_dialog_test.dart](../test/shared/widgets/update_dialog_test.dart).
|
||||
- **Nuovi file in `lib/`**: aggiungerli all'import di
|
||||
[test/coverage_helper_test.dart](../test/coverage_helper_test.dart), altrimenti lcov
|
||||
li esclude dal report di coverage anche se non hanno bisogno di test dedicati.
|
||||
Reference in new issue
Block a user