Merge pull request #33 from SwevenSoftware/feature/android-developer-fix

improved android developer manual

Author: lusergit

assets/android/MVVM.png

@@ -17,29 +17,50 @@ nav_order: 3
 {:toc}
 </details>
 
-L'architettura scelta per l'applicazione mobile è il MVVM (Model View ViewModel).
-Questa architetura è ottima per separare logica da presentazione, ma non solo, è particolarmente utile per gestire con efficacia e scalabilità le chiamate API.
-Ogni funzionalità infatti segue questa architettura, con alcune aggiunte per soddisfare le necessità intrinseche ad ogni funzionalità.
-
-Questo si denota dal nostro diagramma dei package:
+## Diagramma dei pacchetti
+Vediamo qui il nostro diagramma dei package:
 
 ![](/assets/android/package_diagram.png)
 
-Il package "ui" gestiscono i file della view e del viewmodel, il package "data" gestisce il model e il package "services" contiene le interfacce API.
-Invece il package "res" contiene tutti i file xml e png per gestire l'aspetto e le icone dell'applicazione.
+I package all'interno di "ui" gestiscono i file della View e del Viewmodel e eventuali altre classi. 
+Il package "data" gestisce il Model con le sue data class e le repositories. 
+Il package "services" contiene le interfacce API, il NetworkClient e le data class per le risposte del server.
+Infine il package "res" contiene tutti i file xml e png per gestire l'aspetto, la navigazione e le icone dell'applicazione.
 
-Nello specifico quindi ogni funzionalità ricrea il MVVM, come descritto in questo diagramma delle classi, specifico per la funzionalità UserRooms:
+## Pattern architetturale: MVVM
+L'architettura scelta per l'applicazione mobile è il MVVM (Model View ViewModel).
+Questa architetura è ottima per separare logica da presentazione, ma non solo, è particolarmente utile per gestire con efficacia e scalabilità le chiamate API.
+Ogni funzionalità infatti segue questa architettura, a volte con alcune aggiunte per soddisfare le necessità intrinseche di ogni funzionalità.
+Nello specifico quindi ogni funzionalità ricrea il MVVM, in cui si va a separare la UI dalla business logic:
+- la View utilizza linguaggi di markup, nel nostro caso .xml, e si utilizza il two-way data binding per comunicare con essa.
+- il ViewModel fa da intermediario tra il Model e la View grazie a LiveData. Invoca i metodi del Model per poi fornire i dati ottenuti alla View in una forma facilmente utilizzabile.
+- il Model comunica con il server e contiene dati e logica di validazione.
+
+![](/assets/android/MVVM.png)
+
+## Diagramma delle classi
+Vediamo ora un diagramma delle classi, in questo caso della funzionalità UserRooms ma utilizzato in generale da quasi tutte le pagine:
 
 ![](/assets/android/class_diagram.png)
 
 Da questo diagramma possiamo vedere come sono implementati i metodi e le classi del MVVM.
-Per prima cosa viene creato il model, per gestire gli oggetti in entrata dal lato server.
+Per prima cosa viene creato il Model, per gestire gli oggetti in entrata dal lato server.
 La chiamata Get all'API viene fatta dall'interfaccia APIRooms, creata dalla UserRepository tramite il nostro Retrofit Builder, implementato nel file NetworkClient.
 In NetworkClient vengono anche gestiti i certificati http tramite la libreria Okhttp3.
-L'UserRoomsFragment gestisce assieme ai file XML la view e alla propria creazione, tramite un UserRoomsViewModelFactory, crea il nostro viewModel: UserRoomsViewModel.
+L'UserRoomsFragment gestisce assieme ai file .xml la View, con cui comunica tramite data binding. Alla propria creazione, tramite un UserRoomsViewModelFactory, crea il nostro ViewModel: UserRoomsViewModel.
 I dati che vengono ricevuti dal server tramite Retrofit vengono inseriti all'interno di LiveData, i quali vengono letti da UserRoomsFragment e UserRoomsViewModel tramite observers definiti nelle relative classi.
-Questi observers si occupano di gestire e notificare alla view i cambiamenti agli oggetti, in modo da poter aggiornare i dati visti dall'utente nell'applicazione.
+Questi observers si occupano di gestire e notificare alla View i cambiamenti agli oggetti, in modo da poter aggiornare i dati visti dall'utente nell'applicazione.
 
 Come introdotto prima, ogni funzionalità ha dei bisogni aggiuntivi propri, in questo caso ad esempio è stato necessario implementare un UserRoomsAdapter per gestire dinamicamente gli oggetti della lista prenotazioni, implementata tramite uno standard RecyclerView.
 
