Subscription Model & License Management

Overview

Visla GPS utilizza un modello di subscription basato su licenze per dispositivo. Ogni dispositivo attivo richiede una licenza valida. Il sistema gestisce automaticamente upgrade, downgrade e sospensione dispositivi per garantire che l'utente rimanga sempre nei limiti del proprio piano.

Concetti Chiave

Licenze vs Dispositivi

Licenza: Permesso di tracciare un dispositivo attivamente
Dispositivo Attivo: Dispositivo che invia posizioni e viene tracciato
Dispositivo Sospeso: Dispositivo associato all'account ma non tracciato (non consuma licenza)

Stati Dispositivo

Stato	Descrizione	Consuma Licenza	Visibile in App
Attivo	Tracciato normalmente	✅ Sì	✅ Sì
Sospeso	Associato ma in pausa	❌ No	✅ Sì (badge arancione)
Rimosso	Dissociato dall'account	❌ No	❌ No

Scenari Utente (iOS)

1. Utente Nuovo (0 Licenze, 0 Dispositivi)

Situazione Iniziale:

Licenze: 0
Dispositivi: 0

Comportamento:

✅ Può navigare l'app liberamente
✅ Nessun modal bloccante
❌ NON può aggiungere dispositivi

Flusso Aggiunta Dispositivo:

Utente clicca "Aggiungi Dispositivo"
Inserisce token Visla
PRIMA del claim, app controlla licenze
Alert: "Nessuna Licenza Attiva"
- Messaggio: "Per aggiungere dispositivi devi prima acquistare almeno una licenza"
- Bottoni: "Acquista Licenza" (blu) | "Annulla" (grigio)

Codice iOS:

// In AddDeviceView.claimDevice()
let status = try await ApiClient.shared.getLicenseStatus()

if status.allowed == 0 {
    showNoLicenseModal = true
    return
}

2. Utente con Licenze Sufficienti (2 Licenze, 1 Dispositivo)

Situazione Iniziale:

Licenze: 2
Dispositivi Attivi: 1
Disponibili: 1

Comportamento:

✅ Può aggiungere dispositivi normalmente
✅ Nessun modal bloccante
✅ Può aggiungere fino a 1 dispositivo aggiuntivo

Flusso Aggiunta Dispositivo:

Utente clicca "Aggiungi Dispositivo"
Inserisce token Visla
Check licenze: 1 < 2 ✅ OK
Device aggiunto con successo
Nuovo stato: 2 licenze, 2 dispositivi attivi

3. Utente al Limite (2 Licenze, 2 Dispositivi, Prova ad Aggiungere 3°)

Situazione Iniziale:

Licenze: 2
Dispositivi Attivi: 2
Disponibili: 0

Comportamento:

❌ NON può aggiungere dispositivi
Alert preventivo prima del claim

Flusso Aggiunta Dispositivo:

Utente clicca "Aggiungi Dispositivo"
Inserisce token Visla
PRIMA del claim, app controlla licenze
Alert: "Limite Dispositivi Raggiunto"
- Messaggio: "Hai 2 dispositivi attivi e 2 licenze. Per aggiungere altri dispositivi devi acquistare più licenze o sospendere un dispositivo esistente"
- Bottoni: "Acquista Licenze" (blu) | "Annulla" (grigio)

Codice iOS:

if status.active >= status.allowed {
    showLimitReachedModal = true
    return
}

4. Downgrade: Più Dispositivi che Licenze (3 Dispositivi, 2 Licenze)

Situazione Iniziale:

Licenze: 2 (dopo downgrade da 3)
Dispositivi Attivi: 3
Squilibrio: +1 dispositivo

Comportamento:

⚠️ Modal bloccante all'apertura app
Utente DEVE risolvere lo squilibrio

Flusso:

App si apre
checkLicenseStatus() rileva: 3 > 2
Modal: "Dispositivi Oltre il Limite"
- Messaggio: "Hai 3 dispositivi attivi ma solo 2 licenze. Scegli cosa fare:"
- Opzioni:
  - "Acquista Licenze" (blu) → Vai a piano superiore
  - "Sospendi Dispositivi" (arancione) → Apre DeviceSelectionModal

DeviceSelectionModal:

Mostra lista di tutti i dispositivi
Utente seleziona quali 2 mantenere attivi
Gli altri vengono sospesi automaticamente
Badge arancione "🟠 Sospeso" sui dispositivi sospesi

Codice iOS:

// In MainTabView.checkLicenseStatus()
if status.active > status.allowed {
    showSubscriptionRequired = true
}

Backend:

