15 KiB
Registro delle decisioni di progetto
Questo documento raccoglie le decisioni importanti prese nel corso della vita di CrAPP: scelte che hanno influito sulla direzione del prodotto, sull’organizzazione del lavoro o su come l’app si evolve nel tempo.
Non descrive come è fatto il codice. Per quello esistono ARCHITECTURE.md e DATABASE.md.
Serve a rispondere a domande del tipo:
- Perché abbiamo scelto così?
- Cosa avevamo escluso e perché?
- Quando conviene riaprire una decisione?
Come usare questo registro
Ogni decisione segue lo stesso schema:
| Campo | Significato |
|---|---|
| Data | Quando la decisione è stata presa o confermata |
| Stato | Accettata · In valutazione · Sostituita · Obsoleta |
| Contesto | Quale problema o opportunità avevamo di fronte |
| Decisione | Cosa abbiamo scelto di fare |
| Alternative scartate | Cosa non abbiamo fatto e perché |
| Conseguenze | Cosa comporta nel quotidiano (utenti, admin, sviluppo) |
| Riesame | Quando ha senso riconsiderarla |
Quando aggiungere una voce
- una scelta influisce su più moduli o su più release;
- escludiamo un’alternativa non ovvia;
- accettiamo un compromesso consapevole (debito, limitazione, ritardo);
- cambiamo una decisione precedente.
Quando non serve
- dettagli implementativi locali;
- scelte estetiche minori;
- bugfix o correzioni puntuali.
Decisioni accettate
DD-001 — CrAPP deve restare indipendente da Lovable
Data: luglio 2026
Stato: Accettata
Contesto
Il progetto nasce come prototipo su Lovable Cloud. Per crescere serve controllo su codice, deploy, database e costi.
Decisione
Spostare lo sviluppo su repository GitHub indipendente, con deploy su Vercel e database Supabase gestito dal team.
Alternative scartate
- Restare su Lovable come unica piattaforma → troppa dipendenza da un servizio esterno.
- Riscrivere tutto da zero → costo e rischio inutili; il prototipo funzionava già.
Conseguenze
- Maggiore libertà e responsabilità per il team.
- Restano tracce del passaggio (dipendenze, meta tag): vanno eliminate gradualmente, non in blocco.
- L’app deve poter girare anche fuori dall’ecosistema Lovable (vedi
PORTABILITA.md).
Riesame
Quando il progetto non userà più alcun componente Lovable.
DD-002 — Sviluppo document-first
Data: agosto 2026
Stato: Accettata
Contesto
Con più persone (e assistenti AI) che lavorano sul codice, serviva un modo per evitare funzionalità “inventate” al volo e incoerenze tra moduli.
Decisione
Ogni nuova funzionalità significativa viene prima progettata e documentata in docs/modules/, poi implementata. Il flusso ufficiale è: idea → progettazione → documentazione → database → codice → test → release.
Alternative scartate
- Documentare solo a posteriori → troppo spesso incompleto o assente.
- Affidarsi solo al codice come documentazione → illeggibile per chi non programma.
Conseguenze
- Rallenta leggermente l’avvio di nuove feature, ma riduce rework e discussioni infinite.
- I moduli v1.0 vanno retro-documentati quando possibile.
- Nessuna feature non documentata entra in produzione.
Riesame
Se il team diventa molto piccolo e la documentazione smette di essere consultata.
DD-003 — Due branch: main stabile, develop per il lavoro
Data: agosto 2026
Stato: Accettata
Contesto
Serve separare ciò che i giocatori usano ogni giorno da ciò che è ancora in prova.
Decisione
main→ produzione, sempre funzionante, deploy automatico.develop→ sviluppo e preview, merge sumainsolo dopo test.
Alternative scartate
- Sviluppare direttamente su
main→ rischio di rotture in produzione. - Branch per ogni feature → eccessivo per la dimensione attuale del team.
Conseguenze
- Gli utenti in produzione non vedono lavori incompleti.
- Ogni release su
maindeve includere verifica delle funzionalità esistenti.
Riesame
Se il team cresce e servono review più granulari (pull request per feature).
DD-004 — Ogni versione aggiunge, non riscrive
Data: agosto 2026
Stato: Accettata
Contesto
CrAPP v1.0 è già usata dalla squadra per presenze, calendario, scout, badge e notifiche. Rischiare regressioni su moduli funzionanti vanifica la fiducia degli utenti.
Decisione
Le nuove versioni introducono funzionalità. Non si riscrive un modulo già operativo salvo richiesta esplicita e pianificata.
Alternative scartate
- Refactoring ampio “per pulire” insieme a ogni release → alto rischio, poco valore immediato per gli utenti.
Conseguenze
- Coesistono temporaneamente soluzioni vecchie e nuove (es. dati hardcoded accanto a tabelle database).
- Il debito tecnico va gestito con migration dedicate, non di nascosto.
Riesame
Quando un modulo diventa ingestibile o blocca una release importante.
DD-005 — Mobile-first, pochi click, pochi schermi
Data: origine progetto
Stato: Accettata
Contesto
I giocatori usano l’app soprattutto da smartphone, spesso in spogliatoio o in palestra, con poco tempo e poca pazienza.
Decisione
Interfaccia semplice, veloce, ottimizzata per telefono. Navigazione ridotta (barra inferiore). Ogni schermata deve avere uno scopo chiaro.
Alternative scartate
- Layout da desktop con menu complessi → scomodo in mobilità.
- App nativa iOS/Android → costi e tempi di pubblicazione non giustificati per una squadra amatoriale.
Conseguenze
- Funzionalità amministrative complesse vanno semplificate o suddivise con cura.
- La PWA è la forma giusta per questo pubblico.
Riesame
Se emergono esigenze desktop forti (es. gestione documenti massiva solo da PC).
DD-006 — Intelligenza artificiale solo se porta beneficio reale
Data: origine progetto
Stato: Accettata
Contesto
L’AI è attraente ma può complicare l’app, aumentare i costi e creare aspettative irrealistiche.
Decisione
Usare l’AI solo quando riduce lavoro agli admin o migliora concretamente l’esperienza dei giocatori. Non introdurla “perché si può”.
Alternative scartate
- AI ovunque (chatbot, suggerimenti automatici, analisi predittive) → fuori focus per una squadra amatoriale.
Conseguenze
- “AI Allenamenti” è in roadmap v1.2, non v1.1.
- Ogni proposta AI va valutata con la domanda: chi risparmia tempo e quanto?
Riesame
Quando l’AI diventa economica e affidabile per casi d’uso chiari (es. generazione allenamenti).
DD-007 — Badge calcolati dall’app, non salvati nel database
Data: origine progetto
Stato: Accettata
Contesto
I badge dipendono da statistiche già disponibili (presenze, MVP, cacche, ecc.). Salvare ogni badge sbloccato nel database aggiungerebbe complessità senza beneficio immediato.
Decisione
I badge vengono calcolati al volo dall’applicazione in base ai dati esistenti. Non esiste una tabella badge dedicata.
Alternative scartate
- Tabella
badge_sbloccaticon storico → utile in futuro per notifiche retroattive o audit, ma non necessaria ora.
Conseguenze
- Meno migration e meno sincronizzazione.
- Lo “sblocco” celebrativo usa cache locale per non ripetere animazioni.
- Un eventuale storico badge richiederà una nuova decisione.
Riesame
Se servono badge manuali assegnati dagli admin o storico immutabile.
DD-008 — Gamification equa tra ruoli
Data: origine progetto
Stato: Accettata
Contesto
In pallavolo i ruoli hanno statistiche diverse (un libero non segna punti d’attacco). Confrontare tutti sugli stessi numeri sarebbe ingiusto e scoraggiante.
Decisione
Le statistiche personali in profilo e squadra devono essere eque per tutti i ruoli. Dati tecnici di reparto (punti, ace, muri) restano nello Scout Live come informazione di squadra, non come leva competitiva individuale.
Alternative scartate
- Classifiche individuali basate su punti → penalizza libero, palleggiatore, centrale.
Conseguenze
- Badge e obiettivi usano presenze, MVP, pagelle, serie, cacche — metriche accessibili a tutti.
- Lo scout resta strumento tecnico, non gioco.
Riesame
Se la squadra chiede esplicitamente classifiche tecniche per ruolo.
DD-009 — Tesseramento CSI manuale in v1.1, integrazione API in v2.0
Data: agosto 2026
Stato: Accettata
Contesto
La v1.1 deve aiutare gli admin a raccogliere documenti e dati per il tesseramento CSI. Un collegamento automatico al sistema CSI è complesso e non urgente.
Decisione
- v1.1: profilo completo, dashboard admin, download documenti, export CSV con i campi richiesti dal CSI.
- v2.0: eventuale collegamento automatico a CSI (calendario, risultati, classifica ufficiale).
Alternative scartate
- Integrazione CSI già in v1.1 → scope troppo ampio, dipendenza da API esterne non controllate.
Conseguenze
- Gli admin guadagnano subito tempo (niente più Excel e chat per i documenti).
- L’export CSV deve essere affidabile e completo: è il deliverable chiave della v1.1.
Riesame
Quando il CSI mette a disposizione API stabili o quando il volume di tesseramenti giustifica l’automazione.
DD-010 — Profilo giocatore: niente storico certificati in v1
Data: agosto 2026
Stato: Accettata
Contesto
Il certificato medico va aggiornato ogni stagione. Tenere lo storico di tutte le versioni complica upload, storage e privacy.
Decisione
In v1 il giocatore può sovrascrivere certificato e data di scadenza. Lo storico delle versioni precedenti non viene conservato.
Alternative scartate
- Archivio certificati → utile per audit, rinviato a versioni future.
Conseguenze
- Implementazione più semplice e veloce.
- Gli admin vedono solo il certificato attuale.
- Va comunicato chiaramente ai giocatori che sostituire il file elimina quello precedente.
Riesame
Se il CSI o il regolamento interno richiedono conservazione storica.
DD-011 — Autenticazione reale prima del profilo amministrativo completo
Data: agosto 2026
Stato: Accettata
Contesto
Oggi l’app identifica l’utente con la selezione del giocatore da una lista, senza login. Documenti, certificati e dati personali richiedono sapere chi sta operando e impedire accessi non autorizzati.
Decisione
Prima di completare il modulo Profilo Giocatore (v1.1), introdurre login con Google o email tramite Supabase Auth — non tramite Lovable Auth. Dopo il login, il giocatore associa il proprio profilo squadra.
Alternative scartate
- Continuare solo con selezione da lista → inaccettabile per dati sensibili.
- Lovable Auth → crea dipendenza da piattaforma che stiamo abbandonando.
Conseguenze
- Tutti dovranno fare login almeno una volta.
- Gli admin useranno ruoli veri (
user_roles), non una lista di nomi hardcoded. - È prerequisito per dashboard admin e export CSI.
Riesame
Dopo il rollout auth, se emergono problemi di adozione (giocatori poco digitali).
DD-012 — Non migrare gli ID giocatore in v1.1
Data: agosto 2026
Stato: Accettata
Contesto
L’app usa identificativi semplici (g1, g2, …) collegati a presenze, voti, palloni e altre funzioni già in uso. Nel database esiste anche una tabella giocatori con UUID, non collegata al codice attuale.
Decisione
Per la v1.1 non unificare gli ID. I nuovi dati del profilo si agganciano agli identificativi già in uso. La migrazione verso UUID resta un lavoro separato, pianificato e testato.
Alternative scartate
- Migrare tutto a UUID in v1.1 → rischio alto di rompere presenze, voti, scout e notifiche.
Conseguenze
- Coesistono due modelli anagrafici fino a migration dedicata.
DATABASE.mdva tenuto aggiornato su cosa è “attivo” e cosa è “futuro”.
Riesame
Quando la v1.1 è stabile e c’è tempo per una migration con checklist regressioni completa.
DD-013 — Portabilità: l’app non deve dipendere da servizi esclusivi
Data: luglio 2026
Stato: Accettata
Contesto
La squadra potrebbe voler cambiare hosting, database o fornitore auth in futuro.
Decisione
CrAPP deve poter girare su Node.js + PostgreSQL standard. Niente funzionalità bloccate su servizi proprietari. I dati si accedono solo tramite moduli in src/lib/, non direttamente dai componenti.
Alternative scartate
- Accettare lock-in per velocità → contrario alla lunga vita del progetto.
Conseguenze
- Supabase va bene perché è PostgreSQL e self-hostable.
- Le API push e i job restano endpoint HTTP richiamabili da qualsiasi scheduler.
Riesame
Se si adotta un servizio che viola questa regola.
Decisioni in valutazione
DD-014 — Convergenza schema database (eventi e presenze)
Data: —
Stato: In valutazione
Contesto
Esistono due modelli paralleli: tabelle “legacy” usate dall’app (eventi_app, risposte_presenze) e tabelle “nuove” con autenticazione e vincoli (eventi, presenze, giocatori UUID).
Decisione proposta
Unificare gradualmente sul modello autenticato, dopo auth e profilo stabili.
Perché non ora
Rischio regressioni su calendario e presenze, moduli più usati della squadra.
Riesame previsto
Post v1.1, con migration e test dedicati.
DD-015 — Rosa anagrafica: da codice hardcoded a database
Data: —
Stato: In valutazione
Contesto
La lista giocatori vive ancora nel codice sorgente. Il database ha già una tabella popolata ma non usata.
Decisione proposta
Spostare l’anagrafica su database, mantenendo gli stessi ID finché non si fa DD-012.
Perché non ora
Il profilo v1.1 può agganciarsi agli ID attuali; la migrazione rosa può essere fase 2.
Riesame previsto
In parallelo o subito dopo il rollout auth.
Template per nuove decisioni
Copiare questo blocco in fondo al documento quando serve registrare una nuova scelta.
DD-XXX — [Titolo breve della decisione]
Data:
Stato: Accettata · In valutazione · Sostituita · Obsoleta
Contesto
[Quale problema stavamo risolvendo?]
Decisione
[Cosa abbiamo scelto?]
Alternative scartate
- [Alternativa 1] → [perché no]
- [Alternativa 2] → [perché no]
Conseguenze
[Cosa cambia per utenti, admin e team di sviluppo]
Riesame
[Quando o in quali condizioni rivedere la decisione]
Indice rapido
| ID | Titolo | Stato |
|---|---|---|
| DD-001 | Indipendenza da Lovable | Accettata |
| DD-002 | Sviluppo document-first | Accettata |
| DD-003 | Branch main / develop | Accettata |
| DD-004 | Ogni versione aggiunge, non riscrive | Accettata |
| DD-005 | Mobile-first | Accettata |
| DD-006 | AI solo se utile | Accettata |
| DD-007 | Badge calcolati, non in DB | Accettata |
| DD-008 | Gamification equa tra ruoli | Accettata |
| DD-009 | CSI manuale v1.1, API v2.0 | Accettata |
| DD-010 | Niente storico certificati v1 | Accettata |
| DD-011 | Auth reale prima del profilo | Accettata |
| DD-012 | Non migrare ID in v1.1 | Accettata |
| DD-013 | Portabilità dello stack | Accettata |
| DD-014 | Convergenza schema DB | In valutazione |
| DD-015 | Rosa da hardcoded a DB | In valutazione |
Ultimo aggiornamento: 7 agosto 2026