Introduzione

MyFidelity: Un Sistema Innovativo di Gestione della Fidelizzazione

MyFidelity è un'applicazione progettata per rafforzare il legame della fiducia tra il negozio e la loro clientela. Attraverso l'uso di questo applicativo, il proprietario del negozio può offrire un'esperienza personalizzata e gratificante ai loro clienti fedeli tramite dei vantaggi forniti da MyFidelity.

Funzionalità Principali:

Scansione QR: Ogni cliente possiede un codice QR univoco, che il negoziante può facilmente scansionare utilizzando un dispositivo mobile munito del suo accesso predefinito. Questo processo semplifica l'aggiunta di punti fedeltà al profilo del cliente.

Accumulo Punti: I clienti accumulano punti fedeltà ogni volta che effettuano acquisti che superano una soglia minima di spesa.

Massimo Punti: Il numero massimo di punti che un cliente può accumulare è 12. Questi punti non scadono, garantendo ai clienti la libertà di utilizzarli senza preoccupazioni di perdere i benefici acquisiti.
Riscatto Punti: Una volta che un cliente decide di utilizzare i suoi punti massimi accumulati per ottenere uno sconto, il saldo dei punti si azzera. Questo permette al cliente di iniziare un nuovo ciclo di accumulo e di beneficiare nuovamente delle ricompense offerte dalla fidelity card.
Auto-Lettura Punti: I clienti possono monitorare autonomamente i punti fedeltà accumulati attraverso l'applicazione utente. Questa funzione di auto-lettura fornisce trasparenza e consente ai clienti di essere sempre aggiornati sul loro saldo punti.
Interfaccia Negozianti: Esiste un'interfaccia dedicata ai negozianti all'interno dell'applicazione, non accessibile ai clienti normali. Questa interfaccia permette ai negozianti di gestire con facilità le fidelity card, visualizzare i saldi punti di ciascun cliente e monitorare l'efficacia del programma di fidelizzazione.

Vantaggi per il Negozio:

Fidelizzazione Clienti: L'App MyFidelity incentiva i clienti a tornare, aumentando la probabilità di acquisti ripetuti.
Marketing Personalizzato: Con le informazioni raccolte, i negozianti possono creare offerte personalizzate che rispondono alle preferenze di acquisto dei clienti.
Analisi Dati: L'interfaccia del negoziante fornisce dati preziosi sul comportamento di acquisto dei clienti, permettendo di ottimizzare le strategie di vendita.

Vantaggi per il Cliente:

Ricompense Tangibili: I clienti si sentono apprezzati e ricompensati per la loro fedeltà, incentivandoli a continuare a fare acquisti nel negozio.
Facilità d'Uso: L'applicazione è intuitiva e facile da usare, rendendo semplice per i clienti tenere traccia dei loro punti e dei vantaggi.

Utilizzo cliente

Processo di Installazione e Registrazione nell'App MyFidelity

Per iniziare a sfruttare i vantaggi dell'app MyFidelity, il cliente dovrà seguire questi passaggi:

Installazione dell'App: Scaricare e installare l'applicativo MyFidelity per il proprio dispositivo mobile.
Creazione del Profilo Utente:
- Accedere alla pagina di registrazione integrata nell'app.
- Compilare i campi richiesti con le proprie informazioni personali.
- Confermare la registrazione per creare un profilo sicuro all'interno dell'app.
Accesso utente:
- Effettuare il login con le credenziali scelte in fase di registrazione. Da qui viene possibile la visualizzazione dei dettagli di come i punti sono stati guadagnati, inclusi l'importo speso e la data dell'acquisto.
Accumulo Punti:
- Una volta effettuato l'accesso, gli utenti possono iniziare ad accumulare punti fedeltà. I punti verranno registrati digitalmente nel profilo utente ad ogni acquisto qualificante.
Profilo Utente e Codice QR:
- Nella sezione profilo, gli utenti possono trovare le loro informazioni personali e la possibilità di disconnettersi dall'App (Logout).
- In basso alla schermata è presente un icona da dove sarà possibile aprire l'interfaccia di visualizzazione del proprio Codice QR.
- Presentando questo codice QR al negoziante presso i negozi supportati, sarà possibile accumulare punti fedeltà con facilità.

Esperienza Utente Post-Registrazione

Dopo la registrazione, l'utente avrà accesso a una serie di funzionalità che migliorano l'esperienza di acquisto:

