# Checklist: Da Design a Prototipo Giocabile

**Obiettivo**: Qualcuno clona il repo e in <30 min gioca un turno.
**Target**: Singolo utente, browser, esecuzione locale on-premise.

---

## Fase 0 — Setup Progetto (priorità: critica)

- [ ] `git init` nella directory /home/codex/rpg/
- [ ] Struttura directory (src/, tests/, data/, frontend/)
- [ ] `requirements.txt`: FastAPI, uvicorn, ollama-python, aiohttp
- [ ] `docker-compose.yml` opzionale (per isolamento)
- [ ] Script `start.sh` / `start.bat` che avvia tutto con un comando
- [ ] `.gitignore`: dcc/pdf_pages/, __pycache__, *.db

---

## Fase 1 — Backend Core (priorità: critica)

### 1.1 State Machine
- [ ] `src/engine/state_machine.py`: orchestratore turni (Leggi -> LLM -> Valida -> Esegui -> Scrivi)
- [ ] Retry logic con backoff esponenziale + jitter
- [ ] Idempotenza: cache risultati per turn_id
- [ ] Safe fallback narrativo su errore

### 1.2 SQLite / Stato Gioco
- [ ] `src/engine/db.py`: connessione, init schema, migrazioni
- [ ] Implementare schema: campaign, characters, adventure_state, quest_log, turn_log
- [ ] CRUD base per ogni tabella
- [ ] Backup automatico (copia .db a ogni avvio)

### 1.3 Approved Tools (10)
- [ ] `roll-dice`: d20, d%, d24, catena dadi, modificatori
- [ ] `combat`: iniziativa, attacco, mighty-deed, furtivo, critico, fumble
- [ ] `ability-check`: abilità ladro (con dado dedicato) e altri (d20+mod)
- [ ] `saving-throw`: Tempra/Riflessi/Volontà
- [ ] `movement`: esplorazione stanze, distanza, incontri
- [ ] `spellcasting`: prova incantesimo, tabella risultati, corruzione/ritorsione
- [ ] `update-inventory`: aggiungi/rimuovi/equipaggia
- [ ] `award-xp`: 0-4 PE per incontro, avanzamento livello
- [ ] `update-quest`: stato missioni
- [ ] `dm-override`: modifica stato, forza risultato, ignora regola

---

## Fase 2 — LLM Integration (priorità: critica)

- [ ] `src/llm/client.py`: wrapper chiamate Ollama API (gemma2:9b)
- [ ] `src/llm/prompts.py`: template system prompt con:
  - Regole fondamentali (d20, CD/CA, catena dadi)
  - Approved Tools (nome, parametri, quando usarli)
  - Mappa avventura (aree, CD, statistiche mostri)
  - Regole classi (Dado Cimento, abilità ladro, ecc.)
- [ ] `src/llm/parser.py`: parsing risposta LLM -> tool calls strutturati
- [ ] Tool calling: filtraggio tool contro allowlist + validazione parametri
- [ ] Test: chiamata singola a Ollama, verificare risposta in italiano

---

## Fase 3 — Avventura Machine-Readable (priorità: alta)