# In devices/license_utils.py
def suspend_excess_devices(user_id: int, device_ids_to_keep: List[int]):
    # Sospende tutti i device NON in device_ids_to_keep
    # Imposta suspended=True in user_device_attributes

5. Upgrade: Da 2 a 5 Licenze

Situazione Iniziale:

Licenze: 2
Dispositivi Attivi: 2
Dispositivi Sospesi: 1

Flusso:

Utente acquista upgrade (2 → 5 licenze)
Backend aggiorna allowed_licenses via webhook
Nuovo stato: 5 licenze, 2 attivi, 3 disponibili
✅ Può riattivare dispositivi sospesi
✅ Può aggiungere fino a 3 nuovi dispositivi

Riattivazione Dispositivo Sospeso:

Utente va in Device Settings di un dispositivo sospeso
Sezione "Gestione Licenza" mostra stato "🟠 Dispositivo Sospeso"
Bottone verde "Riattiva Dispositivo" (se licenze disponibili)
Conferma: "Il dispositivo verrà riattivato e riprenderà il tracciamento"
Backend imposta suspended=False
Badge cambia da "🟠 Sospeso" a "🟢 Online/🔴 Offline"

Sospensione Manuale:

Utente va in Device Settings di un dispositivo attivo
Sezione "Gestione Licenza" mostra stato "✅ Dispositivo Attivo"
Bottone arancione "Sospendi Dispositivo"
Conferma: "Il dispositivo verrà sospeso e non verrà più tracciato"
Backend imposta suspended=True
Libera una licenza per altri dispositivi

Restrizioni Provider

Regola: Un Provider per Utente

Importante: Un utente che inizia una subscription con un provider (Apple, Google, Stripe) DEVE continuare con quello stesso provider. Non è possibile mescolare provider.

Esempi

✅ Scenario Valido

Utente si registra con Apple
Acquista piano Basic (1 licenza) via Apple
Fa upgrade a Pro (5 licenze) via Apple
Fa downgrade a Basic via Apple
Tutto tramite Apple ✅

❌ Scenario NON Valido

Utente si registra con Apple
Acquista piano Basic via Apple
Prova a fare upgrade via Google Play
Backend rifiuta: "Hai già una subscription attiva con Apple"

Cambio Provider

Per cambiare provider, l'utente DEVE:

Disdire completamente la subscription con il provider corrente
Aspettare la scadenza naturale del periodo pagato
Dopo la scadenza, può acquistare con un nuovo provider

Esempio:

Utente ha subscription Apple (scade 15 Gennaio)
Disdice da Apple il 5 Gennaio
Subscription rimane attiva fino al 15 Gennaio
Dal 16 Gennaio può acquistare con Google Play

Messaggi Backend

Il backend è configurato per gestire questi casi con messaggi chiari:

# In billing/routes/subscriptions.py
if existing_provider and existing_provider != new_provider:
    raise ConflictError(
        f"Hai già una subscription attiva con {existing_provider}. "
        f"Per cambiare provider devi prima disdire la subscription corrente."
    )

Logica Backend

Endpoint Chiave

`GET /api/billing/license-status`

Restituisce lo stato corrente delle licenze:

{
  "allowed": 5,      // Licenze totali del piano
  "active": 3,       // Dispositivi attivi
  "suspended": 1,    // Dispositivi sospesi
  "total": 4         // Totale dispositivi (attivi + sospesi)
}

`POST /api/devices/{device_id}/suspend`

Sospende un dispositivo:

# Imposta suspended=True in user_device_attributes
# Il device rimane visibile ma non tracciato
# Non consuma licenza

`POST /api/devices/{device_id}/reactivate`

Riattiva un dispositivo sospeso (se licenze disponibili):

if active_count >= allowed_licenses:
    raise BadRequestError("Nessuna licenza disponibile")

# Imposta suspended=False

`POST /api/devices/select-active`

Seleziona quali dispositivi mantenere attivi durante downgrade:

# Riceve: device_ids_to_keep
# Sospende tutti gli altri
# Usato da DeviceSelectionModal

Webhook Subscription

Quando un utente cambia piano (upgrade/downgrade):

# In billing/webhooks.py
@router.post("/stripe/webhook")
async def stripe_webhook():
    # 1. Riceve evento da Stripe/Apple/Google
    # 2. Aggiorna allowed_licenses nel database
    # 3. Se downgrade e active > allowed:
    #    - Invia notifica push all'utente
    #    - Utente deve aprire app e risolvere

Copertura Scenari

✅ Scenari Coperti

