Flatten PlayerProfileResponse with top-level parent/team/coach fields

forgejo_admin commented

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

Owner

Copy link

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 app to display complete player, parent, and coach information so that I can manage the program without missing data.

Context

Spike Mismatch 1: The frontend expects parent_name, parent_phone, parent_email, team_name, team_id, coach_name as top-level fields on the player profile response. Currently these are only available nested inside related objects, forcing the frontend to drill into nested structures.

The fix is to flatten PlayerProfileResponse so these fields appear at the top level alongside the existing nested objects. This is additive — nested objects remain, top-level fields are added for convenience.

File Targets

src/basketball_api/routes/players.py — PlayerProfileResponse model + endpoint logic

Acceptance Criteria

PlayerProfileResponse includes parent_name, parent_phone, parent_email as top-level Optional[str] fields
PlayerProfileResponse includes team_name as top-level Optional[str], team_id as Optional[int]
PlayerProfileResponse includes coach_name as top-level Optional[str]
Fields are populated from the existing nested parent/team/coach relationships
Existing nested objects remain unchanged (additive, not breaking)
All existing tests pass

Test Expectations

Unit test verifying flattened fields appear in response JSON
Test with player that has no parent/team/coach (fields should be null)

Constraints

Additive only — do not remove nested objects
Priority: HIGH

Checklist

Implementation complete
Tests written and passing
ruff format and ruff check clean
PR submitted

Spike: forgejo_admin/basketball-api#278 (Mismatch 1)

### 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 app to display complete player, parent, and coach information so that I can manage the program without missing data. ### Context Spike Mismatch 1: The frontend expects `parent_name`, `parent_phone`, `parent_email`, `team_name`, `team_id`, `coach_name` as top-level fields on the player profile response. Currently these are only available nested inside related objects, forcing the frontend to drill into nested structures. The fix is to flatten `PlayerProfileResponse` so these fields appear at the top level alongside the existing nested objects. This is additive — nested objects remain, top-level fields are added for convenience. ### File Targets - `src/basketball_api/routes/players.py` — `PlayerProfileResponse` model + endpoint logic ### Acceptance Criteria - [ ] `PlayerProfileResponse` includes `parent_name`, `parent_phone`, `parent_email` as top-level `Optional[str]` fields - [ ] `PlayerProfileResponse` includes `team_name` as top-level `Optional[str]`, `team_id` as `Optional[int]` - [ ] `PlayerProfileResponse` includes `coach_name` as top-level `Optional[str]` - [ ] Fields are populated from the existing nested parent/team/coach relationships - [ ] Existing nested objects remain unchanged (additive, not breaking) - [ ] All existing tests pass ### Test Expectations - Unit test verifying flattened fields appear in response JSON - Test with player that has no parent/team/coach (fields should be null) ### Constraints - Additive only — do not remove nested objects - Priority: HIGH ### Checklist - [ ] Implementation complete - [ ] Tests written and passing - [ ] `ruff format` and `ruff check` clean - [ ] PR submitted ### Related - Spike: forgejo_admin/basketball-api#278 (Mismatch 1)

forgejo_admin commented

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

Author

Owner

Copy link

Scope Review: READY

Review note: review-740-2026-04-03
Single-repo, single-file additive change. All file targets verified. PlayerProfileResponse at line 40 confirmed missing flattened fields.

[SCOPE] Create architecture note arch-basketball-api (shared across all mismatch tickets)

## Scope Review: READY Review note: `review-740-2026-04-03` Single-repo, single-file additive change. All file targets verified. PlayerProfileResponse at line 40 confirmed missing flattened fields. - `[SCOPE]` Create architecture note arch-basketball-api (shared across all mismatch tickets)