00 · Apertura: il seme

Un seme di baobab può restare anni nella terra secca aspettando la pioggia. Questo modulo è l'attesa buona: preparare il terreno prima di scavare.

Come studiare

1. Leggi dall'esterno verso l'interno. Prima ciò che la persona vede (il sito, la CLI), poi l'API, poi i servizi e per ultimo il disco. Ogni strato spiega quello sotto.
2. Leggi con un test aperto accanto. La suite in testes/ non usa pytest: ogni file è uno script che monta una galassia vera in una cartella temporanea e verifica un comportamento. Il docstring in cima a ogni test racconta la storia del bug che impedisce. È la migliore documentazione del progetto.
3. I commenti sono lunghi di proposito. Quasi ogni decisione strana ha un paragrafo che spiega il bug reale che l'ha motivata. Prima di "semplificare" qualcosa, leggi il commento.
4. Studia in cerchio. Alla fine di ogni modulo ci sono domande da discutere. Il codice comunitario si impara meglio in gruppo.

Preparare l'ambiente

# backend
cd bbx-v3-back
python3 -m venv .venv && . .venv/bin/activate
pip install -r requirements.txt && pip install -e .
sudo apt install git-annex ffmpeg poppler-utils      # opzionali, per media/sync

bbx criar-galaxia "Galassia di Studio"   # crea mucua, territorio e admin
bbx api                                  # http://127.0.0.1:8000/docs

# frontend (un altro terminale)
cd bbx-v3-front
npm ci
npm run dev                              # http://localhost:5173

La password dell'admin creato si trova in ~/.baobaxia/credenciais.yaml.

Eseguire i test

bash testes/rodar_suite.sh          # tutto (≈ 5 min)
python3 testes/test_merge_bbx.py    # un solo file

I test non hanno bisogno di FastAPI, git-annex né rete: testes/_fake_fastapi.py permette di importare le rotte come funzioni normali, e un FakeSankofaBackend sostituisce git-annex con git puro. Senza faster-whisper e tesseract, quattro casi di test_enriquecimento_whisper.py falliscono — è previsto.

Nel front: npm run check (svelte-check) e npm run build.

Esercizi

1. Avvia l'API e apri /docs. Trova tre rotte che non chiedono autenticazione. Perché ognuna può essere pubblica?
2. Entra con l'admin (bbx login --usuario <admin>), crea un saber (bbx publicar foto.jpg --titulo "Prova") e apri la sua cartella in ~/.baobaxia/galaxias/. Cosa c'è dentro saber.bbx?
3. Esegui testes/test_quem_e_desambiguacao.py e leggi il docstring. Quale problema di persone reali risolve?

Da discutere

• Cosa cambia per chi programma quando la mucua sta in una scuola di quilombo, senza tecnici nei dintorni, e non in un data center?