210 lines
4.3 KiB
Markdown
210 lines
4.3 KiB
Markdown
# Contratto JSON del Cruciverba
|
|
|
|
Questo documento definisce il formato di scambio tra:
|
|
|
|
- `brain`: il motore che genera e compila il cruciverba
|
|
- `client`: web app, backend, servizio PDF o altra macchina remota che richiede un cruciverba
|
|
|
|
L'obiettivo e' avere un payload:
|
|
|
|
- completo
|
|
- stabile
|
|
- espandibile
|
|
- riusabile per stampa PDF, gioco web e archiviazione
|
|
|
|
## Flusso
|
|
|
|
1. Il client invia una `request` JSON al motore.
|
|
2. Il motore risponde con una `response` JSON completa del cruciverba.
|
|
3. Lo stesso JSON di risposta puo' essere:
|
|
- salvato a database
|
|
- convertito in PDF
|
|
- renderizzato in una pagina web interattiva
|
|
- riaperto in futuro senza rigenerare il cruciverba
|
|
|
|
## Principi di progettazione
|
|
|
|
- Ogni cruciverba ha un `crossword_id` univoco.
|
|
- La `request` conserva i parametri di generazione originali.
|
|
- La `response` include sia la griglia giocabile sia la soluzione.
|
|
- Le parole hanno metadati ricchi: posizione, direzione, clue, tema, pos, fonte clue.
|
|
- Le coordinate sono sempre assolute e 0-based nella griglia normalizzata esportata.
|
|
- La griglia esportata e' rettangolare e normalizzata: niente coordinate negative.
|
|
- Il formato supporta versioning con `schema_version`.
|
|
|
|
## Request
|
|
|
|
Campi principali:
|
|
|
|
- `schema_version`: versione del contratto
|
|
- `request_id`: id della richiesta lato client
|
|
- `requested_at`: timestamp ISO 8601
|
|
- `generator`: configurazione del motore
|
|
- `output`: preferenze di output
|
|
- `client_context`: metadati opzionali del chiamante
|
|
|
|
### `generator`
|
|
|
|
- `topic`: stringa o lista di topic
|
|
- `difficulty`: alias testuale
|
|
- `seed`: opzionale, per riproducibilita'
|
|
- `initial_word_count`
|
|
- `themed_fill_count`
|
|
- `target_empty_ratio`
|
|
- `diffxy`
|
|
- `time_limit_seconds`
|
|
- `max_candidates_per_word`
|
|
- `lexicon_file`
|
|
- `definitions_enabled`
|
|
- `definition_style`: per future varianti clue
|
|
- `preferred_output_language`
|
|
|
|
### `output`
|
|
|
|
- `include_solution_grid`
|
|
- `include_clue_sources`
|
|
- `include_diagnostics`
|
|
- `include_generation_log`
|
|
- `format_hints`
|
|
|
|
## Response
|
|
|
|
Campi principali:
|
|
|
|
- `schema_version`
|
|
- `request_id`
|
|
- `crossword_id`
|
|
- `generated_at`
|
|
- `status`
|
|
- `generator`
|
|
- `summary`
|
|
- `grid`
|
|
- `entries`
|
|
- `clues`
|
|
- `solution`
|
|
- `diagnostics`
|
|
- `artifacts`
|
|
|
|
## Sezione `grid`
|
|
|
|
- `rows`
|
|
- `cols`
|
|
- `cell_size_hint`
|
|
- `cells`
|
|
|
|
Ogni cella ha:
|
|
|
|
- `row`
|
|
- `col`
|
|
- `kind`: `block` oppure `letter`
|
|
- `solution`
|
|
- `display`
|
|
- `number`: numero clue se la cella apre una parola
|
|
- `across_entry_id`
|
|
- `down_entry_id`
|
|
- `is_prefilled`
|
|
|
|
Note:
|
|
|
|
- `solution` contiene sempre la lettera corretta per celle attive.
|
|
- `display` e' vuoto per la scheda giocatore.
|
|
- `number` serve per numerazione in stampa e web.
|
|
|
|
## Sezione `entries`
|
|
|
|
Ogni entry rappresenta una parola collocata in griglia.
|
|
|
|
Campi:
|
|
|
|
- `entry_id`
|
|
- `number`
|
|
- `direction`: `across` o `down`
|
|
- `answer`
|
|
- `answer_length`
|
|
- `row`
|
|
- `col`
|
|
- `cells`: lista coordinate
|
|
- `clue`
|
|
- `clue_source`
|
|
- `topics`
|
|
- `pos`
|
|
- `is_seed`
|
|
- `added_by_filler`
|
|
- `confidence`
|
|
|
|
## Sezione `clues`
|
|
|
|
Ridondante ma utile per client semplici.
|
|
|
|
- `across`: lista clues orizzontali
|
|
- `down`: lista clues verticali
|
|
|
|
Ogni clue:
|
|
|
|
- `number`
|
|
- `entry_id`
|
|
- `text`
|
|
- `enumeration`
|
|
- `topic_match`
|
|
- `source`
|
|
|
|
## Sezione `solution`
|
|
|
|
- `grid_rows`: lista di stringhe, una per riga
|
|
- `words`: elenco risposte
|
|
|
|
`grid_rows` usa:
|
|
|
|
- lettera maiuscola per cella piena
|
|
- `#` per casella nera
|
|
|
|
## Sezione `diagnostics`
|
|
|
|
Serve a tuning, benchmark e debug.
|
|
|
|
- `total_words`
|
|
- `seed_words_requested`
|
|
- `seed_words_placed`
|
|
- `filler_words_added`
|
|
- `intersections`
|
|
- `filled_cells`
|
|
- `empty_cells`
|
|
- `empty_ratio`
|
|
- `target_empty_ratio`
|
|
- `topic_words`
|
|
- `off_topic_words`
|
|
- `pos_counts`
|
|
- `runtime_lexicon`
|
|
- `seed`
|
|
- `generation_seconds`
|
|
|
|
## Sezione `artifacts`
|
|
|
|
URL o path futuri per file derivati.
|
|
|
|
- `pdf_player`
|
|
- `pdf_solution`
|
|
- `thumbnail`
|
|
- `html_preview`
|
|
|
|
## Estensioni future previste
|
|
|
|
- `difficulty_profile`: facile/medio/difficile per definizioni separate
|
|
- `hints`: aiuti progressivi per singola parola
|
|
- `theme_story`: testo introduttivo del cruciverba
|
|
- `player_state`: salvataggio partita in corso
|
|
- `stats`: tempi, errori, percentuali di completamento
|
|
|
|
## Regola pratica consigliata
|
|
|
|
La macchina "brain" deve esporre almeno due endpoint logici:
|
|
|
|
- `POST /crosswords/generate`
|
|
- input: request JSON
|
|
- output: response JSON
|
|
|
|
- `GET /crosswords/{crossword_id}`
|
|
- output: stessa response JSON salvata
|
|
|
|
In questo modo il contratto resta identico sia via file sia via webservice.
|