dcc-rpg/CHECKLIST.md

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
• Completare Aree 1.1, 1.3 e 1.9 (mancano) — scrivere descrizioni originali ispirate al tema
• Completare pagina 39 (setup avventura, plot hook: Vorkhul Ksh'tharan, il Vincolato alle Stelle)
• Completare tabelle equipaggiamento (armi, armature, equipaggiamento — tradotte dal Reference Booklet)
• Completa tabella critici (I-V) e fumble in italiano (tradotta dal Reference Booklet)
• Completa tabella mestieri d100 (tradotta dal Reference Booklet)
• 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)

• Recuperare pagina 39: scritta ex-novo (Vorkhul Ksh'tharan background)
• Estrarre strutturalmente le tabelle critici/fumble (formato Markdown, tradotte dal Reference Booklet)
• 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.