forgejo_admin/basketball-api

Fork 1

API: enrich TeamDetail — multi-coach, coach role/phone, player height/jersey #284

New issue

Closed

opened 2026-04-03 16:57:46 +00:00 by forgejo_admin · 2 comments

forgejo_admin commented

2026-04-03 16:57:46 +00:00

Owner

Type

Feature

Lineage

Related to forgejo_admin/basketball-api#278 (spike: audit API response contract mismatches with westside-landing frontend)

Repo

forgejo_admin/basketball-api

User Story

As an admin/coach/parent, I want the API to return complete team detail data (multiple coaches with role/phone, players with height/jersey) so that the frontend can display it without field mapping hacks.

Context

Spike Mismatch 9: The team detail API endpoint has three gaps:

Single vs multi-coach: TeamDetail.coach is a singular CoachBrief, but teams can have multiple coaches. Change to coaches: list[CoachBrief].
Coach fields: CoachBrief is missing role and phone.
Player fields: PlayerBrief is missing height and jersey_number.

The frontend (westside-app src/routes/(app)/teams/[id]/+page.svelte) already consumes team.coaches (plural array), coach.role, and coach.phone. The API is behind — this ticket brings the API contract in line with what the frontend expects.

Scope: API-only. No frontend changes needed — the frontend already uses the plural coaches array and the enriched fields.

File Targets

Files to modify:

src/basketball_api/routes/teams.py — TeamDetail model: change coach: CoachBrief | None to coaches: list[CoachBrief]. CoachBrief model: add role: Optional[str] and phone: Optional[str]. PlayerBrief model: add height: Optional[str] and jersey_number: Optional[str]. Update query to populate new fields from DB relationships.

Files NOT to touch:

westside-app frontend — already consumes the new contract shape

Acceptance Criteria

TeamDetail field changed from coach: CoachBrief | None to coaches: list[CoachBrief]
CoachBrief includes role: Optional[str] and phone: Optional[str]
PlayerBrief includes height: Optional[str] and jersey_number: Optional[str]
API populates all new fields from DB relationships
All existing tests pass

Test Expectations

API: test team detail with 0, 1, and 2+ coaches
API: test player brief includes height and jersey_number
Run command: pytest tests/

Constraints

Breaking change on coach (singular) to coaches (plural) — coordinate deploy with frontend (frontend already expects plural, so deploy API first is safe)
Priority: HIGH

Checklist

PR opened (basketball-api only)
Tests written and passing
ruff format and ruff check clean
No unrelated changes

Spike: forgejo_admin/basketball-api#278 (Mismatch 9)
Frontend already compatible: westside-app src/routes/(app)/teams/[id]/+page.svelte

### Type Feature ### Lineage Related to forgejo_admin/basketball-api#278 (spike: audit API response contract mismatches with westside-landing frontend) ### Repo forgejo_admin/basketball-api ### User Story As an admin/coach/parent, I want the API to return complete team detail data (multiple coaches with role/phone, players with height/jersey) so that the frontend can display it without field mapping hacks. ### Context Spike Mismatch 9: The team detail API endpoint has three gaps: 1. **Single vs multi-coach**: `TeamDetail.coach` is a singular `CoachBrief`, but teams can have multiple coaches. Change to `coaches: list[CoachBrief]`. 2. **Coach fields**: `CoachBrief` is missing `role` and `phone`. 3. **Player fields**: `PlayerBrief` is missing `height` and `jersey_number`. The frontend (westside-app `src/routes/(app)/teams/[id]/+page.svelte`) already consumes `team.coaches` (plural array), `coach.role`, and `coach.phone`. The API is behind — this ticket brings the API contract in line with what the frontend expects. **Scope**: API-only. No frontend changes needed — the frontend already uses the plural coaches array and the enriched fields. ### File Targets Files to modify: - `src/basketball_api/routes/teams.py` — `TeamDetail` model: change `coach: CoachBrief | None` to `coaches: list[CoachBrief]`. `CoachBrief` model: add `role: Optional[str]` and `phone: Optional[str]`. `PlayerBrief` model: add `height: Optional[str]` and `jersey_number: Optional[str]`. Update query to populate new fields from DB relationships. Files NOT to touch: - westside-app frontend — already consumes the new contract shape ### Acceptance Criteria - [ ] `TeamDetail` field changed from `coach: CoachBrief | None` to `coaches: list[CoachBrief]` - [ ] `CoachBrief` includes `role: Optional[str]` and `phone: Optional[str]` - [ ] `PlayerBrief` includes `height: Optional[str]` and `jersey_number: Optional[str]` - [ ] API populates all new fields from DB relationships - [ ] All existing tests pass ### Test Expectations - API: test team detail with 0, 1, and 2+ coaches - API: test player brief includes height and jersey_number - Run command: `pytest tests/` ### Constraints - Breaking change on `coach` (singular) to `coaches` (plural) — coordinate deploy with frontend (frontend already expects plural, so deploy API first is safe) - Priority: HIGH ### Checklist - [ ] PR opened (basketball-api only) - [ ] Tests written and passing - [ ] `ruff format` and `ruff check` clean - [ ] No unrelated changes ### Related - Spike: forgejo_admin/basketball-api#278 (Mismatch 9) - Frontend already compatible: westside-app `src/routes/(app)/teams/[id]/+page.svelte`

