# Spec di design — Fase 2: Vetrina pubblica + Anagrafiche

**Data:** 2026-06-08 · **Stato:** approvato (design) · **Autore:** Claude + Paolo
**Base:** [`2026-06-07-tta-piattaforma-design.md`](2026-06-07-tta-piattaforma-design.md) (spec generale) · stack/ADR [`../../decisioni/2026-06-07-stack-architettura.md`](../../decisioni/2026-06-07-stack-architettura.md)
**Premessa:** Fase 1 (fondamenta: SvelteKit + Neon/Drizzle + Better Auth + tema + test) è completata e in produzione (`main`). Questa Fase 2 costruisce la parte **"contenitore"**, indipendente dalla formula tornei ancora indecisa.

---

## 1. Obiettivo e ambito
Consegnare un **sito pubblico vero e completo** + le **anagrafiche giocatore**, usando i contenuti già presenti nel repo, senza dipendere da migrazione/engine.

**Dentro (le pagine "verdi"):**
- **Vetrina**: Home, Eventi, Regolamento, Albo d'Oro, Community.
- **Anagrafica**: profilo giocatore (modifica nick TtA / nick TdG / email) + collegamento `Player`↔`User`.

**Fuori (rimandato a fasi successive perché dipende da dati/engine):**
- **Classifiche live** e **Dashboard partite/calendario/ranking** → richiedono il motore eventi (Fase 3-4).
- **Collegamento allo storico (claim, opzione A)** → richiede la migrazione dei ~177 giocatori (fase dedicata; richiede ri-accesso al workbook Excel via MCP Drive).
- `/eventi/[slug]` di dettaglio per singolo format → YAGNI per ora.

## 2. Approccio ai contenuti (decisione d'impianto)
I contenuti curati vivono come **moduli statici committati**, NON nel DB:
- `src/lib/content/events.ts` — i format (Bolgia estiva/autunnale, Torneo Generale, Duello, Palio, Supercoppa): nome, descrizione, periodo, formato sintetico. (Fonte: `data/sorgenti/*`.)
- `src/lib/content/albo.ts` — albo d'oro (vincitori per competizione/anno). (Fonte: `data/sorgenti/trello-tta-goblin.md` + `workbook-xlsx-mappa.md`.) Tipizzato.
- `src/lib/content/community.ts` — link (Telegram, goblins.net, ecc.).
- **Regolamento**: reso dal markdown `data/sorgenti/regolamento-v1.5.md` (via `mdsvex` o import del testo) in `/regolamento`.

Le pagine vetrina sono **prerendered (SSG)** (`export const prerender = true`) → veloci, SEO, **zero dipendenza da DB**. Quando arriveranno engine/migrazione, le pagine dinamiche leggeranno dal DB; l'albo potrà migrare lì senza cambiare la UI (stessi componenti).

> Razionale: i dati sono curati e quasi statici; tenerli come moduli tipizzati evita una dipendenza dalla migrazione e mantiene la Fase 2 sbloccata e semplice.

## 3. Architettura — Vetrina (piano 2a)
Route pubbliche **prerendered**:
- `/` — Home: hero, sezione "I nostri tornei" (card dai `events.ts`), "Albo d'Oro — ultimi vincitori" (teaser da `albo.ts`), strip community. *(struttura approvata dal mockup)*
- `/eventi` — i format come sezioni/card (da `events.ts`).
- `/regolamento` — testo del regolamento (da markdown).
- `/albo` — albo d'oro completo per competizione (da `albo.ts`), reso con un componente **tabella** riusabile.
- `/community` — link e risorse.

Componenti riusabili in `src/lib/components/`: `Section`, `Card`, `Badge`, `DataTable` (riusabile poi per le classifiche), oltre a `Header`/`Footer` già esistenti. Tutto sul sistema **pergamena+civiltà** (token già in `app.css`).

## 4. Architettura — Anagrafiche (piano 2b)
- **Collegamento `Player`↔`User`**: alla registrazione si crea una riga `player` collegata allo `user`, con `nome_app_tta` = nick scelto in fase di signup. Implementazione via **Better Auth `databaseHooks.user.create.after`** (o equivalente documentato). Gli utenti di test esistenti vengono allineati (backfill minimale o ricreazione).
- **`/profilo`** (area autenticata, guardia come la dashboard): il giocatore vede e modifica:
  - **nick TtA** (`nome_app_tta`): validazione `isValidNickname` (già esistente) + **check di unicità** server-side prima dell'update.
  - **nick TdG** (`nick_tdg`): opzionale.
  - **email**: cambio con **ri-verifica** del nuovo indirizzo (flusso `changeEmail` di Better Auth).
- Le scritture passano da **azioni server / endpoint server-only** con validazione prima dell'update (mai fidarsi del client).

## 5. Decomposizione in piani
Due plan indipendenti, ognuno consegna software funzionante e testabile:
- **Piano 2a — Vetrina** (pubblica, niente auth): moduli contenuto + route prerendered + componenti. **Si costruisce per primo.**
- **Piano 2b — Anagrafiche** (auth): wiring `Player`↔`User` + `/profilo` con validazioni.

## 6. Design / UI
Alla costruzione si attiva la skill **`frontend-design`** (o `impeccable`) per i componenti reali; il mockup della Home è solo direzione. Sistema **pergamena + civiltà** (token in `src/app.css`), **responsive**, titoli serif + testo sans. I 4 colori giocatore restano solo funzionali (non servono in Fase 2 finché non ci sono partite/posti).

## 7. Test
- Unit sui **moduli contenuto** (forma/coerenza dei dati: ogni evento ha i campi attesi; albo ben formato).
- Unit sulla logica **nick** (validazione già testata + nuova funzione/uso per l'**unicità**).
- Le pagine vetrina sono prevalentemente **visive**: smoke di rendering opzionale (la pagina monta senza errori). `pnpm check` e `pnpm build` restano gate.

## 8. Fuori scope / rimandato (riepilogo)
Classifiche live, dashboard partite/calendario/ranking, claim allo storico, migrazione completa (~177 giocatori), `/eventi/[slug]`, notifiche, PWA. Restano alle fasi 3+ (motore eventi) e alla fase di migrazione.

## 9. Note tecniche ereditate
- `neon-http` non supporta transazioni (vedi ADR §Limiti noti): non rilevante in Fase 2 (scritture profilo = singola riga), da tenere presente per Fase 3.
- Debito noto da valutare in Fase 2b: FK `player.user_id` → `user.id` (oggi `user_id` è `text` senza FK); guardia auth centralizzabile in `event.locals` (oggi guardia per-pagina). Entrambi opzionali, decidere nel piano 2b.