Visualizzazione delle Fidelity Card: L'utente può consultare le sue fidelity card, sia quelle correnti che quelle passate, con tutti i dettagli relativi agli acquisti effettuati.
Gestione dei Punti Fedeltà: Monitorare i punti accumulati e comprendere come sfruttarli al meglio per ottenere premi o sconti.
Facilità di Accumulo Punti: Grazie al codice QR univoco, l'accumulo dei punti diventa un processo semplice e veloce durante la visita ai negozio affiliato.

Utilizzo dell'applicazione con profilo Negoziante/Amministrativo

L'applicazione MyFidelity offre funzionalità amministrative per gestire le fidelity card e i clienti. Ecco come utilizzarla:

Installazione dell'App:
- Scarica e installa l'applicativo MyFidelity sul tuo dispositivo mobile.
Accesso tramite profilo amministrativo:
- Accedi all'app utilizzando le credenziali del profilo amministrativo (queste vengono predisposte per il negoziante).
Scannerizza il codice QR del cliente:
- Una volta entrati nell'app, utilizza la funzione di scansione nella parte inferiore della schermata per accedere rapidamente alle informazioni del cliente e registrare un punto sulla fidelity card.

Altre funzionalità dell'applicativo nel profilo amministratore

Visualizzazione delle informazioni sulle fidelity card:
- Per vedere il numero di fidelity card attive, vai alla sezione corrispondente nell'app.
- Controlla anche quante fidelity card sono state completate dai clienti.
Gestione dei punti dei clienti:
- Visualizza e modifica i punti accumulati da ciascun cliente.

Frontend

Dettagli Tecnici dello Sviluppo Front-End di MyFidelity

Per la realizzazione della parte front-end dell'applicazione MyFidelity, sono stati selezionati strumenti all'avanguardia nel panorama dello sviluppo web e mobile:

Angular Typescript: Questo potente framework web è stato scelto per la sua capacità di costruire applicazioni dinamiche e reattive. Angular offre un ambiente robusto per lo sviluppo di interfacce utente complesse, sfruttando il linguaggio TypeScript per garantire tipizzazione statica e oggetti orientati agli oggetti.

Ionic Framework: La scelta di Ionic come framework cross-platform permette a MyFidelity di essere accessibile su una vasta gamma di dispositivi. Ionic si integra perfettamente con Angular, fornendo componenti UI ottimizzati per dispositivi mobili e una performance fluida su sia iOS che Android.

Akita State Management: Per gestire lo stato dell'applicazione in modo efficiente, è stato adottato Akita. Questo pattern di state management consente di mantenere una fonte di verità unica per lo stato dell'applicazione, facilitando la sincronizzazione dei dati tra le varie parti dell'interfaccia utente.

L'architettura dell'applicazione segue gli standard di Ionic, con una gestione dei dati dell'utente in locale che assicura rapidità e sicurezza nell'accesso alle informazioni. Akita viene utilizzato per gestire lo stato dell'applicazione, offrendo una soluzione scalabile e manutenibile.

src/
╰── app/
╰── assets/
╰── environments/
╰── theme/
╰── global.scss
╰── index.html
╰── main.ts
╰── polyfills.ts
╰── test.ts
╰── zone-flags.ts

Struttura delle Pagine:

Homepage Cliente: La pagina principale del cliente è il cuore dell'esperienza utente, dove è possibile visualizzare la propria fidelity card con i punti accumulati, l'importo e la data degli acquisti qualificanti.

app/
╰── tabs/
    ╰── page/
        ╰── home/

Dashboard Admin: La homepage dedicata al gestore del negozio offre una panoramica delle statistiche generali del programma di fidelizzazione, inclusa una lista dei clienti con i relativi punti. Questa pagina fornisce anche strumenti per l'analisi statistica, permettendo al negoziante di valutare l'efficacia delle strategie di fidelizzazione.

app/
╰── tabs/
    ╰── page/
        ╰── admin/
            ╰── home-admin/

Sezione Autenticazione: L'applicazione include una sezione dedicata al login e alla registrazione. L'accesso alle funzionalità di fidelizzazione è protetto da autenticazione, assicurando che ogni utente sia univocamente identificato e il suo profilo sia accuratamente gestito.

Per la registrazione:

app/
╰── page/
    ╰── register/

Per il login:

app/
╰── page/
    ╰── login/

Sviluppo del frontend

Per sviluppare sul progetto dell'App MyFidelity sul lato Frontend, è necessario seguire una serie di passaggi che includono l'installazione di Node.js e delle sue dipendenze, la clonazione della repository del progetto e l'installazione delle dipendenze del progetto. Di seguito sono riportati i passaggi dettagliati:

