Exam #N: "Gioco Sfortuna"

Student: s343424 Giovanni Russo

React Client Application Routes

• Route /: Pagina principale (Home). Mostra un messaggio di benvenuto e un pulsante per giocare. Agli utenti non autenticati mostra le regole del gioco, a quelli autenticati mostra la cronologia delle partite.

• Route /login: Pagina di login. Contiene il form per inserire le credenziali (email e password) e accedere.

• Route /game: Pagina della partita. Qui il giocatore visualizza le sue carte, la nuova carta da posizionare e può fare la sua scelta. Gestisce due flussi di gioco diversi: Modalità Demo (utente non loggato): La validazione della risposta avviene interamente sul client. Modalità Utente Autenticato: La validazione della risposta viene delegata al server tramite API.

• Route /end-game: Pagina di riepilogo finale della partita. Mostra l'esito della partita e le carte collezionate (iniziali e vinte).

• Route *: Pagina per route non valide (Not Found).

API Server

• POST /api/sessions

  • descrizione: esegue il login di un utente.
  • body request: { "username": "[email protected]", "password": "user_password" }
  • body response: { "id": 1, "username": "[email protected]", "name": "Nome Utente" }
  • Successo: 201 Created – restituisce informazioni utente
  • Errore: 401 Unauthorized – credenziali non valide

• DELETE /api/sessions/current

  • descrizione: esegue il logout dell'utente corrente, terminando la sessione.
  • Successo: 200 OK

• GET /api/sessions/current

  • descrizione: verifica se un utente è attualmente autenticato e ne restituisce i dati
  • body response:{ "id": 1, "username": "[email protected]", "name": "Nome Utente" }
  • Successo: 200 OK – restituisce informazioni utente
  • Errore: 401 Unauthorized – utente non autenticato

• GET /api/games/demo

  • descrizione: prepara una nuova partita in modalità demo. Restituisce 3 carte iniziali e 1 carta da giocare completa di tutti i suoi dati (incluso badness), per permettere la validazione lato client.
  • body response: { "initialCards": [...], "firstCard": {...} }
  • Successo: 200 OK – restituisce 3 carte iniziali e una carta da giocare (con badness)
  • Errore:500 Internal Server Error – non ci sono abbastanza carte nel DB

• GET /api/cards

  • descrizione:Endpoint ausiliario per recuperare tutte le carte dal database.
  • body response: Un array di oggetti carta completi.
  • Successo: 200 OK – restituisce un array di carte
  • Errore: 500 Internal Server Error – errore nel recupero dal database

