gioco-mobile/client/README.md

# Contrabbandieri MMO — Client

Prototipo web mobile-first del client di gioco. Parla con il server (`../server`) via REST (`/api/v1`) e Socket.IO (`/ws`).

> Nota: `Blueprint_Client.md` conteneva una copia del blueprint server, quindi le scelte client (Vite + React, tema noir) sono state concordate a parte. Il client è volutamente "stupido": tutte le regole di gioco vivono sul server.

## Stack

Vite · React 19 · TypeScript · React Router · socket.io-client · CSS puro (nessuna UI library)

## Avvio

Il server deve essere attivo (vedi `../server/README.md`). Poi:

```bash
npm install
npm run dev
```

Apri `http://localhost:5173` (per provarlo da telefono sulla stessa rete: `http://<ip-del-pc>:5173`).

Se il server non è su `localhost:3000`, crea un `.env` da `.env.example` con `VITE_API_URL`.

## Schermate

- **Login/Registrazione** — JWT salvato in localStorage.
- **Covo** (home) — profilo, denaro, reputazione, barra XP, città corrente, eventi attivi, accesso alle classifiche, logout.
- **Mercato** — listino della città corrente (prezzo acquisto/vendita), eventi che influenzano i prezzi, modale compra/vendi con quantità; si auto-aggiorna a ogni tick del server via `market:updated`.
- **Missioni** — descrizioni narrative, chip per tipo, barra della probabilità di successo stimata, requisito di livello (lucchetto), bottino in merce, abbandono; attive con countdown e riscossione (esito con premi, bottino o multa).
- **Zaino** — inventario con quantità e peso totale.
- **Città** — mappa SVG stilizzata dell'Italia con marker cliccabili (colore = rischio, pulsazione = città corrente, ⚡ = evento attivo) e pannello viaggio; lista compatta come fallback.
- **Classifiche** — denaro e reputazione.

## Realtime

Alla login il client apre la connessione Socket.IO autenticata col JWT. Eventi gestiti: `market:updated` (refresh listino), `mission:completed`, `worldEvent:started`, `worldEvent:ended` (toast di notifica).

## Struttura

```
src/
├── main.tsx / App.tsx       # bootstrap, routing, route guard
├── config.ts                # VITE_API_URL
├── api/                     # http client, tipi DTO, endpoint tipizzati
├── auth/AuthContext.tsx     # sessione (token+player), localStorage, socket lifecycle
├── realtime/socket.ts       # singleton socket.io-client
├── components/              # Layout (topbar+bottom nav), Toast, Countdown
├── screens/                 # una schermata per route
├── shared/format.ts         # formattazione denaro/durate/etichette
└── styles/global.css        # tema noir (variabili CSS)
```

## Build di produzione

```bash
npm run build    # typecheck + bundle in dist/
npm run preview
```