+## Espansione
+Vista la natura modulare di questa applicazione è possibile estenderla in modo semplice visto che ogni pagina è indipendente dalle altre. Se si volessero aggiungere ulteriori funzionalità 
+è sufficiente seguire i pattern già utilizzati per le altre pagine e quindi avere:
+- un file .xml all'interno del package "layout";
+- creare un nuovo package all'interno di "ui", contenente almeno un Fragment ed un ViewModel che comunicano con il layout tramite data binding;
+- se si desidera utilizzare API del server, creare un'interfaccia all'interno di "apis", una Repository all'interno di "repositories" ed eventuali data class all'interno di "model" e "gsonReceive".
+Infine, una volta creata la nuova pagina, è possibile inserirla all'interno dei file nel package "navigation" per renderla accessibile da altre pagine tramite la navigazione standard di Android.
+
+Seguendo la struttura dei package appena definita, è anche possibile aggiungere test di unità delle rispettive classi all'interno della cartella "com.sweven.blockcovid (test)".
+
 {% include prev_next.liquid %}

assets/android/class_diagram.png

@@ -23,8 +23,10 @@ Come indicato all'interno della sezione [Contributing del README](https://github
 
 Modifiche al codice sorgente (per ogni _branch_ e per _Pull Request_) scatenano i processi di [_continuous-integration_](/glossario#continuous-integration) attraverso _GitHub Actions_, seguendo due workflow (`.github/workflows`):
 - `build-app`
-    - Compila il codice
+    - Compila il codice;
 - `detekt-analysis`
-    - Esegue un'analisi statica del codice
+    - Esegue un'analisi statica del codice;
+- `code-coverage`
+    - Calcola la code coverage e la carica su [Codecov](https://codecov.io/).
 
 {% include prev_next.liquid %}

manutentore/android/architettura.md

@@ -33,36 +33,19 @@ Per preparare l'ambiente di lavoro per lo sviluppo dell'applicazione mobile Bloc
 1. scaricare ed installare Android Studio, disponibile al seguente link: [Android Studio](https://developer.android.com/studio);
 2. scaricare l'ultima release dell'applicazione, in formato .zip, disponibile al seguente link: [BlockCOVID-Android](https://github.com/SwevenSoftware/BlockCOVID-android/releases);
 3. estrarne il contenuto in una cartella qualsiasi;
-4. tramite Android Studio, aprire la cartella in cui è stata estratta la release come progetto;
+4. tramite Android Studio, aprire la cartella in cui è stata estratta la release come progetto.
 
-### Apk bundle
+### APK bundle
 
-#### Android studio
+#### Android Studio
 {: .no_toc }
-Android studio offre la possibilità di realizzare un bundle `apk`
+Android Studio offre la possibilità di realizzare un bundle `apk`
 della propria applicazione direttamente all'interno dell'IDE. Questa
 funzione è disponibile all'interno di *Build > Generate signed
-bundle/APK*
+bundle/APK*.
 
-#### Gradle
-{: .no_toc }
-Gradle permette di generare un bundle non firmato della propria
-applicazione tramite 
-
-```sh
-./gradlew assemble
-```
-
-nella root del progetto. In questo caso per l'installazione su un
-dispositivo è necessario firmare l'applicativo generato (rialsciato da
-gradle nel percorso `app/build/output/apk`). È possibile firmare l'apk
-generato tramite il tool apksigner rilasciato ufficialmente dal team
-di sviluppo android. Maggiori informazioni sul suo utilizzo nella
-[documentazione
-ufficiale](https://developer.android.com/studio/command-line/apksigner)
-
-### Testing
-È possibile testare il comportamento dell'applicazione sempre tramite Android Studio:
+## Esecuzione
+È possibile eseguire l'applicazione per testarne il comportamento sempre tramite Android Studio:
 
 - Attivare la modalità debug sul proprio dispositivo Android;
 - fare la build del progetto tramite Android Studio tramite ***Build >

manutentore/android/contribuzione.md

@@ -25,15 +25,15 @@ Android SDK fornisce le librerie API e gli strumenti per sviluppatori necessari
 
 - - -
 
-### Kotlin 1.4.32
+### Kotlin 1.5.20
 
 Kotlin è un linguaggio di programmazione general purpose, multi-paradigma, open source sviluppato dall'azienda di software JetBrains. Kotlin si basa sulla JVM (Java Virtual Machine) e dal 2019 viene utilizzato da Google per lo sviluppo Android.
 
 [https://kotlinlang.org/](https://kotlinlang.org/)
 
 - - -
 
-### Gradle 6.5
+### Gradle 6.7.1
 Gradle è uno strumento di automazione della build open source progettato per essere abbastanza flessibile da creare quasi tutti i tipi di software. Gradle viene eseguito sulla JVM e per utilizzarlo è necessario disporre di un Java Development Kit (JDK)
 
 [https://docs.gradle.org/current/userguide/userguide.html](https://docs.gradle.org/current/userguide/userguide.html)

manutentore/android/installazione.md

@@ -20,13 +20,22 @@ nav_order: 4
 ## Test di unità
 I test di unità sono stati sviluppati utilizzando Junit e Mockito.
 Per eseguirli tramite Android Studio è sufficiente fare tasto destro sul file di test all'interno della cartella "com.sweven.blockcovid (test)" e cliccare su "Run Test with Coverage".
+Alternativamente è possibile eseguirli tramite JaCoCo tramite il comando:
+```sh
+./gradlew clean test jacocoTestReport
+```
+dalla root del progetto. Verrà generato un report con il code coverage all'interno della cartella "/app/build/reports/jacoco/jacocoTestReport/html/index.html".
 
 ## Test di sistema
-I test di sistema invece sono stati sviluppati tramite Espresso.
-Per eseguirli tramite Android Studio è sufficiente fare tasto destro sul file di test all'interno della cartella "com.sweven.blockcovid (androidTest)" e cliccare su "Run Test with Coverage".
-Prima di eseguire questi test è necessario fare il run sul dispositivo mobile o sulla macchina virtuale e assicurarsi di essere sulla pagina di login. Inoltre è necessario disabilitare le animazioni del dispositivo Android tramite le Opzioni sviluppatore. 
+I test di sistema invece sono stati sviluppati tramite Espresso, situati nella cartella "/tests".
+Per eseguirli tramite Android Studio è sufficiente copiarli all'interno della cartella "androidTest", fare tasto destro sul file di test e cliccare su "Run Test with Coverage".
+Prima di eseguire questi test è necessario fare il run sul dispositivo mobile o sulla macchina virtuale e assicurarsi di essere sulla pagina di login. 
+Inoltre è necessario disabilitare le animazioni del dispositivo Android tramite le Opzioni sviluppatore. 
 
 ## GitHub Actions
-Il servizio di [Continuous Integration](/glossario#continuous-integration) che è stato deciso di utilizzare è GitHub Actions, fornito appunto da GitHub. Questo permette di creare dei workflow personalizzati, ovvero dei processi automatici creati sulla base delle proprie esigenze. Ciò ha l'obiettivo di automatizzare il ciclo di vita di sviluppo del software grazie ad un ampia gamma di strumenti e servizi.
+Il servizio di [Continuous Integration](/glossario#continuous-integration) che è stato deciso di utilizzare è GitHub Actions, fornito appunto da GitHub. 
+Questo permette di creare dei workflow personalizzati, ovvero dei processi automatici creati sulla base delle proprie esigenze. 
+Ciò ha l'obiettivo di automatizzare il ciclo di vita di sviluppo del software grazie ad un ampia gamma di strumenti e servizi.
+La code coverage viene automaticamente calcolata ed aggiornata ad ogni push su GitHub tramite [Codecov](https://codecov.io/).
 
 {% include prev_next.liquid %}

manutentore/android/tecnologie.md

@@ -15,16 +15,16 @@ Lo scopo del Manuale Manutentore è presentare le procedure di installazione e s
 
 Il prodotto BlockCOVID permette di tracciare l'utilizzo di postazioni e stanze di lavoro all'interno di aziende.
 Il progetto si articola su 3 moduli:
-- [Server](/manutentore/server): espone le API utilizzate dai client Android e Web, fornisce la business logic e permette di persistere i dati su database e servizio blockchain,
-- [Android](/manutentore/android): permette ai dipendenti di prenotare ed utilizzare le postazioni di lavoro, e agli addetti alle pulizie di segnalare le stanze sanificate,
+- [Server](/manutentore/server): espone le API utilizzate dai client Android e Web, fornisce la business logic e permette di persistere i dati su database e servizio blockchain;
+- [Android](/manutentore/android): permette ai dipendenti di prenotare ed utilizzare le postazioni di lavoro, e agli addetti alle pulizie di segnalare le stanze sanificate;
 - [Web](/manutentore/web): mette a disposizione degli amministratori una piattaforma web per reperire informazioni sull'utilizzo delle postazioni, con possibilità di creare e modificare stanze e di generare i report che verranno aggiunti alla blockchain.
 
 ## Tipologie di utenti
 
 All'interno del progetto vengono considerate 3 tipologie di utenti (si noti che ogni account può essere associato a più di una tipologia di utente):
-- **User**: generalmente associato ad un dipendente, permette di effettuare prenotazioni ed utilizzare le postazioni
-- **Cleaner**: tipologia di utente utilizzato dagli addetti alle pulizie per segnalare la sanificazione delle stanze
-- **Admin**: utenti che hanno permessi di modifica di stanze e account, nonché di visualizzazione di tutte le prenotazioni presenti nel sistema 
+- **User**: generalmente associato ad un dipendente, permette di effettuare prenotazioni ed utilizzare le postazioni:
+- **Cleaner**: tipologia di utente utilizzato dagli addetti alle pulizie per segnalare la sanificazione delle stanze:
+- **Admin**: utenti che hanno permessi di modifica di stanze e account, nonché di visualizzazione di tutte le prenotazioni presenti nel sistema.
 
 ## Riferimenti informativi
 - [Documentazione Spring](https://spring.io/projects/)