pal-e-docs

Review: Add player_id param to jersey and checkout endpoints for multi-player parents

review-basketball-api-256 Doc

review needs-refinement
Project

Ticket Review: basketball-api #256

Verdict: NEEDS_REFINEMENT
Reviewed: 2026-03-29 | Board item: #694 | Story: WS-S18

Template Completeness

Type PASS Feature
Lineage PASS References parent spike westside-landing#196 and dependency #255
Repo PASS forgejo_admin/basketball-api
User Story PASS Clear parent-with-multiple-players persona
Context PASS Explains parent.players[0] problem with concrete line refs
File Targets PASS jersey.py, checkout.py, tests/ -- all exist. DO NOT touch list correct.
Acceptance Criteria PASS 4 criteria covering happy path, 403, backwards compat, multi-endpoint
Test Expectations PASS 3 unit tests + run command specified
Constraints PASS Optional param, cross-parent validation, dependency noted
Checklist PASS Standard 3-item checklist
Related PASS westside-basketball project + parent spike

File Target Verification

  • jersey.py -- EXISTS. jersey_player_info at line 106-131, jersey_checkout at line 172-onwards. parent.players[0] confirmed at lines 127 and 241. Line numbers in issue are accurate.
  • checkout.py -- EXISTS. create_checkout_session at line 103. parent.players[0] confirmed at line 147. Line numbers accurate.
  • account.py -- EXISTS. Parent.email.ilike(user.email) pattern confirmed at line 57 (referenced in context for dual-auth pattern).
  • auth.py -- EXISTS. Will be the target for the dual-auth dependency (#255), not this ticket.

Traceability Check

  • Story label: Board item #694 has story:WS-S18 -- PASS
  • Arch label: Board item #694 has arch:basketball-api -- PASS
  • Story note: ws-s18 slug NOT FOUND in pal-e-docs -- FAIL. The story is referenced but never documented. This breaks the traceability triangle (User Story <> Architecture <> Board Item).

Dependency Check

  • Hard dependency: Issue #255 ("Add dual-auth dependency for jersey and checkout routes") -- board item #693
  • Status: #255 is in backlog column, not yet reviewed, not dispatched, not merged -- BLOCKER
  • This ticket explicitly states: "Depends on dual-auth dependency being merged first"
  • The player_id param changes assume the dual-auth dependency resolves the parent. Without it, adding player_id to token-only endpoints is still useful but incomplete for the SPA flow.

Decomposition Assessment

  • 3 discrete changes: add player_id to jersey_player_info, jersey_checkout, create_checkout_session
  • Within 3-change limit -- PASS
  • Estimated agent time: ~5 minutes -- PASS
  • Single repo, single concern -- well-scoped

Acceptance Criteria Quality

  • Concrete endpoint paths with query params -- verifiable
  • 403 case for cross-parent access -- security covered
  • Backwards compatibility (no player_id defaults to players[0]) -- migration-safe
  • All four criteria are testable with pytest

Blocking Issues

  • Missing story note: Create ws-s18 in pal-e-docs with the user story "As a parent, I want to receive a branded email with jersey ordering link so that I can order without bringing cash" (as stated in #255's lineage). This completes the traceability triangle.
  • Unresolved dependency: #255 must be reviewed, dispatched, and merged before #256 can move to todo. Currently both are in backlog. Review #255 first, then re-review #256.

Recommendations

  • Review and promote #255 first (it has no upstream dependencies beyond the spike).
  • Create the WS-S18 story note in pal-e-docs.
  • Once #255 is merged and WS-S18 story exists, this ticket is ready for todo.
  • The ticket body itself is excellent -- no content changes needed.