public-clubsy

Sport Structure Upload via Template (CSV)

Goal

Enable bulk upload of categories, leagues, and teams in the club active season from a CSV template.

This guide documents the actual implemented behavior in the sport structure screen.

Where it is used

• Screen: SportStructureScreen
• Button: Import CSV template
• Requirement: user with club management permissions and screen in edit mode.

Reference files

• Base template: sport_structure_import_template_en.csv

Required CSV format

Required headers (recommended order):

entity,name,category,league

Columns

• entity: row type. Allowed values:
  • category
  • league
  • team
• name: main entity name.
• category: required only when entity=team.
• league: required only when entity=team.

Validation rules

Import validates before insert:

1. File must contain at least header + 1 data row.
2. Columns entity and name must exist.
3. If entity=team, category and league are required.
4. entity outside category|league|team is an error.
5. For teams, category/league must exist:
   • in active season DB, or
   • in the same file (if created as category/league rows).

If validation errors exist, import is not executed and an error summary is shown.

Insert behavior

• New categories: inserted if they do not exist in active season (normalized name comparison).
• New leagues: same criteria.
• New teams: inserted if equivalent name+category+league combination does not exist.
• Existing records are not deleted.
• Existing names are not updated (append/partial upsert mode focused on new records).

Text normalization

Before compare/insert:

• trim is applied;
• multiple spaces collapse into one.

Example:

• " Senior A " -> "Senior A"

Valid example

entity,name,category,league
category,Senior,,
category,Youth,,
league,Gold,,
league,Silver,,
team,Senior Team A,Senior,Gold
team,Senior Team B,Senior,Silver
team,Youth Team A,Youth,Silver

Expected result:

• Categories created: 2 (if they did not exist)
• Leagues created: 2 (if they did not exist)
• Teams created: 3 (if they did not exist)

Invalid example

entity,name,category,league
team,Team without league,Senior,
foo,Unknown entry,,
team,,Senior,Gold
team,Team with missing reference,U13,Gold

Expected errors:

• team row without league;
• invalid entity (foo);
• empty name;
• non-existing category reference (U13).

Recommended operation flow

1. Download base template.
2. Fill categories and leagues first.
3. Fill teams referencing exact category/league names.
4. Import template.
5. Review creation summary.
6. Retry if errors with corrected data.

Best practices

• Keep consistent names (e.g. Youth A, Youth B).
• Avoid typographic variants for the same entity.
• Load in blocks (simple structure first, then expansions).

Current scope

This import covers:

• categories
• leagues
• teams

Not covered yet:

• bulk member assignment
• player_profile load
• mass update/delete

Troubleshooting

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

Header does not match. Verify first row.

“Template has no data”

File has only header or is empty.

“team requires category and league”

Incomplete team row.

“category/league does not exist”

Add creation row in same CSV or create it in app first.