CRAPP/docs/decisions/DD-016.md

DD-016 — Schema dati Profilo Giocatore (F0)

Data: agosto 2026
Stato: Accettata

Contesto
La progettazione F0 del modulo Profilo Giocatore ha definito come persistere dati personali, documenti e certificati, in coesistenza con l’anagrafica attuale (g1…g17 nel codice) e con la tabella giocatori UUID già presente ma non usata. Serviva una scelta chiara su dove salvare i dati, come collegare l’autenticazione e come proteggere documenti sensibili — senza toccare le tabelle preesistenti già operative.

Decisione
Si introducono due nuove tabelle additive:

• giocatori_squadra — anagrafica squadra con ID testuali (g1…g17), dati gestiti dagli admin (nome, cognome, numero, ruolo) e collegamento account (auth_user_id).
• profili_giocatore — dati personali, metadati documento identità, certificato medico e path dei file, in relazione 1:1 con giocatori_squadra.

Regole vincolanti:

1. giocatori_squadra diventa progressivamente la source of truth per l’anagrafica squadra. Durante la transizione, crapp-data.ts resta come fallback se il database non è disponibile o i dati non sono ancora migrati.
2. L’associazione auth_user_id ↔ giocatore è un’operazione controllata e atomica (es. al primo accesso da /benvenuto, con UPDATE … WHERE auth_user_id IS NULL). Il giocatore non può modificare liberamente auth_user_id; solo un admin può resettarlo in casi eccezionali.
3. I file (documento identità, certificato, foto tessera) vivono nel bucket Storage profili-giocatore, configurato come privato.
4. Documenti personali e sanitari non devono mai essere esposti tramite URL pubblici. Accesso solo tramite client autenticato con policy RLS, o signed URL a scadenza breve per download admin.
5. Le tabelle preesistenti non vengono modificate (eventi_app, risposte_presenze, voti, palloni, scout, push, ecc.). Il profilo si aggancia agli ID g1…g17 già in uso, senza migrare verso UUID per ora (coerente con DD-012).
6. La tabella giocatori (UUID) resta invariata e non usata dal modulo profilo.

Alternative scartate

• Estendere la tabella giocatori UUID → conflitto con ID operativi del codice e rischio di regressioni.
• Salvare file come base64 nel database → ingestibile, difficile da gestire e da scaricare.
• Bucket pubblico con URL permanenti → inaccettabile per dati sanitari e documenti d’identità.
• Permettere al giocatore di cambiare auth_user_id liberamente → rischio di impersonazione e race condition.
• Modificare le tabelle preesistenti per aggiungere FK verso il profilo → viola DD-004 e DD-012.

Conseguenze

• Coesistono temporaneamente tre rappresentazioni dell’anagrafica: crapp-data.ts (fallback), giocatori_squadra (target), giocatori UUID (dormiente).
• src/lib/rosa.ts legge dal database e ricade su crapp-data.ts in caso di errore o assenza dati (DD-015).
• Il completamento profilo (30/30/30/10) si calcola in app, non si persiste nel database.
• Lo storico certificati non viene conservato (coerente con DD-010).
• Le migration M1–M2 (tabelle, RLS, bucket) restano additive: solo CREATE, nessun ALTER/DROP su schema esistente.
• Raffina e attua quanto proposto in DD-015 per la rosa anagrafica, senza sostituire formalmente quella voce.

Riesame

• Quando giocatori_squadra è stabile in produzione e il fallback crapp-data.ts non serve più.
• Quando si pianifica la convergenza verso UUID (DD-012, dopo che il profilo sarà stabile).
• Se il CSI o il regolamento richiedono conservazione storica documenti o consensi privacy dedicati.