Carrega d'estructura esportiva per plantilla (CSV)

Objectiu

Permetre la carrega massiva de categories, lligues i equips a la temporada activa del club des d'una plantilla CSV.

Aquesta guia documenta el comportament real implementat a la pantalla d'estructura esportiva.

On s'utilitza

• Pantalla: Estructura esportiva
• Boto: Importar plantilla CSV
• Requisit: usuari amb permisos de gestio del club i pantalla en mode edicio.

Arxius de referencia

• Plantilla base: sport_structure_import_template_ca.csv

Format obligatori del CSV

Capcaleres requerides (en aquest ordre recomanat):

entity,name,category,league

Columnes

• entity: tipus de fila. Valors permesos:
  • category
  • league
  • team
• name: nom principal de l'entitat.
• category: nomes obligatori quan entity=team.
• league: nomes obligatori quan entity=team.

Regles de validacio

La importacio valida abans d'inserir:

1. L'arxiu ha de tenir almenys capcalera + 1 fila de dades.
2. Han d'existir les columnes entity i name.
3. Si entity=team, category i league son obligatoris.
4. entity fora de category|league|team es considera error.
5. Per a equips, la categoria/lliga han d'existir:
   • a la BD de la temporada activa, o
   • al mateix arxiu (si es creen en files category/league).

Si hi ha errors de validacio, no s'executa la importacio i es mostra un resum d'errors.

Comportament d'insercio

• Categories noves: s'insereixen si no existeixen a la temporada activa (comparacio normalitzada per nom).
• Lligues noves: mateix criteri.
• Equips nous: s'insereixen si no existeix combinacio equivalent de nom+categoria+lliga.
• No s'eliminen registres existents.
• No actualitza noms existents (mode append/upsert parcial orientat a altes).

Normalitzacio de text

Abans de comparar/inserir:

• s'aplica trim;
• espais multiples es col lapsen a un.

Exemple:

• " Senior A " -> "Senior A"

Exemple valid

entity,name,category,league
category,Senior,,
category,Juvenil,,
league,Or,,
league,Plata,,
team,Equip Senior A,Senior,Or
team,Equip Senior B,Senior,Plata
team,Equip Juvenil A,Juvenil,Plata

Resultat esperat:

• Categories creades: 2 (si no existien)
• Lligues creades: 2 (si no existien)
• Equips creats: 3 (si no existien)

Exemple invalid

entity,name,category,league
team,Equip sense lliga,Senior,
foo,Registre desconegut,,
team,,Senior,Or
team,Equip amb referencia faltant,Sub13,Or

Errors esperats:

• fila amb team sense league;
• entity invalid (foo);
• name buit;
• referencia a categoria inexistent (Sub13).

Flux recomanat d'operacio

1. Descarregar plantilla base.
2. Completar categories i lligues primer.
3. Completar equips referenciant noms exactes de categoria/lliga.
4. Importar plantilla.
5. Revisar resum de creacio.
6. Repetir si hi ha errors amb dades correctes.

Bones practiques

• Mantenir noms consistents (ex. Juvenil A, Juvenil B).
• Evitar variants tipografiques per a la mateixa entitat.
• Carregar per blocs (primer estructura simple, despres ampliacions).

Abast actual

Aquesta importacio cobreix:

• categories
• lligues
• equips

No cobreix encara:

• assignacio massiva de membres
• carrega de perfils de jugador
• actualitzacio/esborrat massiu

Troubleshooting

"CSV requereix columnes: entity,name,category,league"

La capcalera no coincideix. Verificar primera fila.

"Plantilla sense dades"

L'arxiu nomes te capcalera o esta buit.

"team requereix category i league"

Fila d'equip incompleta.

"categoria/lliga no existeix"

Afegir fila de creacio al mateix CSV o crear-la abans a l'app.