Documentazione Tecnica

Benvenuto nella documentazione ufficiale di FidelityApp. Questo documento spiega l'architettura, la logica di business e l'integrità del sistema multi-tenant creato.

Architettura Core

L'app segue i principi della Clean Architecture per garantire testabilità e scalabilità. Il codice è diviso in feature-folder:

  • Data Layer: Implementazione dei repository e chiamate Firebase/Hive.
  • Domain Layer: Modelli dati (Freezed) e logica di business pura.
  • Presentation Layer: UI Flutter (Widget) e State Management (Riverpod).

Stack Tecnologico

Flutter (Dart)

Framework UI cross-platform.

Riverpod + Generator

Gestione dello stato reattiva.

Firebase

Auth, Firestore e Cloud Storage.

Hive

Database NoSQL locale per persistenza offline.

Schema Firestore

Il database è strutturato per supportare il multi-tenancy:

/users/{uid} -> { role: 'merchant' | 'customer' }
/merchants/{uid} -> { businessName, pointsRate, logoUrl }
/customers/{uid} -> { displayName, qrCodeId }
/memberships/{id} -> { merchantId, customerId, pointsBalance }
/transactions/{id} -> { merchantId, customerId, amount, type, status }

Logica di Scansione

Il sistema utilizza due tipi di flussi:

  1. Accredito Punti: Il Merchant scansiona il QR statico del Cliente -> Inserisce l'importo -> Transazione atomica su Firestore.
  2. Riscatto Premi: Il Cliente genera un QR temporaneo (codice RWD-XXXX) -> Il Merchant lo scansiona -> Il sistema convalida la transazione "Pending".

API Pubbliche e Cloud Functions

Il sistema espone API RESTful tramite Firebase Cloud Functions (Node.js) per permettere l'integrazione con gestionali di cassa di terze parti.

  • Autenticazione: Middleware custom che verifica la validità del Bearer Token (apiKey) generato dal merchant.
  • Rate Limiting & Sicurezza: Le funzioni controllano che il merchant sia autorizzato (piano PRO attivo) prima di elaborare le richieste.
  • Endpoint Punti: Utilizza transazioni Firestore per garantire la consistenza tra l'aggiunta punti, l'aggiornamento storico e l'aggiornamento totali.
  • Endpoint Push: Si interfaccia in modo asincrono con l'API REST di OneSignal per l'invio massivo o mirato di notifiche, bypassando i limiti del client.
Vedi la documentazione completa degli endpoint API →

Setup Locale Sviluppatore

Per avviare il progetto dopo il checkout:

# 1. Installa dipendenze
flutter pub get

# 2. Genera i file necessari (Freezed/Riverpod)
dart run build_runner build --delete-conflicting-outputs

# 3. Collega Firebase
flutterfire configure