pal-e-docs

Review: Report: players behind on payment — generate invoice list for Marcus

review-1582-2026-06-23 Review

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Standalone, part of story:WS-S9
  • [x] Repo — ldraney/westside-basketball
  • [x] User Story — well-formed As/I want/So that
  • [x] Context — adequate background
  • [x] File Targets — present but inaccurate (see below)
  • [x] Feature Flag — none (appropriate for admin-only tool)
  • [x] Acceptance Criteria — 3 criteria
  • [x] Test Expectations — present
  • [x] Constraints — present, time-sensitive noted
  • [x] Checklist — present
  • [x] Related — present

Traceability

  • [x] story:WS-S9 label — "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:westside-basketball label — references the main app repo
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-westside-basketball for component westside-basketball. No matching note found in pal-e-docs.
  • [x] Forgejo issue — ldraney/westside-basketball#50, open

File Targets

  • [ ] lib/tasks/payments.rake — ISSUE: file does not exist. The lib/tasks/ directory is empty. This is a valid creation target but should be stated as "create new" not implied as existing.
  • [x] app/controllers/admin/payments_controller.rb — verified: exists, already has payment dashboard logic with index action including both Stripe and DB payment summaries.
  • [ ] "Database query against players, payments, and parents tables" — ISSUE: there is no payments table. The actual tables are payment_links (with status, amount_cents, paid_at), players, and parents. The issue should reference the correct table names.

Critical discovery: existing infrastructure

The existing codebase already has almost everything this ticket describes:
  • Admin::PaymentsController#index — full payment dashboard at /admin/payments
  • StripeClient#db_payment_summary — returns per-team, per-player data including: player name, parent email, total owed, total paid, per-link status and paid_at dates
  • app/views/admin/payments/index.html.erb — renders all payment data in table format, already showing player name, parent email, paid amount, owes amount, and status
The "report" may simply be a filtered view of the existing dashboard (unpaid players only) or a rake task / CSV export wrapper around the existing db_payment_summary method. The issue should acknowledge this existing infrastructure and clarify what additional output format is needed beyond the existing dashboard.

Repo Placement

OK — issue filed on ldraney/westside-basketball, which is the correct repo. All file targets are within this repo. Single-repo scope.

Dependencies

  • No blocking dependencies. All related payment items (Phase 6 Stripe, contract flow, commerce admin, webhook sync) are in the done column.
  • The existing payment dashboard and StripeClient#db_payment_summary are solid foundations — this ticket extends them rather than building from scratch.
  • Item #1579 (Spike: Rails email sending — ActionMailer setup) is in backlog. If "delivered as email" is the intended output format, this ticket may depend on #1579. Currently undocumented.

Acceptance Criteria

  • [x] AC1 "Query identifies all players with overdue or missing payments" — testable, though "overdue" needs definition. The DB uses payment_links.status and paid_at — "overdue" could mean status=active with no paid_at, but this should be explicit.
  • [x] AC2 "Output includes: player name, parent name, parent email, amount owed, last payment date" — testable. Note: existing db_payment_summary already returns all of these except "parent name" (it returns parent email only). The parents table has a name column, so this is a minor addition.
  • [ ] AC3 "List is delivered in a format Marcus can act on (email, spreadsheet, or console output)" — too vague. Which format? If email: depends on ActionMailer (#1579). If spreadsheet: needs CSV generation. If console: rake task or rails runner. Pick one.

Blast Radius

Low blast radius. This is a read-only report — no mutations to existing data. The existing StripeClient#db_payment_summary is already called by the payments controller; adding a rake task that calls the same method is safe. No downstream consumers affected.
One consideration: the existing dashboard uses a hardcoded expected amount of $552.0 for the Stripe links section. The ticket should clarify whether this threshold is relevant or if the DB payment links section (which tracks actual amounts owed) is the correct data source.

Decomposition Assessment

No decomposition needed. This is a single-file addition (rake task or controller enhancement) in one repo, with 3 acceptance criteria. Estimated agent time: well under 5 minutes. The existing db_payment_summary method does most of the heavy lifting already.

Recommendation

  • [BODY] Fix file targets: remove "Database query against players, payments, and parents tables" — the correct table is payment_links (not payments), joined with players and parents.
  • [BODY] Acknowledge existing infrastructure: Admin::PaymentsController#index, StripeClient#db_payment_summary, and the payment dashboard view already contain the data this report needs. Clarify whether this ticket adds a rake task, CSV export, or filtered view on top of the existing dashboard.
  • [BODY] Narrow AC3: specify the output format (CSV file, rake task console output, email, or filtered dashboard page). If email is chosen, add dependency on #1579 (ActionMailer spike).
  • [BODY] Define "behind on payment" — does it mean any player with an active (unpaid) payment_link? Or players missing payment links entirely? Or players below a dollar threshold? The existing dashboard distinguishes between Stripe manual links (hardcoded $552 threshold) and DB payment links (per-link status tracking).