pal-e-docs

Review: Add GET /admin/players/{id} detail endpoint

review-676-2026-03-29b Doc

review ready
Project

Verdict: READY

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Decomposed from westside-landing#185
  • [x] Repo — forgejo_admin/basketball-api
  • [x] User Story — As Marcus (admin), player detail for CRM
  • [x] Context — Explains gap between list and detail endpoints
  • [x] File Targets — Modify and do-not-touch lists present
  • [x] Acceptance Criteria — 7 criteria, all testable
  • [x] Test Expectations — 3 unit tests + run command
  • [x] Constraints — Pattern matching + model reuse guidance
  • [x] Checklist — Standard PR/test/no-unrelated
  • [x] Related — project-westside-basketball + upstream issue

Traceability

  • [x] story:WS-S12 label — "As an admin, I want to manage user accounts (reset passwords, view profiles) so that I can support parents directly"
  • [x] story note verified — found in project-westside-basketball user-stories section under Admin (Marcus)
  • [x] arch:basketball-api label — component identified
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-basketball-api (platform-wide gap, not specific to this ticket)
  • [x] Forgejo issue — forgejo_admin/basketball-api#249, open

File Targets

  • [x] src/basketball_api/routes/admin.py — verified: file exists (1059 lines), contains existing admin endpoints with consistent patterns (require_admin dependency, Pydantic response models, joinedload queries). No existing GET /admin/players/{player_id} endpoint. Existing GET /admin/players list endpoint at line 305 provides pattern reference.

Repo Placement

Correct. Issue filed on basketball-api, file target is in basketball-api. Single-repo scope.

Dependencies

  • Downstream: westside-landing#185 (CRM player detail page) depends on this endpoint. No blocker on this ticket.
  • No blockers: #675 (in_progress, story:WS-S9 payment tracking) and #666 (in_progress, story:WS-S7/WS-S18 email) are independent features in different parts of admin.py.
  • Model verified: Player model has all fields referenced in AC — parent relationship, teams (M2M via player_teams), registrations, contract_status, contract_signed_at, jersey_option, jersey_size, jersey_number, jersey_order_status, date_of_birth, height, position, current_school, graduating_class, hometown, division, country, photo_url.

Acceptance Criteria

7 criteria, all programmatically verifiable. Criteria 2-5 are field-level assertions on a single response model (not independent behaviors). Test expectations align: valid ID, 404, auth check. Run command is correct: pytest tests/test_admin.py -v.

Blast Radius

Low. Adds a new read-only endpoint. Does not modify existing GET /admin/players list or any other endpoint. The account.py has a separate /players endpoint for non-admin profile editing — no conflict. No downstream schema changes. Rollback is trivial (revert the single file).

Decomposition Assessment

No decomposition needed. 1 file target, 1 repo. The 7 AC are all field-level assertions on a single endpoint response model — they represent one discrete change (add endpoint + response model), not 7 independent tasks. Estimated agent work: under 5 minutes. No parallelizable subtasks.

Recommendation

No action needed. Scope is solid, template complete, traceability verified (arch note gap is platform-wide, tracked separately). Ready for dispatch.