public-clubsy

Caricamento struttura sportiva tramite modello (CSV)

Obiettivo

Permettere il caricamento massivo di categorie, leghe e squadre nella stagione attiva del club da un modello CSV.

Questa guida documenta il comportamento realmente implementato nella schermata struttura sportiva.

Dove si usa

• Schermata: SportStructureScreen
• Pulsante: Importa modello CSV
• Requisito: utente con permessi di gestione club e schermata in modalita modifica.

File di riferimento

• Modello base: sport_structure_import_template_it.csv

Formato obbligatorio CSV

Intestazioni richieste (ordine consigliato):

entity,name,category,league

Colonne

• entity: tipo riga. Valori consentiti:
  • category
  • league
  • team
• name: nome principale entita.
• category: obbligatoria solo quando entity=team.
• league: obbligatoria solo quando entity=team.

Regole di validazione

L’import valida prima di inserire:

1. Il file deve avere almeno intestazione + 1 riga dati.
2. Devono esistere colonne entity e name.
3. Se entity=team, category e league sono obbligatorie.
4. entity fuori da category|league|team e errore.
5. Per squadre, categoria/lega devono esistere:
   • in DB stagione attiva, oppure
   • nello stesso file (se create in righe category/league).

Se ci sono errori di validazione, l’import non viene eseguito e viene mostrato un riepilogo errori.

Comportamento inserimento

• Nuove categorie: inserite se non esistono nella stagione attiva (confronto nome normalizzato).
• Nuove leghe: stesso criterio.
• Nuove squadre: inserite se non esiste combinazione equivalente nome+categoria+lega.
• Non elimina record esistenti.
• Non aggiorna nomi esistenti (modalita append/upsert parziale orientata a nuove creazioni).

Normalizzazione testo

Prima di confrontare/inserire:

• si applica trim;
• spazi multipli collassano in uno.

Esempio:

• " Senior A " -> "Senior A"

Esempio valido

entity,name,category,league
category,Senior,,
category,Giovanile,,
league,Oro,,
league,Argento,,
team,Squadra Senior A,Senior,Oro
team,Squadra Senior B,Senior,Argento
team,Squadra Giovanile A,Giovanile,Argento

Risultato atteso:

• Categorie create: 2 (se non esistevano)
• Leghe create: 2 (se non esistevano)
• Squadre create: 3 (se non esistevano)

Esempio non valido

entity,name,category,league
team,Squadra senza lega,Senior,
foo,Voce sconosciuta,,
team,,Senior,Oro
team,Squadra con riferimento mancante,U13,Oro

Errori attesi:

• riga team senza league;
• entity non valido (foo);
• name vuoto;
• riferimento a categoria inesistente (U13).

Flusso operativo consigliato

1. Scaricare modello base.
2. Compilare prima categorie e leghe.
3. Compilare squadre referenziando nomi esatti categoria/lega.
4. Importare modello.
5. Verificare riepilogo creazione.
6. Ripetere se ci sono errori con dati corretti.

Buone pratiche

• Mantenere nomi consistenti (es. Giovanile A, Giovanile B).
• Evitare varianti tipografiche per la stessa entita.
• Caricare per blocchi (prima struttura semplice, poi ampliamenti).

Ambito attuale

Questa importazione copre:

• categorie
• leghe
• squadre

Non copre ancora:

• assegnazione massiva membri
• caricamento player_profile
• aggiornamento/cancellazione massiva

Troubleshooting

“CSV requires columns: entity,name,category,league”

L’intestazione non coincide. Verificare prima riga.

“Template has no data”

Il file ha solo intestazione o e vuoto.

“team requires category and league”

Riga squadra incompleta.

“category/league does not exist”

Aggiungere riga creazione nello stesso CSV o creare prima in app.