Installazione di Node.js

Prima di tutto, è necessario installare Node.js sul tuo sistema. Puoi farlo utilizzando i seguenti comandi a seconda del tuo sistema operativo:

Winget (Windows 10/11)
```
winget install --id=OpenJS.NodeJS  -e
```

Homebrew (MacOS/Linux)
```
brew install node
```

Clonazione della Repository del Progetto

Dopo aver installato Node.js, è possibile clonare la repository del progetto utilizzando il tuo client Git. Il comando per farlo è il seguente:

git clone -b develop https://gitlab.com/5ci-li-megghiu/pantacard-frontend

Installazione delle Dipendenze del Progetto

Una volta clonato il progetto, entra nella cartella del progetto e apri il terminale di sistema per installare le dipendenze. Questo include l'installazione di Angular e Ionic, oltre alle dipendenze specifiche del progetto. I comandi per farlo sono i seguenti:

Installazione Angular
```
npm install angular
```
Installazione Ionic
```
npm install ionic
```
Installazione Dipendenze Progetto
```
npm install
```

Dopo aver installato le dipendenze, sarai in grado di partecipare allo sviluppo del progetto.

Esecuzione del Progetto

Per eseguire il progetto sul tuo sistema locale, utilizza il seguente comando:

ionic serve

Questo avvierà il server di sviluppo e potrai visualizzare l'app nel tuo browser.

Backend

Dettagli Tecnici dello Sviluppo Back-End di MyFidelity

Nella realizzazione della parte back-end dell’applicazione MyFidelity, sono stati selezionati strumenti adeguati per garantire un funzionamento efficiente e scalabile. Ecco i dettagli tecnici:

Tecnologie Utilizzate

Java: Il linguaggio di programmazione principale utilizzato per sviluppare la parte backend, tra cui le API usato nella versione 21.
JDBC (Java Database Connectivity): Un'API Java che definisce come un client può accedere a un database. Utilizziamo il driver JDBC di MariaDB per interfacciarci con il database MariaDB.

MariaDB: MariaDB, un database relazionale open source, offre elevate prestazioni, sicurezza e compatibilità con MySQL. Il driver JDBC di MariaDB consente alle applicazioni Java di interagire con il database.

Spring Boot: Un framework che semplifica la creazione di applicazioni stand-alone e basate su produzione, utilizzando il modello di programmazione Spring.

Panoramica del Framework Spring Boot Spring Boot semplifica la configurazione delle applicazioni Java, supporta lo sviluppo di microservizi e offre un ambiente di sviluppo integrato con server web incorporati.

Alcune delle dependencies utilizzate:

Spring Data JPA: Per l'accesso ai dati tramite JPA (Java Persistence API). Semplifica l'interazione con il database e offre funzionalità avanzate per le operazioni CRUD.
Spring Boot Starter Web : Per la creazione di servizi web RESTful. Questa dipendenza abilita il framework Spring MVC per gestire le richieste HTTP e le risposte.
Spring Security Core e Spring Security Web: Per la gestione dell'autenticazione e dell'autorizzazione. Queste dipendenze consentono di proteggere le risorse dell'applicazione e gestire gli utenti.
Lombok: Per la generazione automatica di codice boilerplate. Semplifica la scrittura di classi riducendo la verbosità del codice.
JSON Web Token (JWT): Per la gestione dei token di autenticazione. Questa libreria consente di creare, verificare e gestire i token JWT.

Liquibase: Uno strumento di gestione delle versioni del database, che consente di tracciare, gestire e applicare modifiche allo schema del database in modo sicuro e affidabile. Utilizzata come dependency all'interno di Spingboot tramite Liquibase Core.

Inizializzazione del Database con Liquibase Liquibase gestisce le migrazioni del database, traccia le modifiche e facilita l'integrazione continua automatizzando le migrazioni come parte del processo di build e deploy.

Struttura Database

Qui troviamo le tabelle e le entità che le compongono con le loro rispettive associazioni, ogni tabella ha un ruolo specifico:

utenti: Questa tabella contiene informazioni sugli utenti del sistema. Ogni utente ha un id, nome, cognome, email, password, data di nascita, ruolo (per distinguere tra diversi tipi di utenti come clienti, e admin), numero di cellulare, username e codice.

fidelity_card: Questa tabella tiene traccia delle carte fedeltà emesse. Ogni carta ha un id, una data di inizio e di fine validità, e l’id_utente del titolare della carta. L’id_utente è una chiave esterna che fa riferimento all’id nella tabella degli utenti.

