traccia-calorica/docs/DEVICE_TESTING.md

# Test su Device e Creazione APK senza Android Studio

> Guida per testare l'app su dispositivo reale e generare APK usando solo CLI (senza Android Studio).
> Ultimo aggiornamento: 16/04/2026

---

## 1. Prerequisiti

### Software Necessario
| Software | Versione | Download | Note |
|----------|----------|----------|------|
| Node.js | 18+ | nodejs.org | Già installato |
| Java JDK | 17+ | adoptium.net | Per Gradle |
| Android SDK (cmdline-tools) | Latest | developer.android.com | Solo CLI, no IDE |
| Gradle | 8+ | Incluso nel progetto | Via wrapper |

### Installare Android SDK Command Line Tools (senza Android Studio)

#### Windows
```bash
# 1. Scaricare command line tools da:
# https://developer.android.com/studio#command-line-tools-only

# 2. Creare struttura directory
mkdir -p C:/Android/cmdline-tools/latest

# 3. Estrarre lo zip in C:/Android/cmdline-tools/latest/
# (i file bin/, lib/ etc. devono essere DENTRO latest/)

# 4. Configurare variabili d'ambiente (aggiungere al profilo bash o System env)
export ANDROID_HOME=C:/Android
export ANDROID_SDK_ROOT=C:/Android
export PATH=$PATH:$ANDROID_HOME/cmdline-tools/latest/bin
export PATH=$PATH:$ANDROID_HOME/platform-tools
```

#### Installare componenti SDK
```bash
# Accettare licenze
sdkmanager --licenses

# Installare componenti necessari
sdkmanager "platform-tools"
sdkmanager "platforms;android-34"
sdkmanager "build-tools;34.0.0"

# Verificare installazione
sdkmanager --list | head -20
```

### Configurare JAVA_HOME
```bash
# Windows — verificare path Java
# Il JDK 17+ deve essere installato
export JAVA_HOME="C:/Program Files/Eclipse Adoptium/jdk-17.x.x-hotspot"
# oppure
export JAVA_HOME="C:/Program Files/Java/jdk-17"

# Verificare
java -version
javac -version
```

---

## 2. Preparazione Progetto per Android

### Build dell'app Ionic
```bash
# Build di produzione
ionic build --prod

# Oppure build di sviluppo (più veloce, con source maps)
ionic build
```

### Aggiungere piattaforma Android (prima volta)
```bash
npx cap add android
```

### Sync dopo ogni build
```bash
npx cap sync android
```

### Copiare solo i file web (senza sync dipendenze native)
```bash
npx cap copy android
```

---

## 3. Build APK da Riga di Comando

### APK di Debug (per test)
```bash
# Navigare nella directory android
cd android

# Build con Gradle wrapper (non serve Gradle installato globalmente)
./gradlew assembleDebug

# L'APK si trova in:
# android/app/build/outputs/apk/debug/app-debug.apk
```

### APK di Release (per distribuzione)
```bash
# 1. Generare keystore (solo la prima volta)
keytool -genkey -v \
  -keystore calorie-tracker-release.keystore \
  -alias calorie-tracker \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000

# 2. Configurare signing in android/app/build.gradle
# Aggiungere nella sezione android {}:
```

```groovy
// In android/app/build.gradle
android {
    // ... configurazione esistente ...

    signingConfigs {
        release {
            storeFile file('calorie-tracker-release.keystore')
            storePassword 'LA_TUA_PASSWORD'
            keyAlias 'calorie-tracker'
            keyPassword 'LA_TUA_PASSWORD'
        }
    }

    buildTypes {
        release {
            signingConfig signingConfigs.release
            minifyEnabled true
            proguardFiles getDefaultProguardFile('proguard-android.txt'), 'proguard-rules.pro'
        }
    }
}
```

```bash
# 3. Build release APK
cd android
./gradlew assembleRelease

# L'APK si trova in:
# android/app/build/outputs/apk/release/app-release.apk
```

### AAB (Android App Bundle) per Google Play
```bash
cd android
./gradlew bundleRelease

# L'AAB si trova in:
# android/app/build/outputs/bundle/release/app-release.aab
```

---

## 4. Installare APK su Device

### Via USB (ADB)
```bash
# 1. Abilitare "Opzioni sviluppatore" sul telefono:
#    Impostazioni → Info telefono → Tocca 7 volte "Numero build"

# 2. Abilitare "Debug USB" nelle opzioni sviluppatore

# 3. Collegare il telefono via USB

# 4. Verificare che il device sia rilevato
adb devices
# Deve mostrare il device con stato "device"

# 5. Installare l'APK
adb install android/app/build/outputs/apk/debug/app-debug.apk

# Per reinstallare (sovrascrivere)
adb install -r android/app/build/outputs/apk/debug/app-debug.apk
```

### Via WiFi (ADB wireless)
```bash
# 1. Collegare prima via USB
adb devices

# 2. Abilitare TCP/IP
adb tcpip 5555

# 3. Trovare IP del telefono (Impostazioni → WiFi → IP)
adb connect 192.168.1.XXX:5555

# 4. Scollegare USB — ora si può installare via WiFi
adb install android/app/build/outputs/apk/debug/app-debug.apk
```

### Senza ADB — Trasferimento diretto
1. Copiare l'APK sul telefono (via USB, email, cloud, etc.)
2. Sul telefono: abilitare "Installa da origini sconosciute"
3. Aprire il file APK → Installa

