Back-end: Guide for developers - Edit by Luca Marasca, Matteo Lupini, Nicolò Ruggeri
- 1. Banca Unicam: Back-End Guide for Developers Development Team September 2017 1
- 2. 1 Introduction Backend Questa guida si riferisce alla parte back-end del sito, ovvero un server web di risposta alle richieste di dati e informazioni poste dal browser tramite gli script del front-end. I dati richiesti sono principalmente informazioni salvate in un database, realizzato tramite MongoDB o elaborazioni di esse. Il backend di un sito web `e la parte relativa all’amministrazione dello stesso, parte amministrativa dalla quale `e possibile creare – modificare articoli e contenuti, impostazioni del sito web o portale che sia e cos`ı via. L’accesso al backend `e garantito tramite una procedura di identificazione, chiamata anche ‘login’ o log-in’, che si concretizza nell’immissione di username e password, accesso a livello di amministratore del sito web. Al backend di un sito web `e correlato il frontend ovvero l’interfaccia pubblica del sito stesso, visibile a tutti coloro che lo navigheranno, la quale si presenter`a con dei contenuti di testo, multimediali, grafici ecc... 1.1 Software utilizzati Per la realizzazione della parte back-end `e stato utilizzato Node.js, un runtime JavaScript bastato sul motore JavaScript V8 di Chrome, questo framework uti- lizza un modello di I/O non bloccante ad eventi cos`ı da poter rimanere efficiente anche quando sottoposto a richieste multiple. Oltre a Node.js `e stato utilizzato MongoDB per la realizzazione del database. (vedere documentazione db) 1.2 JWT JWT sta per JSON Web Token. Si tratta di uno standard che viene usato per ”regolare” le richieste tra due parti che possono essere un’applicazione ed il server a cui fa riferimento. un JWT `e divisibile in tre parti: • 1-Header: l’intestazione. Contiene delle informazioni sul token stesso e su come `e stato criptato; • 2-Payload: il corpo vero e proprio che contiene dei dati ”variabili” in base al contesto; • 3-Signature: una firma che contiene un hash dell’header, del payload ed un ”secret” conosciuto solo dai server dell’applicazione; Il token viene generato tramite la ricezione di una ”parola o frase” chiamata secret; essa viene convertita in base 64 (header e payload) e successivamente tramite la cifratura HMACSHA256 viene generato il vero e proprio token che sar`a diverso in base ai dati che vengono passati e al momento in cui viene generato. 1.3 Moduli • Morgan `e utilizzato per scrivere a console 2
- 3. • body-parser Serve per utilizzare il json all’ interno delle chiamate e delle risposte del server • express `e un framework per applicazione in node.js e fornisce servizi prin- cipalmente http e funzionalit`a per i middleware • nodemailer `e utilizzato per inviare e-mail • jsonwebtoken `e utilizzato per usufruire dei token • moment `e utilizzato per calcolare la differenza tra oggetti di tipo data • fs `e utilizzato per la gestione dei file memorizzati su disco 1.4 Route Il server `e diviso in varie route, ogni route ha lo scopo specifico di rispondere a determinate richieste, alcune di esse sono accessibili soltanto tramite aut- enticazione via JWT, ovvero il server richiede un token di autenticazione per assicurarsi dell’ identit`a del richiedente. Di seguito, sono elencate le varie route: • La route ”./” `E la route principale del server, `e stata configurata per creare 3 account di default per verificarne il corretto funzionamento. Gli account creati sono due utenti normali ed uno admin, vengono inoltre aggiunte tre transazioni di prova tra i due utenti normali. • La route ”./verify” `e una route di risposta a richieste http di tipo GET, prende in input tramite una query-string l’id della richiesta di autenti- cazione email e la convalida associandola all’ account precedentemente creato in modo tale da attivarlo. • La route ”/list” `e una route di test, quando viene chiamata risponde con un array in Json contenente i dati di tutti gli utenti registrati nel database. Ovviamente la cancellazione di tale route non influisce sul corretto fun- zionamento del server. • La route ”/get-avvisi” `e utilizzata per il salvataggio delle immagini degli utenti nel server (non funziona sulla demo in heroku). Per il salvataggio delle immagini nel server si utilizza un middleware multiparty che perme- tte il salvataggio di file in locale ed in seguito si chiama una funzione per lo spostamento di essa nel corretto percorso. • La route ”/SignUp” `e una route di risposta a richieste http di tipo POST, prende in input i dati di registrazione (email, pin, password e immagine), ne verifica la correttezza e in caso le salva nel database ed invia un email (con link di attivazione) in attesa della convalidazione o risponde con un messaggio di errore (es: email gi`a in uso). • La route ”/uploadPic”, viene invocata nel caso in cui si decida di modifi- cate l’immagine del profilo 3
- 4. • La route POST /api/authenticate ´E la prima api route, ancora non ne- cessita di JWT per essere utilizzata ma prendendo in input nome utente e password e se corretti genera il token per le prossime autenticazioni. • (Da questa route in poi si necessita sempre del JWT in ingresso per es- eguire le risposte.) La route POST /api/userData non necessita di dati in input e risponde con tutte le informazioni relative all’ utente loggato (lo stesso a cui `e associato il token). • La route POST /api/userDataNAccount `e identica alla precedente con la sola differenza che il numero di conto di cui restituire le informazioni viene preso in ingresso. • La route POST /api/updateUserData `e utilizzata per aggiornare i dati inerenti a uno user (e-mail, password ecc...). • La route POST /api/Movements ritorna la lista dei movimenti in ingresso e in uscita dell’ utente loggato. • La route POST /api/invio-bonifico-admin `e invocata nel caso in cui un admin debba effettuare un bonifico tra due utenti. • La route POST /api//invio-bonifico-user `e invocata nel caso in cui uno user debba effettuare un bonifico ad un altro user • La route POST /api/CalcolaMediaUscite Ritorna alla parte front-end la media delle uscite dello user loggato. • La route POST /api/CalcolaMediaEntrate Ritorna alla parte front-end la media delle entrate dello user loggato. • La route POST /api/invio-avviso `e invocata nel momento in cui un admin abbia la necessit`a di effettuare una comunicazione agli user (admin e non) presenti all’ interno del Database. L’avviso viene aggiunto al database, e successivamente viene spedita ad ogni cliente della banca. • La route POST /api/deleteAlert viene invocata nel caso in cui un admin abbia la necessit`a di eliminare un avviso scritto in precedenza dal DB (in questo caso, non verr`a inviata un ulteriore e-mail) • La route POST /api/off `e invocata nel caso in cui vi sia la necessit`a da parte di un admin di disabilitare un utente che per diversi motivi possa non necessitare pi`u della registrazione al sito web. • La route POST /api/on `e invocata nel caso in cui un utente richieda nuovamente i servigi della banca dopo che abbia deciso di farsi disabilitare l’account • La route POST /api/InserisciPin-admin viene invocata nel caso in cui un amministratore debba registrare un nuovo utente nel DB 4
- 5. 2 Introduzione Database Il database, come da consegna, `e stato gestito con mongo DB che funziona in record costituiti da documenti, senza restrizioni con l’unico vincolo che un doc- umento deve essere al massimo di 16MB. Questi documenti sono memorizzati nel formato JSON e per ogni collezione (oggetto) viene definito uno schema con i campi dell’oggetto. La peculiarit`a di mongo `e che ha una gestione asin- crona quindi tutte le funzioni necessitano di callback, inoltre per evitare sovrac- carico di ogni connessione al termine di ogni funzione la connessione al database viene chiusa. Nel progetto tutta la gestione del database `e stata fatta nel file database.js in cui, in primo luogo, sono state scaricate le dipendenze di mongo e poi `e stata inserita la stringa di connessione (URL) al database. Tutte le funzioni del database sono esportate con la parola exports e poi utilizzate dal lato server. • La prima e pi`u importante funzione `e la funzione init che `e una funzione che inizializza tutto il database con le relative collezioni e controlli. • La funzione findUserByAccount, in base al numero di account passato dal server ritorna interamente l’utente in oggetto JSON dalla collezione “users”. • La funzione authenticate serve come controllo al server nel momento in cui si prova a fare il login, viene passato al database email password e il database controlla che l’email e la password inserite corrispondano con un solo record all’interno del database nella collezione “users”. (inoltre viene controllato se il profilo utente `e attivo o meno mediante il controllo di un booleano). • La funzione addUser `e una funzione che prende l’oggetto JSON utente (come viene definito dallo schema) e lo inserisce tramite un add al database nella collezione “users”. (vengono controllati alcuni campi per mettere dei valori di default nel caso non siano stati definiti). • La funzione addTransaction `e una funzione che prende un oggetto transazione JSON, prende l’utente che fa la transazione e l’utente che riceve la transazione dalla collezione “users” e aggiunge da una parte e toglie dall’altra l’ammontare della transazione, infine viene aggiunta la transazione alla collezione “trans- actions”. • La funzione findUserByMail `e una funzione che prende la mail passata dal server e cerca dentro il database nella collezione “users” un utente con quella mail e fa ritornare l’utente come oggetto JSON. • La funzione verifyPin prende un oggetto JSON pin e controlla nella collezione “pins” se il pin che viene inserito dall’utente per la verifica esiste, nel caso esista torna al server la risposta true con l’oggetto pin. 5
- 6. • La funzione insertPin prende un oggetto pin JSON passato dal server e lo inserisce con add nel database nella collezione “pins”. • La funzione allMovementSend `e una funzione che prende in ingesso il nu- mero account di un profilo utente e ritorna in un array tutta la lista dei movimenti fatti in uscita da quel profilo utente presi dalla collezione “movements”. • La funzione allMovementReceived `e una funzione che prende in ingesso il numero account di un profilo utente e ritorna in un array tutta la lista dei movimenti ricevuti a quel profilo utente presi dalla collezione “move- ments”. • La funzione deleteRecordPin `e una funzione che prende in ingresso un numero di pin e cancella il record di quel pin. • La funzione findMaxNumberOfAccount `e la funzione che torna il numero pi`u alto del numero di account in maniera tale che non ci siano numeri di account duplicati. • La funzione verifyMail `e una funzione che cerca nella collezione “users” e controlla che non ci sia la mail presente nel database. • La funzione sortUsersByNumberOfAccount `e una funzione che tramite la parola sort permette di ordinare dalla collezione “users” gli utenti per numero di account in maniera discendente. • La funzione addAdvise `e una funzione che prende un oggetto JSON avviso e tramite add lo inserisce nella collezione “advises”. • La funzione returnLastFiveAdvises `e una funzione che ritorna gli ultimi 5 avvisi mediante la data di creazione nella collezione “advises”. • Le funzioni activateAccount e disactivateAccount servono rispettivamente per attivare o disattivare il booleano che controlla se il profilo `e attivo o non attivo. • Le funzioni sumCashOutside e sumCashInside prendono dalla collezione “movements” la somma delle quantit`a in uscita o in entrata di ogni profilo utente (richiedono il numero di account). • La funzione modifyCredential `e una funzione che nella collezione “users” fa l’update delle credenziali che l’utente decide modificare del suo profilo. • La funzione addUserToVerify `e una funzione che tramite la add aggiunge alla collezione “userToVerify” un utente da verificare. • La funzione findUserByLink `e una funzione che dato un link trova all’interno della collezione “userToVerify” il relativo utente e lo restituisce al server. 6
- 7. • La funzione deleteUserToVerify elimina il record di un utente da verificare all’interno della collezione “userToVerify”. • La funzione updateCash `e una funzione che prende l’utente JSON e il nuovo saldo che dovr`a avere l’utente sul conto. • La funzione allAdvise ritorna una lista di tutti gli avvisi che vengono presi all’interno della collezione “advises”. La funzione deleteAdvise `e una funzione che elimina un avviso in base al suo numero. • La funzione returnMaxNumber ritorna il numero pi`u alto degli avvisi. 2.1 Schemi Lo schema del database `e stato diviso in 5 collezioni: users, movements, pins, advises e userToVerify. In ogni collezione sono stati definiti i campi presenti e con le parole chiave required (rende richiesto un campo), unique (rende unico un campo) e defualt (mette un valore ad un campo di default). Inoltre in ogni collezione `e stato inserito il tipo di quel campo. Successivamente gli schemi sono usati dal server per creare gli oggetti JSON e per lavorare con le funzioni del database. 7