CRAPP/docs/DESIGN_DECISIONS.md

# 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*