public-clubsy

Carga de estrutura desportiva por modelo (CSV)

Objetivo

Permitir a carga massiva de categorias, ligas e equipas na temporada ativa do clube a partir de um modelo CSV.

Este guia documenta o comportamento real implementado no ecra de estrutura desportiva.

Onde se usa

• Ecra: SportStructureScreen
• Botao: Importar modelo CSV
• Requisito: utilizador com permissoes de gestao do clube e ecra em modo edicao.

Ficheiros de referencia

• Modelo base: sport_structure_import_template_pt.csv

Formato obrigatorio do CSV

Cabecalhos requeridos (nesta ordem recomendada):

entity,name,category,league

Colunas

• entity: tipo de linha. Valores permitidos:
  • category
  • league
  • team
• name: nome principal da entidade.
• category: obrigatorio apenas quando entity=team.
• league: obrigatorio apenas quando entity=team.

Regras de validacao

A importacao valida antes de inserir:

1. O ficheiro deve ter pelo menos cabecalho + 1 linha de dados.
2. Devem existir as colunas entity e name.
3. Se entity=team, category e league sao obrigatorios.
4. entity fora de category|league|team e erro.
5. Para equipas, categoria/liga devem existir:
   • na BD da temporada ativa, ou
   • no mesmo ficheiro (se criadas em linhas category/league).

Se houver erros de validacao, a importacao nao e executada e e mostrado um resumo de erros.

Comportamento de insercao

• Categorias novas: inseridas se nao existirem na temporada ativa (comparacao normalizada por nome).
• Ligas novas: mesmo criterio.
• Equipas novas: inseridas se nao existir combinacao equivalente de nome+categoria+liga.
• Nao elimina registos existentes.
• Nao atualiza nomes existentes (modo append/upsert parcial orientado a criacao).

Normalizacao de texto

Antes de comparar/inserir:

• aplica-se trim;
• espacos multiplos colapsam em um.

Exemplo:

• " Senior A " -> "Senior A"

Exemplo valido

entity,name,category,league
category,Senior,,
category,Juvenil,,
league,Ouro,,
league,Prata,,
team,Equipa Senior A,Senior,Ouro
team,Equipa Senior B,Senior,Prata
team,Equipa Juvenil A,Juvenil,Prata

Resultado esperado:

• Categorias criadas: 2 (se nao existiam)
• Ligas criadas: 2 (se nao existiam)
• Equipas criadas: 3 (se nao existiam)

Exemplo invalido

entity,name,category,league
team,Equipa sem liga,Senior,
foo,Registo desconhecido,,
team,,Senior,Ouro
team,Equipa com referencia em falta,Sub13,Ouro

Erros esperados:

• linha com team sem league;
• entity invalido (foo);
• name vazio;
• referencia a categoria inexistente (Sub13).

Fluxo recomendado de operacao

1. Descarregar modelo base.
2. Completar categorias e ligas primeiro.
3. Completar equipas referenciando nomes exatos de categoria/liga.
4. Importar modelo.
5. Rever resumo de criacao.
6. Repetir se houver erros com dados corrigidos.

Boas praticas

• Manter nomes consistentes (ex. Juvenil A, Juvenil B).
• Evitar variantes tipograficas para a mesma entidade.
• Carregar por blocos (primeiro estrutura simples, depois ampliacoes).

Alcance atual

Esta importacao cobre:

• categorias
• ligas
• equipas

Ainda nao cobre:

• atribuicao massiva de membros
• carga de player_profile
• atualizacao/eliminacao massiva

Troubleshooting

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

O cabecalho nao coincide. Verificar primeira linha.

“Template has no data”

O ficheiro tem apenas cabecalho ou esta vazio.

“team requires category and league”

Linha de equipa incompleta.

“category/league does not exist”

Adicionar linha de criacao no mesmo CSV ou criar antes na app.