cat swift/scegliere-progetto-finale-requisiti.md

Lezione 72 60 min

Scegliere il progetto finale e fissare i requisiti

Impostare un progetto finale Swift non giocattolo: obiettivi, vincoli, scope, requisiti funzionali e criteri di qualità.

Il progetto finale non deve dimostrare che sai scrivere codice Swift. Deve dimostrare che sai progettare un piccolo sistema Swift.

Un progetto valido attraversa:

  • dominio modellato bene;
  • dati esterni o persistenza;
  • concurrency;
  • error handling;
  • test;
  • package/module separation;
  • documentazione;
  • una piccola interfaccia SwiftUI, CLI o API server.

La tentazione è scegliere qualcosa di enorme. Invece serve un progetto abbastanza piccolo da finire e abbastanza reale da mettere pressione sulle decisioni.

Criteri di scelta

Un buon progetto finale ha:

  • almeno 4-6 tipi di dominio;
  • almeno 2 use case;
  • almeno 1 fonte dati esterna o persistente;
  • almeno 3 errori significativi;
  • almeno 1 flusso async;
  • almeno 1 test double;
  • almeno 1 confine tra dominio e infrastruttura;
  • una consegna visibile: CLI, SwiftUI screen, SDK pubblico o route server.

Se il progetto può essere fatto tutto in un singolo file, è troppo piccolo.

Se richiede login, pagamenti, notifiche push, database complesso e sync multi-device, è troppo grande per il capstone.

Progetti consigliati

Client GitHub o Hacker News

Costruisci un client che:

  • cerca repository o storie;
  • mostra dettaglio;
  • gestisce paginazione;
  • salva cache;
  • supporta refresh e cancellazione;
  • espone una CLI o piccola UI.

Concetti coperti:

  • networking;
  • JSON reale;
  • errori HTTP;
  • cache;
  • concurrency;
  • test async.

Budget personale

Costruisci un motore per:

  • entrate e uscite;
  • categorie;
  • budget mensile;
  • saldo;
  • import/export JSON;
  • report essenziale.

Concetti coperti:

  • modellazione dominio;
  • invarianti;
  • persistenza locale;
  • test di regole;
  • CLI o SwiftUI.

Motore prenotazioni

Costruisci un dominio per:

  • risorse prenotabili;
  • intervalli temporali;
  • disponibilità;
  • conflitti;
  • regole di cancellazione;
  • costo.

Concetti coperti:

  • value types;
  • pattern matching;
  • errori di dominio;
  • test edge case;
  • server route opzionale.

SDK meteo o finanza

Costruisci una libreria che:

  • consuma una API;
  • espone modelli puliti;
  • mappa errori;
  • gestisce retry e cache;
  • documenta API pubblica.

Concetti coperti:

  • library authoring;
  • Codable avanzato;
  • URLSession;
  • DocC;
  • SemVer.

Task manager offline-first

Costruisci:

  • task;
  • progetti;
  • priorità;
  • salvataggio locale;
  • sync simulato;
  • conflitti semplici.

Concetti coperti:

  • architettura;
  • cache;
  • repository;
  • concurrency;
  • UI o CLI.

Requisiti funzionali

Scrivi requisiti come comportamenti osservabili.

Buono:

L'utente può cercare storie per parola chiave.
Il sistema mostra risultati cached se la rete fallisce.
Un task completato resta completato dopo riavvio.
Una prenotazione non può sovrapporsi a una esistente.

Debole:

Usare SwiftUI.
Usare URLSession.
Avere una classe Manager.
Fare una bella architettura.

Tecnologie e pattern sono mezzi, non requisiti.

Requisiti non funzionali

Il capstone deve includere vincoli di qualità:

Il dominio deve essere testabile senza rete.
La cache deve essere sostituibile nei test.
La cancellazione di un caricamento non deve diventare errore generico.
Il package deve compilare con Swift 6.x.
Le API pubbliche devono avere documentazione minima.

Questi requisiti trasformano il progetto da tutorial a lavoro serio.

Scope: must, should, could

Definisci lo scope in tre livelli.

Must
  ricerca, dettaglio, cache, errori, test use case

Should
  paginazione, retry, DocC, CLI JSON output

Could
  UI più ricca, filtri avanzati, esportazione CSV

Finisci prima i must. Il progetto finale non deve naufragare per feature secondarie.

Definition of Done

La consegna è completa quando:

  • il package compila;
  • i test passano;
  • il dominio è separato da infrastruttura;
  • esiste una demo eseguibile;
  • gli errori principali sono gestiti;
  • la documentazione spiega come usare il progetto;
  • il README contiene istruzioni di avvio;
  • la struttura dei moduli è comprensibile.

Documento iniziale

Crea un file PROJECT.md con:

# Progetto finale

## Problema

## Utente

## Must

## Should

## Could

## Architettura prevista

## Rischi

## Definition of Done

Non è burocrazia. È una protezione contro lo scope creep.

Checklist

Prima di scrivere codice:

  • hai scelto un dominio concreto?
  • hai definito 3-5 must?
  • hai escluso feature troppo grandi?
  • sai quale sarà la demo finale?
  • sai quali parti devono essere testate?
  • sai dove entra la rete o la persistenza?
  • sai quale traccia applicativa userai?

Esercizio

Scegli uno dei progetti consigliati e scrivi PROJECT.md.

Poi aggiungi:

  1. cinque requisiti funzionali;
  2. cinque requisiti non funzionali;
  3. tre rischi tecnici;
  4. una demo finale;
  5. una Definition of Done verificabile.

Obiettivo: un altro studente deve poter leggere il file è capire cosa costruirai senza chiederti spiegazioni.