From b1eb92e83d02fe1751ebfd0f4b2feda42270ab8a Mon Sep 17 00:00:00 2001 From: Davide Grilli Date: Sun, 20 Sep 2026 16:48:34 +0200 Subject: [PATCH] docs: aggiunge docs/architettura.md e ristruttura il README Documenta flusso dati per feature, QR e update checker per chi sviluppa il progetto; riorganizza il README nella struttura standard overview/features/architecture/requisiti/installazione/uso/test/build/ contribuire, senza perdere contenuti esistenti. Piccole correzioni a CLAUDE.md (app_theme.dart nell'albero, nota su kAppVersion non sincronizzato). Co-Authored-By: Claude Sonnet 5 --- CLAUDE.md | 2 + README.md | 167 ++++++++++++++++++++++++------------------- docs/architettura.md | 83 +++++++++++++++++++++ 3 files changed, 178 insertions(+), 74 deletions(-) create mode 100644 docs/architettura.md diff --git a/CLAUDE.md b/CLAUDE.md index 0212807..b3fdad3 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -55,6 +55,7 @@ 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 @@ -64,6 +65,7 @@ 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) diff --git a/README.md b/README.md index 4194417..0e0209a 100644 --- a/README.md +++ b/README.md @@ -2,9 +2,29 @@ App Android per la gestione della dieta quotidiana — pianificazione pasti, conversione crudo/cotto e lista della spesa. -## Funzionalità +> Un'unica app per pianificare la settimana, sapere quanto pesare crudo o cotto e non dimenticare cosa comprare. -### Piano Pasti +![License](https://img.shields.io/badge/license-EUPL--1.2-blue) +![Flutter](https://img.shields.io/badge/flutter-3.41.9-02569B?logo=flutter) +![Platform](https://img.shields.io/badge/platform-Android-3DDC84?logo=android) + +## 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 - 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 @@ -28,7 +48,32 @@ App Android per la gestione della dieta quotidiana — pianificazione pasti, con - 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 -## Stack +## 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 | Livello | Tecnologia | |---|---| @@ -38,19 +83,7 @@ App Android per la gestione della dieta quotidiana — pianificazione pasti, con | QR code | qr_flutter + mobile_scanner | | Build APK | Docker (headless) | -## Sviluppo - -Sviluppo locale con Flutter installato sull'host e un emulatore Android dedicato — no Docker. - -```bash -emulator -avd biteplan & -flutter run -# hot reload con "r", hot restart con "R" -``` - -Vedi [docker/README.md](docker/README.md) per test e build APK via Docker. - -### Requisiti host +Requisiti host per lo sviluppo: - **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: @@ -62,7 +95,7 @@ Vedi [docker/README.md](docker/README.md) per test e build APK via Docker. - **Java 17+** (`sudo apt install openjdk-21-jdk`) - Strumenti di base: `git curl unzip` — e ~15 GB di spazio libero -### Installazione passo passo +## Installazione **1. Flutter** (versione pinnata `3.41.9`, la stessa di `.flutter-version`): @@ -116,104 +149,90 @@ 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. -### Installare e testare l'APK di debug sull'emulatore +## Utilizzo + +```bash +emulator -avd biteplan & +flutter run +# hot reload con "r", hot restart con "R" +``` + +Per l'uso dell'app una volta installata, vedi la [guida utente](docs/guida-utente.md). + +### Installare e testare un APK già buildato 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 -``` -**4. Osserva i log in tempo reale (utile per debug):** - -```bash +# log in tempo reale adb logcat --pid=$(adb shell pidof -s com.davide.biteplan) -``` -**5. Disinstalla quando hai finito:** - -```bash +# disinstalla quando hai finito adb uninstall com.davide.biteplan ``` -> Per lo sviluppo iterativo (hot reload) usa invece `flutter run` — questa procedura serve -> a validare l'APK esatto che verrà distribuito. +> Per lo sviluppo iterativo (hot reload) usa `flutter run` — questa procedura serve a +> validare l'APK esatto che verrà distribuito. ## Test -La suite copre unit test e widget test. Richiede l'immagine Docker `biteplan-build` -(creata automaticamente al primo `bash docker/build.sh`). - ```bash -# Tutti i test (dalla root del progetto) -docker run --rm -v "$(pwd):/workspace" -w /workspace biteplan-build \ - bash -c "flutter pub get && flutter test" +flutter test # tutta la suite (host) +flutter test test/features/meal_planner/qr_test.dart # singolo file -# Un singolo file +# versione riproducibile via Docker (immagine biteplan-build, creata al primo bash docker/build.sh) docker run --rm -v "$(pwd):/workspace" -w /workspace biteplan-build \ - bash -c "flutter test test/features/meal_planner/qr_test.dart" + bash -c "flutter pub get --enforce-lockfile && flutter test" ``` -### Struttura +Struttura di `test/` (rispecchia `lib/`): -``` +```text test/ -├── helpers/ -│ └── pump_app.dart # estensione pumpApp per widget test +├── helpers/pump_app.dart # estensione pumpApp per widget test ├── features/ -│ ├── 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 +│ ├── converter/{models,providers}/ +│ ├── meal_planner/{models,providers,widgets}/ + qr_test.dart +│ └── shopping_list/{models,providers,widgets}/ +└── shared/{services,widgets}/ ``` ## Build APK ```bash -bash docker/build.sh # debug → dist/biteplan-debug.apk -bash docker/build.sh --release # release → dist/biteplan-release.apk +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. +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) - [Changelog](CHANGELOG.md) -## Licenza +## Stato e licenza -[EUPL v1.2](LICENSE) — Davide Grilli +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. diff --git a/docs/architettura.md b/docs/architettura.md new file mode 100644 index 0000000..91e3b79 --- /dev/null +++ b/docs/architettura.md @@ -0,0 +1,83 @@ +# 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.