- [ ] `data/adventure/areas.json`: tutte le 9 aree con descrizione, CD, mostri, tesori
- [ ] `data/adventure/monsters.json`: tutte le creature con statistiche complete
- [ ] `data/adventure/items.json`: oggetti recuperabili (corno demoniaco, soldatini, ecc.)
- [ ] `data/adventure/quests.json`: quest principale + secondaria della driade
- [x] Completare Aree 1.1, 1.3 e 1.9 (mancano) — scrivere descrizioni originali ispirate al tema
- [x] Completare pagina 39 (setup avventura, plot hook: Vorkhul Ksh'tharan, il Vincolato alle Stelle)
- [x] Completare tabelle equipaggiamento (armi, armature, equipaggiamento — tradotte dal Reference Booklet)
- [x] Completa tabella critici (I-V) e fumble in italiano (tradotta dal Reference Booklet)
- [x] Completa tabella mestieri d100 (tradotta dal Reference Booklet)
- [x] Completa tabelle classi + abilità ladro + mighty deeds (tradotte dal Reference Booklet)

---

## Fase 4 — Frontend (priorità: alta)

- [ ] `frontend/index.html`: pagina singola con chat + pannello stato
- [ ] `frontend/style.css`: tema scuro DCC, leggibile, essenziale
- [ ] `frontend/app.js`: connessione WebSocket/Fetch al backend
- [ ] Pannello stato personaggi (PF, classe, PE, equipaggiamento)
- [ ] Pannello mappa (aree visitate/da visitare)
- [ ] Log azioni recenti (ultimi N turni)
- [ ] Input testuale per azioni giocatore
- [ ] DM-Override: pulsante per attivare modalità DM + comandi
- [ ] Adattamento mobile (giocabile da telefono)

---

## Fase 5 — Colmare Gap OCR (priorità: media)

- [x] Recuperare pagina 39: scritta ex-novo (Vorkhul Ksh'tharan background)
- [x] Estrarre strutturalmente le tabelle critici/fumble (formato Markdown, tradotte dal Reference Booklet)
- [x] Completare tabella equipaggiamento (Reference Booklet → Italiano)
- [ ] Ripetere OCR pagine 1-2 con pre-processing (contrasto, bianco/nero)
- [ ] Completare risultati incantesimi fascia alta (20-31+) da screenshot

---

## Fase 6 — Testing (priorità: media)

- [ ] `tests/test_tools.py`: test unitari per ogni Approved Tool
  - roll-dice: distribuzione, catena dadi, modificatori
  - combat: critico/fumble, mighty-deed, CA
  - ability-check: dado ladro vs d20 standard
  - spellcasting: corruzione, ritorsione, tabella risultati
- [ ] `tests/test_state_machine.py`: flusso completo di un turno
- [ ] `tests/test_avventura.py`: integrità dati (aree collegabili, mostri referenziati)
- [ ] `tests/test_llm_parser.py`: parsing risposte LLM, filtraggio allowlist

---

## Fase 7 — Documentazione (priorità: media)

- [ ] `README.md` aggiornato con "Come avviare":
  - Prerequisiti (Python 3.11+, Ollama in esecuzione)
  - `pip install -r requirements.txt`
  - `python start.py`
  - Aprire browser a http://localhost:8000
- [ ] `docs/setup.md`: configurazione Ollama, gestione API key
- [ ] `docs/architettura.md`: diagramma flusso, spiegazione pattern NSL
- [ ] `docs/dm-guide.md`: come usare DM-Override, comandi disponibili

---

## Fase 8 — Rifiniture (priorità: bassa)

- [ ] Rate limiting azioni (anti-spam)
- [ ] Salvataggio automatico ogni N turni
- [ ] Logging strutturato (token usage, latenza, errori)
- [ ] Backup automatico SQLite
- [ ] Supporto "setaccio": 4 personaggi per giocatore da gestire in UI
- [ ] Excalidraw/mappa visuale delle stanze
- [ ] Effetti sonori (opzionale, per atmosfera)

---

## Riepilogo Tempo Stimato

| Fase | Ore | Priorità |
|------|-----|----------|
| 0 — Setup Progetto | 0.5 | 🔴 Critica |
| 1 — Backend Core | 4-6 | 🔴 Critica |
| 2 — LLM Integration | 2-3 | 🔴 Critica |
| 3 — Avventura Machine-Readable | 2-3 | 🟡 Alta |
| 4 — Frontend | 3-4 | 🟡 Alta |
| 5 — Gap OCR | 2 | 🟠 Media |
| 6 — Testing | 2 | 🟠 Media |
| 7 — Documentazione | 1 | 🟠 Media |
| 8 — Rifiniture | 2-3 | 🔵 Bassa |

**Totale**: ~18-25 ore per MVP giocabile da altri.