• POST /api/games

  • descrizione: crea una nuova partita per un utente autenticato. Restituisce 3 carte iniziali e la prima carta da giocare (senza l'indice badness).
  • authentication: richiesta
  • request body: { "startedAt": "YYYY-MM-DD HH:mm:ss", "correctGuesses": 0, "status": "ongoing" }
  • response body:{ "gameId": 1, "initialCards": [...], "firstCard": { "id": ..., "title": ..., "imageUrl": ... }}
  • Successo: 201 Created – restituisce gameId, 3 carte iniziali e una nuova carta da giocare
  • Errore:
  • 401 Unauthorized – utente non autenticato
  • 422 Unprocessable Entity – validazione fallita (data, status, ecc.)
  • 500 Internal Server Error – errore DB o carte insufficienti
  • 404 Not Found – nessuna carta disponibile

• GET /api/games/details

  • descrizione: recupera la cronologia dettagliata di tutte le partite completate (con stato 'won' o 'lost') per l'utente autenticato. Le partite sono ordinate per data, dalla più recente alla più vecchia.
  • authentication: richiesta
  • response body: un array di oggetti partita, ciascuno con i dettagli delle carte iniziali e delle carte giocate in ogni round.

  [
  {
    "id": 1,
    "startedAt": "2025-06-15T10:20:00.000Z",
    "correctGuesses": 3,
    "status": "won",
    "initialCards": [
      {"title": "Nome Carta Iniziale 1"}
      
    ],
    "playedCards": [
      {"title": "Nome Carta Giocata 1", "roundId": 1, "won": true}
      
    ]
  }
 
  ]

• Successo: 200 OK – restituisce cronologia completa delle partite concluse

• Errore:

  • 401 Unauthorized – utente non autenticato
  • 500 Internal Server Error

• GET /api/games/:gameId/nextcard

  • descrizione: fornisce la prossima carta casuale per un nuovo round di una partita esistente (senza l'indice badness).
  • authentication: richiesta
  • request parameters: :gameId (ID della partita)
  • response body:{ "id": ..., "title": ..., "imageUrl": ... }.
  • Successo: 200 OK – restituisce la prossima carta da indovinare
  • Errore:
  • 401 Unauthorized – utente non autenticato
  • 403 Forbidden – partita non appartiene all’utente o è già conclusa
  • 404 Not Found – partita non trovata o nessuna carta disponibile
  • 500 Internal Server Error

• POST /api/games/:gameId/guess

  • descrizione:riceve e valida la scelta di un utente per un dato round. Calcola se la posizione è corretta, aggiorna il database, determina se la partita è finita (vinta/persa) e restituisce il risultato.
  • authentication: richiesta
  • request parameters: :gameId (ID della partita)
  • request body: { "cardId": 12, "guessIndex": 2 }. Un guessIndex di -1 indica un timeout.
  • response body: { "correct": boolean, "gameOver": boolean, "finalStatus": "won"|"lost"|"ongoing", "card": {...} } .
  • Successo: 200 OK – restituisce esito del round e stato aggiornato della partita
  • Errore:
  • 401 Unauthorized – utente non autenticato
  • 403 Forbidden – accesso non autorizzato alla partita
  • 404 Not Found – carta o partita non trovata
  • 409 Conflict – carta già usata nella stessa partita
  • 400 Bad Request – guessIndex non valido
  • 422 Unprocessable Entity – validazione input fallita
  • 500 Internal Server Error

Database Tables

• Table card - Contiene l'archivio di tutte le carte da gioco disponibili. Le colonne principali sono id, title, imageUrl e badness (l'indice di sfortuna).
• Table game - Salva le informazioni di ogni partita giocata. Include id, userId (foreign key per user), startedAt, correctGuesses e status ('ongoing', 'won', 'lost').
• Table user - Memorizza le credenziali degli utenti registrati. Contiene le colonne id, email, name, password (hash) e salt.
• Table round - Memorizza i dettagli di ogni singolo round giocato. Contiene id, gameId (foreign key per game), cardId (foreign key per card), roundId (l'ID progressivo del round all'interno della partita) e won (booleano).

Main React Components

• GameSummary.jsx: Mostra il riepilogo al termine di una partita. Riceve come props i dati della partita conclusa e visualizza le carte iniziali, le carte vinte/perse e il risultato finale.
• GameMatch.jsx : Gestisce l'intera logica di una partita. Riceve i dati iniziali come prop da App.jsx e gestisce il flusso dei round, il timer e la validazione delle scelte dell'utente.
• GameHistory.jsx: Visualizza la cronologia delle partite passate dell'utente. Riceve l'elenco delle partite completate e le mostra in un formato leggibile, con dettagli sulle carte coinvolte, l'esito dei round e il risultato finale.
• LoginForm.jsx (in AuthComponents.jsx): Componente dedicato al form di login. Gestisce gli input dell'utente, l'invio delle credenziali tramite API, e lo stato di attesa della risposta del server.
• GameRules.jsx,AuthComponent.jsx, DefaultLayout.jsx, NavHeader.jsx e NotFound.jsx: Sono componenti minori per gestire il flusso dell'applicazione.

Screenshot

Users Credentials

• email: [email protected], password: password (ha concluso svariate partite)
• email: [email protected], password: password (non ha nessuna partita registrata)