109 lines
6.5 KiB
Markdown
109 lines
6.5 KiB
Markdown
# Quickstart: Commercial Entitlements and Billing-State Maturity
|
|
|
|
**Date**: 2026-04-28
|
|
**Branch**: `251-commercial-entitlements-billing-state`
|
|
|
|
This quickstart is the intended reviewer flow after implementation. It stays bounded to the commercial lifecycle overlay described in the spec.
|
|
|
|
## Prerequisites
|
|
|
|
1. Start the local platform stack.
|
|
- `export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail up -d`
|
|
2. Ensure one platform user has directory visibility plus the dedicated commercial lifecycle management capability.
|
|
3. Ensure one workspace member can complete onboarding, one reporting operator can manage review packs, and one customer-safe or operator read-only actor can open review/evidence/download surfaces under current RBAC.
|
|
4. Seed or factory-create:
|
|
- one workspace with untouched lifecycle state
|
|
- one onboarding draft in that workspace
|
|
- one tenant with an existing review, evidence snapshot, and generated review pack
|
|
- one workspace already at or above the managed-tenant activation limit for substrate-block verification
|
|
|
|
## Scenario 1: Change workspace commercial state from the system plane
|
|
|
|
1. Open `/system/directory/workspaces/{workspace}` as the authorized platform user.
|
|
2. Confirm the page shows:
|
|
- current lifecycle state
|
|
- source label
|
|
- rationale and last-changed attribution
|
|
- affected behavior summary for onboarding and review-pack starts
|
|
- the underlying entitlement substrate summary for context
|
|
3. Use `Change commercial state` to move the workspace to `trial` with rationale.
|
|
4. Confirm the page updates immediately and the change is attributable.
|
|
5. Repeat with `grace`, `suspended_read_only`, and `active_paid`.
|
|
6. Confirm every explicit state change requires rationale, including a return to `active_paid`, and that the `Suspended / read-only` path also requires explicit confirmation.
|
|
|
|
## Scenario 2: Gate onboarding activation with business-state truth
|
|
|
|
1. Open `/admin/onboarding/{onboardingDraft}` for a workspace in `trial` or `active_paid`.
|
|
2. Confirm the completion step allows `Complete onboarding` when the underlying entitlement substrate also allows it.
|
|
3. Switch the same workspace to `grace` from the system plane.
|
|
4. Refresh the onboarding draft and confirm:
|
|
- the action remains visible for an otherwise authorized actor
|
|
- the step explains that expansion is frozen during grace
|
|
- no tenant activation occurs
|
|
5. Repeat with `suspended_read_only` and confirm the block message changes to read-only suspension semantics instead of a permission failure.
|
|
|
|
## Scenario 3: Gate review-pack starts before any run is created
|
|
|
|
1. Use a workspace in `trial` or `active_paid` where the underlying review-pack entitlement allows generation.
|
|
2. Trigger the current start family from:
|
|
- tenant dashboard review-pack card
|
|
- review register export action
|
|
- tenant review detail export action
|
|
- review-pack detail regenerate action
|
|
3. Confirm the existing queued-start UX remains unchanged when allowed.
|
|
4. Move the workspace to `grace`.
|
|
5. Confirm review-pack starts remain allowed with a grace warning.
|
|
6. Start one allowed review-pack action and leave the resulting work queued or running.
|
|
7. Move the workspace to `suspended_read_only`.
|
|
8. Confirm the already-created run remains visible and continues with the existing run UX.
|
|
9. Repeat the same start actions and confirm:
|
|
- each surface shows the same lifecycle-based reason
|
|
- no new `ReviewPack` row is created
|
|
- no new `OperationRun` row is created
|
|
- no queued or terminal review-pack notification is emitted for the blocked attempt
|
|
|
|
## Scenario 4: Preserve read-only review, evidence, and generated-pack access while suspended
|
|
|
|
1. Keep the workspace in `suspended_read_only`.
|
|
2. Open the current read-only consumption surfaces as an already-authorized actor:
|
|
- `CustomerReviewWorkspace`
|
|
- tenant review detail
|
|
- review-pack detail
|
|
- evidence snapshot detail
|
|
- current review-pack download link
|
|
3. Confirm:
|
|
- the pages still render
|
|
- already-generated review packs remain downloadable
|
|
- existing review/evidence history remains visible
|
|
- any read-only explanation stays calm and does not masquerade as 403 or 404
|
|
4. Confirm the slice does not add broad new suspension behavior to unrelated mutable controls outside the spec boundary.
|
|
|
|
## RBAC and Plane Semantics Checks
|
|
|
|
1. Access lifecycle mutation from `/admin` and confirm there is no self-service control surface.
|
|
2. Access `/system/directory/workspaces/{workspace}` as a platform user lacking the dedicated lifecycle capability and confirm authorization is enforced without leaking admin-plane truth.
|
|
3. Access onboarding or review-pack surfaces as a non-member or wrong-plane actor and confirm 404.
|
|
4. Access the same surfaces as an established-scope actor lacking the relevant capability and confirm 403.
|
|
5. Access the action as an otherwise authorized actor whose workspace lifecycle blocks the action and confirm a truthful business-state block instead of 403 or 404.
|
|
|
|
## Targeted Validation Commands
|
|
|
|
```bash
|
|
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Entitlements/WorkspaceCommercialLifecycleResolverTest.php
|
|
|
|
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/System/ViewWorkspaceEntitlementsTest.php tests/Feature/System/Spec113/AuthorizationSemanticsTest.php tests/Feature/Onboarding/ManagedTenantOnboardingEntitlementTest.php tests/Feature/Onboarding/OnboardingRbacSemanticsTest.php
|
|
|
|
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/ReviewPack/ReviewPackEntitlementEnforcementTest.php tests/Feature/ReviewPack/ReviewPackGenerationTest.php tests/Feature/ReviewPack/ReviewPackDownloadTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php tests/Feature/Reviews/CustomerReviewWorkspacePackAccessTest.php tests/Feature/Evidence/EvidenceSnapshotResourceTest.php
|
|
|
|
export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent
|
|
```
|
|
|
|
## Out of Scope Confirmations
|
|
|
|
While validating this slice, confirm that the implementation does not add or imply:
|
|
|
|
- payment-provider credentials, invoices, checkout, taxes, or public pricing UI
|
|
- customer-account, subscription, or contract models
|
|
- automated expiry/reminder/renewal logic
|
|
- a second admin-plane commercial settings surface
|
|
- a broad suspension engine across unrelated mutable product surfaces |