pal-e-docs

Review: Backfill jersey_option for players who paid via legacy checkout

review-867-2026-04-06 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — discovered during Commerce page validation (westside-landing#226)
  • [x] Repo — forgejo_admin/basketball-api
  • [x] User Story — As Marcus (admin), I want to see which jersey option each player ordered
  • [x] Context — explains legacy checkout gap, price-to-option mapping
  • [x] File Targets — admin.py and alembic/versions/
  • [x] Acceptance Criteria — 2 criteria
  • [x] Test Expectations — pytest command provided
  • [x] Constraints — 2 constraints listed
  • [x] Checklist — standard 3-item
  • [x] Related — project + upstream issue linked
All required sections present per template-issue-feature.

Traceability

  • [x] story:WS-S9 — "As an admin, I want to track payment status per player so that I know who owes what"
  • [x] story note verified — found in project-westside-basketball user-stories section under Admin (Marcus)
  • [x] arch:basketball-api — basketball-api component
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-basketball-api for component basketball-api
  • [x] Forgejo issue — forgejo_admin/basketball-api#363, open

File Targets

  • [x] src/basketball_api/routes/admin.py — verified exists. No jersey_option references in this file currently.
  • [x] alembic/versions/ — verified exists. Contains migrations 001-024.
  • [ ] CRITICAL: Migration 023_backfill_player_jersey_from_orders.py ALREADY EXISTS and performs exactly this work — backfills jersey_option, jersey_order_status, jersey_size, and jersey_number from paid generic checkout orders using product name/type mapping. The ticket appears to duplicate completed work.

Repo Placement

OK — issue filed on basketball-api, work targets basketball-api. No cross-repo concerns. AC #2 (Commerce page shows values) depends on westside-app rendering but that is a display concern, not a code change.

Dependencies

  • [ ] Item #733 (Fix 9 failing jersey/checkout tests) — in_progress. Jersey test failures may affect this ticket's test expectations. Status: pending.
  • [ ] Item #718 (Remove opt-out from jersey ordering options) — in qa. Changes opt_out behavior which directly affects jersey_option backfill logic. Status: pending.
  • [ ] Item #694 (Add player_id param to jersey/checkout for multi-player parents) — in qa. Modifies checkout flow. Status: pending.
  • [ ] Migration 023 — already exists in codebase. Status: unknown whether applied to production.
None of these dependencies are documented in the ticket scope.

Acceptance Criteria

  • "All 16 paid players have a non-null jersey_option" — testable via DB query, but the number 16 may be stale if migration 023 has already been applied. An agent could verify with SELECT count(*) FROM players WHERE jersey_option IS NULL AND jersey_order_status = 'paid'.
  • "Commerce page Option column shows actual values instead of --" — depends on westside-app rendering. Not directly testable from basketball-api repo alone, but the API response is testable.

Blast Radius

  • Migration 023 already exists and may have been applied to production. A duplicate migration could cause Alembic version conflicts.
  • scripts/fix_contradictory_jersey_state.py also manipulates jersey_option — any new backfill must not conflict with its logic.
  • Webhook handler in checkout routes syncs jersey_option on payment — new backfill must not overwrite webhook-set values (migration 023 already guards against this with a jersey_order_status != 'none' check).
  • Rollback is straightforward — migration 023's downgrade is a no-op since original values were NULL.

Decomposition Assessment

2 file targets, 1 repo, 2 acceptance criteria. No decomposition needed IF the ticket is still valid after clarifying the migration 023 overlap. Estimated agent time under 5 minutes. No independent subtasks to parallelize.

Recommendation

  • [BODY] Migration 023_backfill_player_jersey_from_orders.py already exists and implements this exact backfill. Update the issue body to acknowledge migration 023 and clarify what ADDITIONAL work is needed — e.g., has migration 023 not been applied to prod? Are there players that 023 missed? Is a manual admin endpoint needed on top of the migration?
  • [BODY] Add a Dependencies section documenting the relationship to #733 (failing jersey tests), #718 (opt-out removal), and migration 023 status.
  • [BODY] Fix board item #867 title — it appears blank on board-westside-basketball.
  • [SCOPE] Create architecture note arch-basketball-api for component basketball-api.
  • [LABEL] Verify whether this ticket should be closed as duplicate if migration 023 has been applied and the 16 players now have jersey_option values.