pal-e-docs

Review: Commerce page: full @-comment spec + shared CSS/JS + complete DB schema mapping

review-865-2026-04-06 Doc

review needs-refinement
Project

Verdict: NEEDS_REFINEMENT

Template Completeness

  • [x] Type — Feature
  • [x] Lineage — upstream of westside-landing#226
  • [x] Repo — forgejo_admin/westside-playground
  • [x] User Story — clear "As Marcus (admin), I want commerce view so I can answer who ordered what"
  • [x] Context — thorough, includes DB field inventory and current gap list
  • [x] File Targets — 3 files to modify, exclusions listed
  • [x] Acceptance Criteria — 11 testable criteria
  • [x] Test Expectations — manual only (correct for static HTML playground)
  • [x] Constraints — references SOP, design system tokens, badge classes
  • [x] Checklist — present
  • [x] Related — downstream issue #226 and SOP referenced
All required Feature template sections present. Issue is well-written with strong context and explicit DB field mapping.

Traceability

  • [ ] story:marcus-admin label — INVALID format. Project page uses WS-SXX codes. The issue's user story maps to story:WS-S9 ("As an admin, I want to track payment status per player so that I know who owes what"). marcus-admin is a persona descriptor, not a story code.
  • [ ] story note MISSING — [SCOPE] No entry matching marcus-admin exists in project-westside-basketball user-stories section. Should use story:WS-S9 or create a new story code if WS-S9 is not precise enough.
  • [ ] arch:admin-portal — label present on board item, but no architecture note found. search_notes("arch-admin-portal") returned empty.
  • [ ] arch note MISSING — [SCOPE] Create architecture note arch-admin-portal for the admin portal component.
  • [x] Forgejo issue — forgejo_admin/westside-playground#50, state: open

File Targets

  • [x] commerce.html — verified: exists (575 lines). Confirmed gaps: 1 inline <style> block, 1 inline <script> block, @-comment header missing @state/@interactivity/@gaps/@complexity, DB fields shipped/past_due/canceled/monthly_fee/contract_signed_at/contract_signed_by all absent.
  • [x] shared/style.css — verified: exists (84KB). Append-only target for commerce-specific styles.
  • [x] shared/app.js — verified: exists (24KB). Append-only target for tab/filter logic.
Targets are specific enough for an agent to act on without guessing.

Repo Placement

Correct. Issue filed on westside-playground, all file targets are in westside-playground. This is Gate 1 playground work per sop-capacitor-mobile-lifecycle. Downstream Svelte promotion tracked separately in westside-landing#226.

Dependencies

  • [ ] Board item #863 — same labels (type:feature, arch:admin-portal, story:marcus-admin), null title, in backlog. Potential duplicate or incomplete sibling ticket. Status: unknown — needs reconciliation.
  • [x] Downstream westside-landing#226 — open, documented in Lineage. Not a blocker for this ticket.
  • [x] No blocking in_progress items identified for this work.

Acceptance Criteria

11 ACs total. All are testable:
  • ACs 1-3 (inline style/script removal, @-comment header) — verifiable via grep/file inspection
  • ACs 4-9 (tab filtering, status display, field presence) — verifiable via DOM inspection of rendered page
  • AC 10 (mobile rendering) — requires phone viewport check
  • AC 11 (no console errors at live URL) — requires browser console check at playground funnel URL
No ambiguous criteria. All are specific and agent-verifiable.

Blast Radius

Low. Changes confined to westside-playground (static HTML/CSS/JS). No API changes, no DB migrations, no production deployments. The only downstream consumer is westside-landing#226 which consumes this as a design spec, not as live code. Rollback is trivial (git revert on static files).

Decomposition Assessment

3 file targets in 1 repo. 11 acceptance criteria — exceeds the >5 AC threshold. However:
  • All changes are in one coherent refactor of a single page
  • Moving inline styles and scripts is mechanically coupled to the HTML changes
  • DB field additions are all in the same template structure
  • Estimated agent time: 3-5 minutes (borderline)
  • No independent subtasks that benefit from parallelization — the CSS/JS extraction and HTML rewrite are interdependent
No decomposition recommended. The high AC count reflects granular verification steps for what is essentially one refactor pass. All changes are tightly coupled.

Recommendation

  • [LABEL] Change story:marcus-admin to story:WS-S9 on the board item. The user story in the issue body aligns with WS-S9 (admin payment/commerce tracking visibility).
  • [SCOPE] Create architecture note arch-admin-portal for the admin portal component in pal-e-docs. This arch label is used by at least 2 board items (#863, #865).
  • [SCOPE] Reconcile board item #863 — same labels, null title, in backlog. Determine if it is a duplicate of #865 or a distinct sibling ticket, and either remove it or give it a proper title and scope.