cgalo5758
71818de0bd
Implement the ux-first-run change: a state-derived setup checklist on /operator/setup with a landing region that recedes once required steps are done, and empty states that distinguish blocked from empty across operator and member surfaces. Also add production deployment and environment reference docs, plus a config-key completeness test.
4.7 KiB
operator-setup-checklist Specification
Purpose
Give a fresh deployment's first operator a visible, truthful path from nothing to a deliverable plan: a persistent checklist derived entirely from live system state, never from stored progress, so it can never disagree with the surfaces it links.
Requirements
Requirement: Operator surface provides a state-derived setup checklist
The operator panel SHALL provide a setup checklist that walks a fresh deployment through the minimum path from nothing to a deliverable plan. The checklist SHALL cover, as discrete steps: create an entitlement set; create a product that uses it (the product step is keyed on a published product, and its copy states that the operator panel publishes a product at creation — the panel's create path has no draft state and no separate publish control, so a standalone "publish" step could never be independently acted on); add an active price and sync it to Stripe; create a plan ladder and attach the product as a tier; choose an org-type default plan. Each step SHALL link directly to the surface where the operator completes it, and each incomplete step SHALL name what completing it unlocks (the downstream step it feeds).
Steps SHALL be classed required (entitlement set, published product, ladder with a rank-0 tier) or conditional (price plus Stripe sync, needed only when products are sold for money; org-type default, needed only when signup should confer a plan). A conditional step SHALL state its condition inline, because the system cannot judge from data whether the deployment's model needs it — a free-tier-less paid deployment legitimately never sets a default, and a free-only deployment legitimately never configures Stripe.
Every step's completion state SHALL be derived from live system state (existence queries against the same tables the linked surfaces manage). The checklist SHALL NOT store its own progress flags, so its claims cannot disagree with reality: deleting the last entitlement set un-completes that step.
Scenario: Fresh instance shows every step incomplete
- WHEN an operator views the setup checklist on a deployment with no entitlement sets, products, prices, ladders, or org-type defaults
- THEN every step renders as incomplete
- AND each step links to the surface that completes it
Scenario: Completion is derived, not recorded
- WHEN an operator creates an entitlement set through the normal Entitlement Sets surface and returns to the checklist
- THEN the entitlement-set step renders complete without the operator having interacted with the checklist itself
Scenario: Completion reverses when the underlying state disappears
- WHEN the only entitlement set is deleted after its step showed complete
- THEN the step renders incomplete again
Requirement: The checklist is persistent and revisitable, not a wizard
The checklist SHALL remain reachable for the lifetime of the deployment. It SHALL NOT gate or sequence access to any other operator surface, SHALL NOT force steps to be completed in order, and SHALL NOT require the operator to pass through it on any navigation path. It is a map, not a corridor.
Scenario: Steps can be completed out of order
- WHEN an operator creates a plan ladder before any product exists
- THEN the ladder step derives complete while earlier-listed steps remain incomplete
- AND no checklist mechanism prevented or warned against the ordering
Scenario: Checklist survives setup
- WHEN every step is complete and an operator navigates to the checklist surface directly
- THEN the checklist renders with all steps complete rather than being removed or redirecting away
Requirement: The checklist recedes when required setup is complete
While any required step derives incomplete, the checklist SHALL be foregrounded on the operator landing surface (per the operator-panel-navigation landing-region requirement). Once every required step derives complete, the landing surface SHALL stop foregrounding it, even when conditional steps remain incomplete; the checklist surface itself remains addressable and continues to show conditional steps with their conditions.
Scenario: Completed required setup no longer occupies the landing page
- WHEN every required checklist step derives complete and an operator
visits
/operator - THEN the landing surface does not render the setup-progress region
- AND this holds even when a conditional step (Stripe pricing, org-type default) remains incomplete
Scenario: Conditional steps stay visible on the checklist surface
- WHEN an operator visits the checklist surface after all required steps are complete
- THEN incomplete conditional steps still render, each stating the condition under which it matters