---

## 5. Test in Tempo Reale (Live Reload)

### Live Reload su Device via WiFi
Il modo più veloce per testare durante lo sviluppo:

```bash
# 1. Trovare l'IP della macchina di sviluppo
# Windows:
ipconfig | grep "IPv4"
# Es: 192.168.1.100

# 2. Avviare Ionic con external host
ionic serve --external --host=0.0.0.0

# 3. Modificare capacitor.config.ts per il live reload
```

```typescript
// capacitor.config.ts — SOLO PER SVILUPPO
const config: CapacitorConfig = {
  appId: 'com.precisionvitality.app',
  appName: 'Precision Vitality',
  webDir: 'www',
  server: {
    // SOLO per live reload development!
    url: 'http://192.168.1.100:8100',  // IP della tua macchina
    cleartext: true
  }
};
```

```bash
# 4. Sync e reinstallare
npx cap sync android
cd android && ./gradlew assembleDebug && cd ..
adb install -r android/app/build/outputs/apk/debug/app-debug.apk

# 5. Aprire l'app sul device — le modifiche al codice si rifletteranno in real-time!
```

> **IMPORTANTE**: Rimuovere la sezione `server.url` da `capacitor.config.ts` prima del build di produzione!

---

## 6. Debug Remoto

### Chrome DevTools (per WebView)
1. Collegare device via USB con debug abilitato
2. Aprire Chrome sul PC → `chrome://inspect`
3. Il WebView dell'app apparirà nella lista
4. Cliccare "inspect" → si apre DevTools con console, network, elements

### Logcat (log nativi Android)
```bash
# Tutti i log
adb logcat

# Filtrare per l'app
adb logcat | grep -i "capacitor\|precision"

# Solo errori
adb logcat *:E

# Pulire e seguire
adb logcat -c && adb logcat
```

---

## 7. Script Automazione

### Script build + install completo
Creare `scripts/build-and-install.sh`:

```bash
#!/bin/bash
set -e

echo "=== Building Ionic app ==="
ionic build

echo "=== Syncing Capacitor ==="
npx cap sync android

echo "=== Building APK debug ==="
cd android
./gradlew assembleDebug
cd ..

APK_PATH="android/app/build/outputs/apk/debug/app-debug.apk"

echo "=== Installing on device ==="
adb install -r "$APK_PATH"

echo "=== Done! APK: $APK_PATH ==="
echo "=== App launched ==="
adb shell am start -n com.precisionvitality.app/.MainActivity
```

### Script build release
Creare `scripts/build-release.sh`:

```bash
#!/bin/bash
set -e

echo "=== Building Ionic production ==="
ionic build --prod

echo "=== Syncing Capacitor ==="
npx cap sync android

echo "=== Building Release APK ==="
cd android
./gradlew assembleRelease
cd ..

APK_PATH="android/app/build/outputs/apk/release/app-release.apk"
echo "=== Release APK: $APK_PATH ==="
ls -lh "$APK_PATH"
```

---

## 8. Troubleshooting

### Errore: "ANDROID_HOME not set"
```bash
# Verificare che le variabili siano settate
echo $ANDROID_HOME
echo $ANDROID_SDK_ROOT

# Se vuote, settarle nel profilo (~/.bashrc o ~/.bash_profile)
export ANDROID_HOME=C:/Android
export ANDROID_SDK_ROOT=C:/Android
```

### Errore: "SDK location not found"
```bash
# Creare/verificare android/local.properties
echo "sdk.dir=C:\\\\Android" > android/local.properties
```

### Errore: "No connected devices"
```bash
# Verificare driver USB (Windows)
# Installare Google USB Driver o driver OEM del produttore

# Verificare che il device sia in modalità debug
adb kill-server
adb start-server
adb devices
```

### Errore: "INSTALL_FAILED_UPDATE_INCOMPATIBLE"
```bash
# Disinstallare la versione precedente
adb uninstall com.precisionvitality.app
# Poi reinstallare
adb install android/app/build/outputs/apk/debug/app-debug.apk
```

### Build lento
```bash
# Aggiungere a android/gradle.properties:
org.gradle.jvmargs=-Xmx4096m
org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.caching=true
```

---

## 9. Checklist Test su Device

### Prima del test
- [ ] Node.js e Ionic CLI installati
- [ ] Android SDK command line tools installati
- [ ] Java JDK 17+ installato
- [ ] ANDROID_HOME e JAVA_HOME configurati
- [ ] Device in modalità debug USB

### Test funzionali
- [ ] App si avvia correttamente
- [ ] Navigazione tra tab funzionante
- [ ] FAB visibile e cliccabile
- [ ] Modal input numerico funzionante
- [ ] Modal input LLM funzionante
- [ ] Tastiera nativa si apre correttamente
- [ ] Scroll liste fluido
- [ ] Grafico statistiche visibile
- [ ] Ricerca funzionante
- [ ] Connessione a Firestore (online)
- [ ] Funzionamento offline (attivare modalità aereo)

### Test performance
- [ ] Tempo avvio app < 3 secondi
- [ ] Scroll fluido (60fps)
- [ ] Risposta AI < 5 secondi
- [ ] Nessun crash in 10 minuti di utilizzo

### Test compatibilità
- [ ] Android 10+ (API 29+)
- [ ] Schermo piccolo (5") e grande (6.5"+)
- [ ] Orientamento portrait
- [ ] Tastiera non copre input