453 lines
15 KiB
Markdown
453 lines
15 KiB
Markdown
# 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 su `main` solo 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 `main` deve 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_sbloccati` con 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.md` va 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*
|