feat: many-to-many player-team assignments (junction table migration)

forgejo_admin commented

2026-03-20 05:38:20 +00:00

Owner

Type

Feature

Lineage

plan-wkq → Phase 11 → discovered scope (boys team announcements require multi-team players)

Repo

forgejo_admin/basketball-api

User Story

As an admin
I want to assign a player to multiple teams simultaneously
So that players like Seydou Goudiaby can be rostered on 17U Elite, Select, and Local

Context

Currently Player.team_id is a single FK to teams.id — one player, one team. Seydou Goudiaby needs to be on all three 17U boys teams. This requires a many-to-many relationship via a junction table. The draft board, roster endpoints, email queries, and team assignment routes all reference player.team_id directly and must be updated.

File Targets

Files the agent should modify or create:

src/basketball_api/models.py — add player_teams association table, update Player.teams relationship, remove Player.team_id FK
alembic/versions/xxx_player_teams_junction.py — migration: create junction table, migrate data, drop column
src/basketball_api/routes/teams.py — update assign/unassign endpoints to use junction table
src/basketball_api/routes/roster.py — update roster queries for many-to-many
src/basketball_api/routes/admin.py — update draft board GET/POST (/admin/teams, /admin/teams/save), email queries

Files the agent should NOT touch:

src/basketball_api/services/email.py — separate issue for team announcement email
Frontend code — API-only change

Acceptance Criteria

When I assign a player to multiple teams, all assignments persist
When I query a team roster, multi-team players appear on each team
When I load the admin draft board, existing assignments display correctly
When I save the draft board, multi-team assignments are preserved
Existing single-team assignments are preserved after migration (data migration step)

Test Expectations

Unit test: player can be assigned to 2+ teams via junction table
Unit test: removing one team assignment doesn't affect others
Integration test: draft board save/load round-trips with multi-team player
Integration test: roster endpoint includes multi-team players on each team
Run command: pytest tests/ -v

Constraints

Follow existing SQLAlchemy 2.0 mapped_column style in models.py
Migration must be reversible (downgrade moves first team_id back to column)
Keep player.team convenience property if possible for backwards compat during transition
tofu plan -lock=false N/A — pure API change

Checklist

PR opened
Tests pass
No unrelated changes

Westside Basketball — project
Issue #118 — team announcement email (depends on this)
Issue #115 — team creation (done)

### Type Feature ### Lineage `plan-wkq` → Phase 11 → discovered scope (boys team announcements require multi-team players) ### Repo `forgejo_admin/basketball-api` ### User Story As an admin I want to assign a player to multiple teams simultaneously So that players like Seydou Goudiaby can be rostered on 17U Elite, Select, and Local ### Context Currently `Player.team_id` is a single FK to `teams.id` — one player, one team. Seydou Goudiaby needs to be on all three 17U boys teams. This requires a many-to-many relationship via a junction table. The draft board, roster endpoints, email queries, and team assignment routes all reference `player.team_id` directly and must be updated. ### File Targets Files the agent should modify or create: - `src/basketball_api/models.py` — add `player_teams` association table, update Player.teams relationship, remove Player.team_id FK - `alembic/versions/xxx_player_teams_junction.py` — migration: create junction table, migrate data, drop column - `src/basketball_api/routes/teams.py` — update assign/unassign endpoints to use junction table - `src/basketball_api/routes/roster.py` — update roster queries for many-to-many - `src/basketball_api/routes/admin.py` — update draft board GET/POST (`/admin/teams`, `/admin/teams/save`), email queries Files the agent should NOT touch: - `src/basketball_api/services/email.py` — separate issue for team announcement email - Frontend code — API-only change ### Acceptance Criteria - [ ] When I assign a player to multiple teams, all assignments persist - [ ] When I query a team roster, multi-team players appear on each team - [ ] When I load the admin draft board, existing assignments display correctly - [ ] When I save the draft board, multi-team assignments are preserved - [ ] Existing single-team assignments are preserved after migration (data migration step) ### Test Expectations - [ ] Unit test: player can be assigned to 2+ teams via junction table - [ ] Unit test: removing one team assignment doesn't affect others - [ ] Integration test: draft board save/load round-trips with multi-team player - [ ] Integration test: roster endpoint includes multi-team players on each team - Run command: `pytest tests/ -v` ### Constraints - Follow existing SQLAlchemy 2.0 mapped_column style in models.py - Migration must be reversible (downgrade moves first team_id back to column) - Keep `player.team` convenience property if possible for backwards compat during transition - `tofu plan -lock=false` N/A — pure API change ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `Westside Basketball` — project - Issue #118 — team announcement email (depends on this) - Issue #115 — team creation (done)