punti: Questa tabella registra i punti guadagnati dagli utenti. Ogni record ha un id, un timestamp (ts) che indica quando i punti sono stati guadagnati, l’importo dei punti e l’id_fidelity della carta fedeltà a cui i punti sono stati accreditati. L’id_fidelity è una chiave esterna che fa riferimento all’id nella tabella delle fidelity_card.

Queste tabelle permettono di gestire un sistema di carte fedeltà, tenendo traccia degli utenti, delle loro carte e dei punti che accumulano. Le chiavi esterne (id_utente e id_fidelity) permettono di collegare le tabelle tra loro, creando relazioni tra gli utenti, le loro carte fedeltà e i punti che guadagnano.

Modello Concettuale

punti	fidelity_card	utenti
id PK	id PK	id PK
ts	data_inizio	nome
importo	data_fine	cognome
id_fidelity FK	id_utente FK	email
note	tot_punti	password
	attiva	data
		ruolo
		cellulare
		username UN
		codice UN

Modello Logico

punti(id, ts, importo, id_fidelity)

fidelity_card(id, data_inizio, data_fine, id_utente)

utenti(id, nome, cognome, email, password, data, ruolo, cellulare, username, codice)

API

Introduzione alle API

Le API sono scritte in linguaggio Java utilizzando il framework Spring Boot. Inoltre, Liquibase viene utilizzato per l'inizializzazione e la gestione delle migrazioni del database, mentre il driver JDBC di MariaDB viene impiegato per la connessione al database MariaDB.

API UTILIZZATE:

Api di Autenticazione

AuthController è un controller di Spring Boot che gestisce operazioni relative all'autenticazione come la registrazione e il login degli utenti.
Fornisce due endpoint principali: uno per la registrazione degli utenti e l'altro per il login degli utenti. Questo controller è mappato su /api/auth

Registrare un Utente:
- Inviare una richiesta POST a /api/auth/register con un corpo JSON contenente username, password, nome, cognome, email, data, cellulare.
  Ricevere una risposta con i dati dell'utente ed un token, con un codice di stato "200" se la richiesta è andata a buon fine ed un codice di stato "403" se la richiesta non è andata a buon fine
Effettuare il Login di un Utente:
- Inviare una richiesta POST a /api/auth/login con un corpo JSON contenente username e password.
  Ricevere una risposta con i dati dell'utente un token ed un code, un codice di stato "200" se la richiesta è andata a buon fine ed un codice di stato "403" se la richiesta non è andata a buon fine
Api di gestione Fidelity Card

FidelityCardController è un controller di Spring Boot che gestisce operazioni relative alle fidelity card, come ottenere le fidelity card di un utente, ottenere la fidelity card attiva di un utente, impostare punti manualmente e ottenere punti per codice.
Questo controller è mappato su /api

1. Ottenere tutte le Fidelity Card di un Utente:
- Inviare una richiesta GET a /api/all-fidelity/{user-id}
  Ricevere una risposta JSON con una lista di tutte fidelity card dell'utente specificato.
2. Ottenere la Fidelity Card Attiva di un Utente:
- Inviare una richiesta GET a /api/fidelity/{user-id}
  Ricevere una risposta JSON con la fidelity card attiva dell'utente specificato.
3. Impostare Punti Manualmente:
- Inviare una richiesta POST a /api/set-point-manually con un corpo JSON contenente fidelityCardId e points.
  Ricevere una risposta JSON con i dettagli aggiornati della fidelity card.
4. Ottenere Punti per Codice:
- Inviare una richiesta GET a /api/point/{codice}
  Ricevere una risposta JSON con i punti associati al codice specificato.
Api di gestione dei punti dellaFidelity Card

PuntiController è un controller di Spring Boot che gestisce operazioni relative ai punti fedeltà, come aggiungere punti a un account fedeltà. Questo controller è mappato su /api/punti

Aggiungere Punti:
- Inviare una richiesta POST a /api/punti/add-point con un corpo JSON contenente codice e points.
- Ricevere una risposta JSON con un messaggio di conferma.
Api di gestione degli Utenti

UtenteController è un controller di Spring Boot che gestisce operazioni relative agli utenti come ottenere i dettagli di un singolo utente e ottenere la lista di tutti gli utenti.
Questo controller è mappato su /api

1. Ottenere i Dettagli di un Utente per ID:
- Inviare una richiesta GET a /api/user/{id}
  Ricevere una risposta JSON con i dettagli dell'utente specificato