forgejo_admin commented

2026-04-03 17:05:08 +00:00

Author

Owner

Scope Review: NEEDS_REFINEMENT

Review note: review-744-2026-04-03
Cross-repo ticket needs scope clarification before dispatch.

[BODY] Fix frontend file path: src/routes/teams/[id]/+page.svelte should be src/routes/(app)/teams/[id]/+page.svelte
[BODY] Frontend already uses team.coaches (plural), coach.role, coach.phone — AC #5 (frontend update) appears unnecessary. Verify and remove if confirmed, re-scope as API-only.
[BODY] If frontend changes ARE needed, split into two issues (one per repo).
[SCOPE] Create architecture note arch-basketball-api

## Scope Review: NEEDS_REFINEMENT Review note: `review-744-2026-04-03` Cross-repo ticket needs scope clarification before dispatch. - `[BODY]` Fix frontend file path: `src/routes/teams/[id]/+page.svelte` should be `src/routes/(app)/teams/[id]/+page.svelte` - `[BODY]` Frontend already uses `team.coaches` (plural), `coach.role`, `coach.phone` — AC #5 (frontend update) appears unnecessary. Verify and remove if confirmed, re-scope as API-only. - `[BODY]` If frontend changes ARE needed, split into two issues (one per repo). - `[SCOPE]` Create architecture note arch-basketball-api

forgejo_admin changed title from ~~Enrich team detail page: multi-coach, coach role/phone, player height/jersey~~ to API: enrich TeamDetail — multi-coach, coach role/phone, player height/jersey

2026-04-03 17:47:17 +00:00

forgejo_admin commented

2026-04-03 17:47:48 +00:00

Author

Owner

Scope Review: APPROVED (re-review after refinement)

Review note: review-744-2026-04-03-v2
Issue re-scoped to API-only. Frontend already uses team.coaches (plural), coach.role, coach.phone. Removed frontend scope, fixed file target path, reduced AC from 6 to 5. Single-repo, single-file, <5 min.

[SCOPE] Create architecture note arch-basketball-api (deferred — does not block execution)

## Scope Review: APPROVED (re-review after refinement) Review note: `review-744-2026-04-03-v2` Issue re-scoped to API-only. Frontend already uses `team.coaches` (plural), `coach.role`, `coach.phone`. Removed frontend scope, fixed file target path, reduced AC from 6 to 5. Single-repo, single-file, <5 min. - [SCOPE] Create architecture note arch-basketball-api (deferred — does not block execution)

forgejo_admin referenced this issue from a commit

2026-04-03 17:58:12 +00:00

feat: enrich TeamDetail with multi-coach list and player height/jersey fields

forgejo_admin referenced this issue from a pull request that will close it,

2026-04-03 17:58:50 +00:00

feat: enrich TeamDetail with multi-coach list and player height/jersey #292

forgejo_admin referenced this issue

2026-04-03 22:42:52 +00:00

feat: enrich TeamDetail with multi-coach list and player height/jersey #292

forgejo_admin

2026-04-03 22:42:53 +00:00