pal-e-docs

Review: Commerce admin page — Svelte implementation (promoted from playground)

review-863-2026-04-06 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — Standalone, discovered during session with Marcus
  • [x] Repo — forgejo_admin/westside-landing
  • [x] User Story — As Marcus (admin), I want a dedicated Commerce page so that I can quickly see jersey orders, subscription status, and contract status
  • [x] Context — good background: 59 player cards, no aggregated view, adapter-static pattern, no new endpoints needed
  • [x] File Targets — new commerce page + admin layout nav (but nav path is vague)
  • [x] Acceptance Criteria — 7 criteria covering nav ordering, three tabs, table columns, summary counts, filters, API reuse, client-side derivation
  • [x] Test Expectations — manual validation + npm run build
  • [x] Constraints — existing patterns, Svelte 5 runes, no Tailwind, pure CSS vars
  • [x] Checklist — PR opened, build passes, no unrelated changes
  • [x] Related — project-pal-e-platform, basketball-api#250

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-app label — westside SvelteKit frontend
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-westside-app for the westside SvelteKit frontend component
  • [x] Forgejo issue — westside-landing#226, open

File Targets

  • [x] src/routes/(app)/admin/commerce/+page.svelte — verified: directory does not exist yet (new file creation), parent src/routes/(app)/admin/ exists with sibling routes (players, teams, schedule, users)
  • [ ] Admin nav layout — ISSUE: issue says "Admin layout component (wherever the nav lives)" but should specify src/routes/(app)/+layout.svelte lines 106-126 explicitly. Verified: admin bottom-nav is at that location with current order Dashboard | CRM | Teams | Schedule

Repo Placement

OK. Forgejo repo forgejo_admin/westside-landing matches local checkout ~/westside-app. Single-repo change — no cross-repo concerns. The /admin/players API endpoint already returns all commerce fields (confirmed in basketball-api#250), so no backend changes needed.

Dependencies

  • [ ] Board item #865 (westside-playground#50) — upstream playground spec, currently in needs_approval (NOT done). The playground commerce.html @-comment spec is the implementation contract for this ticket. Playground gate not formally passed yet.
  • [x] basketball-api#250 — jersey fields merged, no blocker
  • [x] /admin/players endpoint — already returns jersey_option, jersey_order_status, jersey_size, jersey_number, subscription_status, monthly_fee, contract_status, contract_signed_at, contract_signed_by. Confirmed via existing CRM page usage.

Acceptance Criteria

7 AC total. All are verifiable:
  • AC1 (nav ordering) — testable via DOM inspection after build
  • AC2 (three tabs) — testable via DOM inspection
  • AC3-5 (table columns, summary counts, filters per tab) — testable via build + visual inspection. However, the exact DB field-to-column mapping is NOT in the issue body — it lives in the playground spec (westside-playground#50). An implementing agent would not have the field mapping without that reference.
  • AC6 (apiFetch reuse) — testable via grep
  • AC7 ($derived state) — testable via grep
Missing: the issue does not specify exact DB field names for each table column. The playground spec has them (jersey_option, jersey_order_status, jersey_size, jersey_number, subscription_status, monthly_fee, contract_status, contract_signed_at, contract_signed_by) but this is not cross-referenced.

Blast Radius

  • Nav change in +layout.svelte affects all admin users — low risk (adding one link between existing links)
  • bottom-nav CSS is in src/app.css. Adding a 5th nav item may compress mobile layout on small screens (320px). Current 4-item nav fills the bar — 5 items needs spacing verification.
  • No other consumers of the admin nav pattern outside +layout.svelte.
  • Rollback is straightforward — revert one new file + one nav line.

Decomposition Assessment

Apply three-thing limit and five-minute rule:
  • 2 file targets in 1 repo — under the 3-file threshold
  • 7 AC — above the 5-AC guideline, but all AC are within a single new page component + one nav line insertion. The AC are logically cohesive (three tab views of the same data source).
  • Estimated agent time: 3-4 minutes. One fetch call, three filtered views, one nav link.
  • No independent subtasks that benefit from parallelization — the page is one unit of work.
No decomposition needed.

Recommendation

  • [BODY] Specify exact nav file path: change "Admin layout component (wherever the nav lives)" to src/routes/(app)/+layout.svelte (lines 106-126, insert between CRM and Teams links)
  • [BODY] Add explicit reference to playground spec: "Implementation contract: westside-playground#50 commerce.html @-comment spec defines exact columns, filters, summary counts, and DB field mappings for each tab."
  • [BODY] Add 5th-nav-item mobile consideration to Constraints: "Adding a 5th bottom-nav item — verify spacing on small screens (320px viewport)"
  • [SCOPE] Create architecture note arch-westside-app for the westside SvelteKit frontend component
  • [SCOPE] Upstream gate: board item #865 (playground spec) is in needs_approval, not done. This ticket should not advance to in_progress until #865 passes its gate.