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.
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
| File | Cosa c'è | Si tocca? |
|---|---|---|
ritrovato/ | La cartella del progetto: app/, tests/, schema.sql, CANVAS.md, README.md | Sì: app/. I test e lo schema no |
ritrovato/tests/ | I test, uno per pezzo. Girano su un database loro | No |
dati_veri.sql | Quello che Nives ha ricopiato dagli scatoloni: va nel TUO database | No |
verifica.py | Nives controlla la tua risposta | No |
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:
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/docsIl 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.
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'è.)- Scrivi il pezzo: lo stampo, la rotta, il router montato in
app/main.py. pytest -k livello_1finché è verde. Poilivello_2, e così via.- Provalo in
/docs, sul tuo database, con i dati di Nives. git add .egit commit, poigit switch mainegit 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.
| Livello | Il pezzo | Cosa c'è di nuovo |
|---|---|---|
| 1 | GET /stazioni | il giro completo, con la rotta più piccola che c'è: un file di rotte nuovo e il router da montare |
| 2 | GET /oggetti: gli oggetti in deposito | lo stampo pubblico, senza il segno particolare |
| 3 | GET /oggetti con i filtri: stazione, categoria, giorno | i filtri facoltativi, un where alla volta |
| 4 | GET /oggetti/{oggetto_id}: la scheda | un percorso con l'id e il 404 |
| 5 | POST /oggetti: registro un oggetto | un valore finto, con il suo nome: registrato_da = 1 |
| 6 | POST /oggetti/{oggetto_id}/restituzioni: restituisco | due 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?
python ../verifica.py "Nome della stazione"Se è sbagliata, Nives ti dà un consiglio. Se è giusta, ti dice «Oggetto ritrovato».