Scenario	iOS	Android	Web	Backend
Nuovo utente (0 lic, 0 dev)	✅	🔄 TODO	🔄 TODO	✅
Aggiunta device senza licenze	✅	🔄 TODO	🔄 TODO	✅
Aggiunta device con licenze	✅	✅	✅	✅
Aggiunta oltre limite	✅	🔄 TODO	🔄 TODO	✅
Downgrade con squilibrio	✅	✅	✅	✅
Upgrade	✅	✅	✅	✅
Sospensione dispositivo	✅	✅	✅	✅
Riattivazione dispositivo	✅	✅	✅	✅
Cambio provider (bloccato)	✅	✅	✅	✅

🔄 Prossimi Passi

Android:

Implementare controllo licenze pre-claim in AddDeviceActivity
Aggiungere alert "No License" e "Limit Reached"

Web:

Implementare controllo licenze pre-claim in AddDeviceModal
Aggiungere modal differenziati per scenari

Diagramma Flusso Decisionale

Note Implementative

iOS

File Chiave:

MainTabView.swift - Check licenze all'apertura app
AddDeviceView.swift - Validazione pre-claim
SubscriptionRequiredModal.swift - Modal squilibrio
DeviceSelectionModal.swift - Selezione dispositivi da mantenere

Logging:

Logger.shared.info("=== checkLicenseStatus START ===")
Logger.shared.info("License status", context: [
    "allowed": status.allowed,
    "active": status.active,
    "suspended": status.suspended
])

Backend

File Chiave:

billing/routes/subscriptions.py - Gestione subscription
devices/license_utils.py - Logica sospensione/riattivazione
devices/routes/devices.py - Endpoint suspend/reactivate
billing/webhooks.py - Webhook provider

Database:

-- user_device_attributes
ALTER TABLE user_device_attributes 
ADD COLUMN suspended BOOLEAN DEFAULT FALSE;

Supporto

Per domande o problemi relativi al modello di subscription:

Backend: Vedi billing/ e devices/license_utils.py
iOS: Vedi MainTabView.swift e AddDeviceView.swift
Android: Vedi SubscriptionRequiredDialog.kt e DeviceSelectionDialog.kt
Web: Vedi subscription-required-modal.tsx e device-selection-modal.tsx

Overview​

Concetti Chiave​

Licenze vs Dispositivi​

Stati Dispositivo​

Scenari Utente (iOS)​

1. Utente Nuovo (0 Licenze, 0 Dispositivi)​

2. Utente con Licenze Sufficienti (2 Licenze, 1 Dispositivo)​

3. Utente al Limite (2 Licenze, 2 Dispositivi, Prova ad Aggiungere 3°)​

4. Downgrade: Più Dispositivi che Licenze (3 Dispositivi, 2 Licenze)​

5. Upgrade: Da 2 a 5 Licenze​

Restrizioni Provider​

Regola: Un Provider per Utente​

Esempi​

✅ Scenario Valido​

❌ Scenario NON Valido​

Cambio Provider​

Messaggi Backend​

Logica Backend​

Endpoint Chiave​

GET /api/billing/license-status​

POST /api/devices/{device_id}/suspend​

POST /api/devices/{device_id}/reactivate​

POST /api/devices/select-active​

Webhook Subscription​

Copertura Scenari​

✅ Scenari Coperti​

🔄 Prossimi Passi​

Diagramma Flusso Decisionale​

Note Implementative​

iOS​

Backend​

Supporto​

Overview

Concetti Chiave

Licenze vs Dispositivi

Stati Dispositivo

Scenari Utente (iOS)

1. Utente Nuovo (0 Licenze, 0 Dispositivi)

2. Utente con Licenze Sufficienti (2 Licenze, 1 Dispositivo)

3. Utente al Limite (2 Licenze, 2 Dispositivi, Prova ad Aggiungere 3°)

4. Downgrade: Più Dispositivi che Licenze (3 Dispositivi, 2 Licenze)

5. Upgrade: Da 2 a 5 Licenze

Restrizioni Provider

Regola: Un Provider per Utente

Esempi

✅ Scenario Valido

❌ Scenario NON Valido

Cambio Provider

Messaggi Backend

Logica Backend

Endpoint Chiave

`GET /api/billing/license-status`

`POST /api/devices/{device_id}/suspend`

`POST /api/devices/{device_id}/reactivate`

`POST /api/devices/select-active`

Webhook Subscription

Copertura Scenari

✅ Scenari Coperti

🔄 Prossimi Passi

Diagramma Flusso Decisionale

Note Implementative

iOS

Backend

Supporto