2. Ottenere la Lista di Tutti gli Utenti:
- Inviare una richiesta GET a /api/user-list
  Ricevere una risposta JSON con la lista di tutti gli utenti
API Qr Code

La servlet
https://api.qrserver.com/v1/create-qr-code/?data=${this.codice}&size=360x360&margin=30
è un servizio esterno che genera codici QR a partire da un testo fornito. In questo caso, l'app MyFidelity utilizza questa servlet per creare un codice QR basato su un input di testo specifico.

Ecco come funziona:

Input del Testo: L'app MyFidelity fornisce un testo (ad esempio, un URL, un messaggio o un identificatore) che deve essere convertito in un codice QR.
Parametri della Servlet:
- data: Il testo fornito viene passato come parametro nella parte finale dell'URL. Ad esempio, ${this.codice} rappresenta il testo da convertire.
- size: Specifica la dimensione del codice QR (in pixel). Nel caso specifico, è impostato su 360x360.
- margin: Specifica il margine intorno al codice QR (in pixel). Qui è impostato su 30.
Generazione del Codice QR: La servlet "https://api.qrserver.com/v1/create-qr-code/" riceve il testo fornito e crea un'immagine del codice QR corrispondente con le dimensioni e i margini specificati.
Esempio di Richiesta POST:
- Per generare un codice QR tramite una richiesta POST, l'app MyFidelity dovrebbe inviare una richiesta HTTP POST all'URL della servlet con il testo da convertire come corpo della richiesta.
- L'app potrebbe inviare una richiesta POST simile a questa:
```
POST https://api.qrserver.com/v1/create-qr-code/
Content-Type: application/x-www-form-urlencoded

data=testo
&size=360x360
&margin=30
```
  Dove testo rappresenta il testo da trasformare nel codice QR.
  
  Risultato prodotto
Salvataggio dell'Immagine: Una volta ottenuta l'immagine del codice QR dalla servlet, l'app MyFidelity può utilizzarla direttamente nell'interfaccia utente.

Sviluppo backend

Prima di tutto bisogna sistemare l'ambiente di sviluppo installando Java, MariaDB e le dependencies di Spring Boot per lo sviluppo del backend di MyFidelity.

Installazione di Java e MariaDB

Bisogna installare in base al proprio sistema operativo gli strumenti necessari:

Winget (Windows 10/11)

winget install --id=Oracle.JDK.21  -e

winget install --id=MariaDB.Server  -e

Homebrew (MacOS/Linux)

brew install openjdk

brew install mariadb
brew services start mariadb

Clonazione della Repository del Progetto

Dopo aver installato Java e MariaDB ed essersi accertati di aver impostato la variabile di path JAVA_HOME, è possibile clonare la repository del progetto utilizzando il tuo client Git. Il comando per farlo è il seguente:

git clone -b develop https://gitlab.com/5ci-li-megghiu/myfidelity-be

Installazione delle Dipendenze del Progetto

Una volta clonato il progetto, entra nella cartella del progetto e apri il terminale di sistema per installare le dipendenze. Questo include l'installazione delle dependencies di Spring. I comandi per farlo sono i seguenti:

Installazione delle dipendenze di Spring Boot

Le dipendenze di Spring Boot possono essere gestite attraverso un file pom.xml il progetto fa utilizzo di Maven per gestire le dependencies. Dopo aver configurato correttamente gli strumenti necessari, puoi installare le dipendenze con:
```
./mvnw install
```
Creazione database necessario per l'esecuzione del progetto

Ecco i passaggi per creare il database in MariaDB:
1. Avvia MariaDB: Apri il terminale (o il prompt dei comandi in Windows) e digita mysql -u root -p. Premi invio, quindi inserisci la password di root quando richiesto.
2. Crea il database: Una volta entrato nel prompt di MariaDB, digita il seguente comando per creare il database:
```
CREATE DATABASE fidelity_db;
```
  Premi invio per eseguire il comando.
3. Verifica la creazione del database: Per assicurarti che il database sia stato creato correttamente, puoi elencare tutti i database con il comando:
```
SHOW DATABASES;
```
Dovresti vedere "fidelity_db" nell'elenco dei database.
1. Uscita: Quando hai finito, puoi uscire da MariaDB digitando exit e premendo invio.
Esecuzione del Progetto

Per eseguire il progetto sul tuo sistema locale, utilizza il seguente comando:
```
./mvnw spring-boot:run
```
Questo avvierà il server di sviluppo e potrai visualizzare nel terminale di esecuzione che il server sarà operativo con successo alla porta 8080.