SPA API compatibility — prefix fix + missing endpoints #95

New issue

Closed

opened 2026-03-18 06:37:53 +00:00 by forgejo_admin · 0 comments

forgejo_admin commented

2026-03-18 06:37:53 +00:00

Owner

Lineage

plan-wkq → Phase 15 (Production Port — SPA Rebuild)

Repo

forgejo_admin/basketball-api

User Story

As an authenticated user (admin, coach, or parent)
I want the SPA pages to load real data from the basketball-api
So that the app is functional, not just a UI shell with error messages

Context

The SPA rebuild (westside-app PR #37) ported all 13 playground pages to SvelteKit with apiFetch() calls. But the basketball-api routes don't match what the SPA expects:

Prefix mismatch: API mounts at /api/players, /api/teams, but SPA calls /players, /teams directly
Missing endpoints: 9 endpoints the SPA needs don't exist yet

Gap Analysis

SPA Calls	API Route	Status
`/account/players`	—	MISSING — parent dashboard
`/players/{id}`	`/api/players/{id}`	PREFIX MISMATCH
`/players/{id}` PUT	—	MISSING — player profile edit
`/players/{id}/billing`	—	MISSING — billing detail
`/admin/dashboard`	—	MISSING — admin home stats
`/admin/players`	—	MISSING — player CRM list
`/admin/players/{id}/mark-paid`	—	MISSING — admin action
`/admin/players/{id}/cancel-subscription`	—	MISSING — admin action
`/admin/teams`	`/api/teams`	PREFIX MISMATCH
`/admin/teams/save`	—	MISSING — draft board save
`/teams/{id}`	`/api/teams/{id}`	PREFIX MISMATCH
`/coaches/me`	—	MISSING — coach dashboard
`/coaches/{id}`	—	MISSING — coach profile
`/register` POST	`/register` POST	WORKS

File Targets

Files to modify:

src/basketball_api/main.py — add SPA-compatible route prefixes or aliases
src/basketball_api/routes/players.py — add /account/players, player edit PUT, billing
src/basketball_api/routes/admin.py — add dashboard, player CRM, mark-paid, cancel-sub
src/basketball_api/routes/coach.py — add /coaches/me, /coaches/{id} JSON endpoints
src/basketball_api/routes/teams.py — ensure team detail returns coach + player data

Files NOT to touch:

src/basketball_api/routes/register.py — registration works, don't break it
src/basketball_api/routes/webhooks.py — Stripe webhooks, don't touch

Acceptance Criteria

Admin lands on /admin — dashboard loads with real stats (player count, team count, pending registrations)
Admin navigates to /admin/players — sees all players with status, team, payment info
Admin navigates to /admin/teams — sees teams with rosters
Parent lands on /my-players — sees their registered players with status badges
Parent clicks player — profile loads with real data
Coach lands on /coach — sees their team roster
Prefix mismatch resolved — SPA calls work without /api prefix

Test Expectations

Existing tests still pass (pytest tests/)
New endpoints return correct JSON shape matching what SPA components expect
Auth: endpoints respect Keycloak Bearer token — admin sees all, parent sees own, coach sees team
Run: pytest tests/ -v

Constraints

All new endpoints use Keycloak Bearer token auth (same pattern as existing routes)
JSON responses must match the field names the SPA components already reference (e.g. player.name, player.status, player.team_name)
Don't break existing HTML-rendering endpoints (register, tryouts admin, coach onboarding)

Checklist

Prefix mismatch fixed
/account/players endpoint
/admin/dashboard endpoint
/admin/players endpoint
/coaches/me and /coaches/{id} endpoints
PR opened
Tests pass

phase-wkq-15-production-port — parent phase
westside-app PR #37 — the SPA that needs these endpoints
Issue #38 (westside-app) — dev environment setup
Issue #39 (westside-app) — contract flow (needs /players/{id}/contract endpoint)

### Lineage `plan-wkq` → Phase 15 (Production Port — SPA Rebuild) ### Repo `forgejo_admin/basketball-api` ### User Story As an authenticated user (admin, coach, or parent) I want the SPA pages to load real data from the basketball-api So that the app is functional, not just a UI shell with error messages ### Context The SPA rebuild (westside-app PR #37) ported all 13 playground pages to SvelteKit with `apiFetch()` calls. But the basketball-api routes don't match what the SPA expects: 1. **Prefix mismatch**: API mounts at `/api/players`, `/api/teams`, but SPA calls `/players`, `/teams` directly 2. **Missing endpoints**: 9 endpoints the SPA needs don't exist yet ### Gap Analysis | SPA Calls | API Route | Status | |-----------|-----------|--------| | `/account/players` | — | MISSING — parent dashboard | | `/players/{id}` | `/api/players/{id}` | PREFIX MISMATCH | | `/players/{id}` PUT | — | MISSING — player profile edit | | `/players/{id}/billing` | — | MISSING — billing detail | | `/admin/dashboard` | — | MISSING — admin home stats | | `/admin/players` | — | MISSING — player CRM list | | `/admin/players/{id}/mark-paid` | — | MISSING — admin action | | `/admin/players/{id}/cancel-subscription` | — | MISSING — admin action | | `/admin/teams` | `/api/teams` | PREFIX MISMATCH | | `/admin/teams/save` | — | MISSING — draft board save | | `/teams/{id}` | `/api/teams/{id}` | PREFIX MISMATCH | | `/coaches/me` | — | MISSING — coach dashboard | | `/coaches/{id}` | — | MISSING — coach profile | | `/register` POST | `/register` POST | WORKS | ### File Targets Files to modify: - `src/basketball_api/main.py` — add SPA-compatible route prefixes or aliases - `src/basketball_api/routes/players.py` — add `/account/players`, player edit PUT, billing - `src/basketball_api/routes/admin.py` — add dashboard, player CRM, mark-paid, cancel-sub - `src/basketball_api/routes/coach.py` — add `/coaches/me`, `/coaches/{id}` JSON endpoints - `src/basketball_api/routes/teams.py` — ensure team detail returns coach + player data Files NOT to touch: - `src/basketball_api/routes/register.py` — registration works, don't break it - `src/basketball_api/routes/webhooks.py` — Stripe webhooks, don't touch ### Acceptance Criteria - [ ] Admin lands on `/admin` — dashboard loads with real stats (player count, team count, pending registrations) - [ ] Admin navigates to `/admin/players` — sees all players with status, team, payment info - [ ] Admin navigates to `/admin/teams` — sees teams with rosters - [ ] Parent lands on `/my-players` — sees their registered players with status badges - [ ] Parent clicks player — profile loads with real data - [ ] Coach lands on `/coach` — sees their team roster - [ ] Prefix mismatch resolved — SPA calls work without `/api` prefix ### Test Expectations - [ ] Existing tests still pass (`pytest tests/`) - [ ] New endpoints return correct JSON shape matching what SPA components expect - [ ] Auth: endpoints respect Keycloak Bearer token — admin sees all, parent sees own, coach sees team - Run: `pytest tests/ -v` ### Constraints - All new endpoints use Keycloak Bearer token auth (same pattern as existing routes) - JSON responses must match the field names the SPA components already reference (e.g. `player.name`, `player.status`, `player.team_name`) - Don't break existing HTML-rendering endpoints (register, tryouts admin, coach onboarding) ### Checklist - [ ] Prefix mismatch fixed - [ ] `/account/players` endpoint - [ ] `/admin/dashboard` endpoint - [ ] `/admin/players` endpoint - [ ] `/coaches/me` and `/coaches/{id}` endpoints - [ ] PR opened - [ ] Tests pass ### Related - `phase-wkq-15-production-port` — parent phase - westside-app PR #37 — the SPA that needs these endpoints - Issue #38 (westside-app) — dev environment setup - Issue #39 (westside-app) — contract flow (needs `/players/{id}/contract` endpoint)