Vai al contenuto
code-to-code

Apro l'indice…

↑ ↓ per scegliere, Invio per aprire, Esc per chiudere

Il progetto5. Un pezzo alla voltap. 159

Ritrovato

L'ufficio oggetti smarriti della Linea Menta, un pezzo alla volta

  • 2–3 ore di lavoro

Milano, giovedì 19 novembre. Porta Codice, l'ufficio oggetti smarriti.

Nives Corti tiene l'ufficio oggetti smarriti della Linea Menta. Gli oggetti trovati sulla linea arrivano in scatoloni, ognuno con un cartellino scritto a mano. Chi ha perso qualcosa telefona dalle 9 alle 12, e Nives cerca a memoria: «L'ombrello giallo? Era a Vecchia Fiera, o forse a Largo Lista…»

Dopo sessanta giorni gli oggetti non ritirati vanno in beneficenza, e nessuno lo sa.

Questa mattina Nives ha ricopiato tutto in un database: stazioni, addetti, oggetti, restituzioni. Le tabelle sono pronte. Lo scheletro di un'app anche: è la cartella del capitolo La cartella del progetto, con /salute verde. Non ci sono rotte.

«Le scrivi tu», dice Nives. «Una alla volta. Ho il telefono che squilla.»

Alle 11 squilla davvero. Una signora, Greta Lombardi: «Ho perso una borsa di tela, nera, domenica 8 novembre. Non so dove: ero sulla linea tutto il giorno.»

Nives vuole sapere in quale stazione l'hanno trovata.

Gli esercizi da scaricare

Una cartella con i file da completare e i test già pronti. Come si usa: la guida in cinque passi.

progetto-un-pezzo-alla-volta.zip35 KB

Lo zip è lo stesso della palestra: la storia è nella cartella storia/, e ha il suo README.md. Il progetto sta in storia/ritrovato/.

I file

FileCosa c'èSi tocca?
ritrovato/La cartella del progetto: app/, tests/, schema.sql, CANVAS.md, README.mdSì: app/. I test e lo schema no
ritrovato/tests/I test, uno per pezzo. Girano su un database loroNo
dati_veri.sqlQuello che Nives ha ricopiato dagli scatoloni: va nel TUO databaseNo
verifica.pyNives controlla la tua rispostaNo

La cartella è quella di Ritrovato come l'hai vista nel capitolo 4: app/main.py con /salute, database.py, modelli.py (le quattro tabelle), schemi.py (OggettoNuovo e Oggetto), e rotte/oggetti.py con il suo APIRouter e un segnaposto: un GET /oggetti che risponde sempre [], e che il livello 2 trasforma nella ricerca vera. Ci sono due differenze: il test di /salute sta in tests/test_stazioni.py, con il primo pezzo, e i test usano il database progetto_un_pezzo_alla_volta_test, non ritrovato_test.

Una volta sola

Dalla cartella dello zip, con il venv acceso, dopo i comandi del README.md principale:

Terminale
createdb ritrovato                           # il TUO database (se risponde already exists, va bene)
psql -d ritrovato -f storia/ritrovato/schema.sql
psql -d ritrovato -f storia/dati_veri.sql    # i dati di Nives
cd storia/ritrovato
cp .env.example .env                         # DATABASE_URL: il tuo database, non quello dei test
fastapi dev app/main.py                      # poi http://127.0.0.1:8000/docs

Il server occupa il terminale: per i test (pytest, sempre dalla cartella storia/ritrovato/) ne serve un secondo, con il venv acceso. Se vuoi ricominciare da capo con i dati, psql -d ritrovato -f storia/dati_veri.sql rimette tutto com'era (anche quello che hai scritto con la tua API).

Come si gioca

Un livello alla volta. Ogni livello è un pezzo, e il pezzo è finito quando sono vere tutte e tre le cose del capitolo: il test è verde, l'hai provato in /docs, è nel commit.

  1. git switch -c livello-1-stazioni: un ramo per pezzo. (Nella cartella dello zip, prima volta: git init, e un commit con quello che c'è.)
  2. Scrivi il pezzo: lo stampo, la rotta, il router montato in app/main.py.
  3. pytest -k livello_1 finché è verde. Poi livello_2, e così via.
  4. Provalo in /docs, sul tuo database, con i dati di Nives.
  5. git add . e git commit, poi git switch main e git merge livello-1-stazioni.

I test usano altre stazioni e altri oggetti: non ti dicono niente della telefonata. Per quella, guarda i dati veri, con la tua API.

I sei livelli

Una cosa nuova per livello.

LivelloIl pezzoCosa c'è di nuovo
1GET /stazioniil giro completo, con la rotta più piccola che c'è: un file di rotte nuovo e il router da montare
2GET /oggetti: gli oggetti in depositolo stampo pubblico, senza il segno particolare
3GET /oggetti con i filtri: stazione, categoria, giornoi filtri facoltativi, un where alla volta
4GET /oggetti/{oggetto_id}: la schedaun percorso con l'id e il 404
5POST /oggetti: registro un oggettoun valore finto, con il suo nome: registrato_da = 1
6POST /oggetti/{oggetto_id}/restituzioni: restituiscodue scritture in una transazione e il 409

Gli stampi e le classi del database ci sono già, tranne quelli del livello 1 e del livello 6: quelli li scrivi tu, in schemi.py.

Cosa detta Nives

  • Livello 5. Un oggetto arrivato in ritardo: Tullio Fabbri, il collega, l'ha tenuto in tasca fino a stamattina. Una borsa di tela, colore nera, categoria borse, trovata domenica 8 novembre (2026-11-08) a Vecchia Fiera (il suo numero lo trovi con la rotta del livello 1). Segno particolare: «cerniera rotta».
  • Livello 6. «Un signore, Corrado Bassi, ha ritirato stamattina la borsa di tela nera di Piazza Query: la toppa a forma di stella combaciava. Ultime cifre del documento: 4471.» Trovala con la ricerca del livello 3 (Piazza Query, borse, 2026-11-08) e registra la restituzione.

Il segno particolare non si vede dall'API pubblica: lo vede solo l'addetto, ed è il motivo per cui Nives sa che la toppa a forma di stella è quella giusta. Tu dei segni, dalla tua API, non vedrai niente.

Il finale

Quando hai fatto tutti i livelli, rileggi la telefonata: una borsa di tela, nera, trovata domenica 8 novembre. Cerca con i filtri, guarda cosa resta nell'elenco: in quale stazione si trova la borsa della signora Lombardi?

Terminale
python ../verifica.py "Nome della stazione"

Se è sbagliata, Nives ti dà un consiglio. Se è giusta, ti dice «Oggetto ritrovato».