ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9e435ea91f
TenantAtlas/specs/342-customer-review-workspace-final-consumption-productization/customer-review-consumption-state-contract.md
ahmido bf10645dc3 feat: finalize customer review workspace consumption (342) (#414) 
## Summary
- finalize the existing Customer Review Workspace as a customer-safe first-screen consumption surface
- lead the page with one review decision card, readiness flow, findings summary, accepted-risk summary, and secondary proof instead of diagnostics-first presentation
- keep evidence, review-pack, export, audit, and operation proof states explicit and separate so the page does not make false readiness or evidence claims
- add focused Spec 342 Feature and Browser coverage plus the spec-local truth map, state contract, and screenshot artifacts
- preserve the existing workspace-wide route with canonical `environment_id` filtering only and no new portal, backend generation flow, or navigation rewrite

## Validation
- `cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Filament/Spec342CustomerReviewWorkspaceConsumptionTest.php tests/Feature/Reviews/CustomerReviewWorkspacePageTest.php`
- `cd apps/platform && ./vendor/bin/sail php vendor/bin/pest tests/Browser/Spec342CustomerReviewWorkspaceConsumptionSmokeTest.php tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php --compact`
- `cd apps/platform && ./vendor/bin/sail bin pint --dirty --format agent`
- `git diff --check`

## Notes
- screenshot artifacts are included under `specs/342-customer-review-workspace-final-consumption-productization/artifacts/screenshots/`
- Livewire v4 compliance unchanged
- Filament provider registration remains in `apps/platform/bootstrap/providers.php`
- no globally searchable resource behavior changed in this slice
- no new destructive action behavior was introduced
- no new Filament assets; deploy `filament:assets` posture is unchanged
- full suite was not run in this turn; validation stayed on the focused Spec 342 slices

Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de>
Reviewed-on: #414
2026-06-01 08:15:11 +00:00

9.7 KiB
Raw Blame History

Spec 342 - Customer Review Consumption State Contract

Status: implemented
Created: 2026-06-01
Scope: Customer Review Workspace first-screen consumption states

This contract defines display states for Customer Review Workspace. These states are presentation labels derived from existing repo truth. They are not a new enum, lifecycle family, persisted status, or platform workflow framework.

Universal Rules

  • Default-visible content must answer: status, reason, impact, and primary next action.
  • Primary next action must be singular per rendered state.
  • Diagnostics default is Collapsed or Unavailable.
  • Raw provider JSON, raw OperationRun payload, fingerprints, stack traces, internal IDs as primary labels, and platform reason families are hidden by default.
  • Customer-safe, auditor-ready, evidence-backed, export-ready, healthy, complete, or compliant claims appear only when repo-backed.
  • OperationRun proof is not evidence output, review-pack output, or customer-safe readiness.
  • External delivery and attestation are unavailable unless implementation discovers repo-backed truth and updates this contract/spec first.

Implementation Notes

  • Spec 342 implemented these states as presentation-only, page-local derived payloads on the existing Customer Review Workspace.
  • Open findings block a ready-to-share claim even when evidence and review-pack truth are available; the pack/export state remains visible but customer-safe output is Needs review.
  • Accepted-risk summaries are visible by default when repo-backed; full accepted-risk records remain collapsed.
  • Findings and accepted-risk follow-up states use concrete decision-card copy based on repo-backed counts, owners, rationale, and review-date context instead of generic issue text.
  • The prior repeated readiness summary cards are absorbed into the six-step consumption flow and right-rail proof panels to reduce duplicate status surfaces.
  • Download review pack appears only as the primary action when the review is actually ready to share; follow-up states keep review-pack availability as status context and route the primary action to the review.
  • Diagnostics remain collapsed by default, and raw provider/support payloads, stack traces, fingerprints, and raw OperationRun JSON are not rendered in the default customer-safe surface.

Flow Steps

The review readiness flow uses these steps:

  1. Review data
  2. Evidence
  3. Findings triaged
  4. Accepted risks reviewed
  5. Review pack
  6. Customer-safe output

Presentation Vocabulary

  • Available
  • Missing
  • Required
  • Generating
  • Failed
  • Ready
  • Needs review
  • Not ready
  • Unavailable
  • Collapsed
  • Deferred

State Contracts

1. Review Not Ready

Field Contract
Visible status Review not ready
Reason Required review data or evidence is missing.
Impact This review should not be shared as customer-ready yet.
Primary next action Complete review preparation, only if repo-supported and authorized; otherwise show unavailable.
Findings summary Unavailable or deferred unless repo-backed review/finding data exists.
Accepted risks state Unavailable or deferred unless repo-backed exception data exists.
Evidence state Missing or unavailable.
Review pack state Unavailable.
Customer-safe output state Not ready.
Export state Unavailable.
Diagnostics default Collapsed/unavailable.

2. Review Ready, Evidence Missing

Field Contract
Visible status Review ready, evidence missing
Reason Review summary exists, but supporting evidence is not available.
Impact Findings can be discussed, but the review is not evidence-backed yet.
Primary next action Open review or generate/open evidence only when repo-supported and authorized.
Findings summary Available when review-derived or finding data is repo-backed.
Accepted risks state Available when exception data is repo-backed.
Evidence state Missing.
Review pack state Required or unavailable.
Customer-safe output state Needs review or not ready; never evidence-backed.
Export state Unavailable unless a repo-backed review pack file is independent and valid.
Diagnostics default Collapsed.

3. Review Ready With Evidence

Field Contract
Visible status Review ready with evidence
Reason Review summary and supporting evidence are available.
Impact Customer stakeholders can consume the review and inspect evidence.
Primary next action Review findings or open evidence, based on repo-backed attention state.
Findings summary Open/attention counts where repo-backed.
Accepted risks state Visible if accepted risks exist.
Evidence state Available.
Review pack state Required, generating, failed, or available from ReviewPack truth.
Customer-safe output state Needs review or ready only when review/pack truth supports it.
Export state Available only from ready non-expired pack file truth.
Diagnostics default Collapsed.

4. Review Pack Required

Field Contract
Visible status Review pack required
Reason Review data exists, but no review pack is available.
Impact Customer-safe export/download is not ready yet.
Primary next action Generate review pack only when existing repo action is supported and authorized; otherwise open review/evidence.
Findings summary Available if repo-backed.
Accepted risks state Available if repo-backed.
Evidence state Available or missing from evidence truth.
Review pack state Required.
Customer-safe output state Not ready or needs review.
Export state Unavailable.
Diagnostics default Collapsed.

5. Review Pack Available

Field Contract
Visible status Review pack available
Reason A review pack is available for this review.
Impact The review can be consumed and exported according to workspace policy if the pack is repo-backed as customer-safe and authorized.
Primary next action Open review pack or download review pack when authorized and file metadata supports it.
Findings summary Still visible; pack availability must not hide findings needing attention.
Accepted risks state Still visible; accepted risks must not be hidden in diagnostics.
Evidence state Available or needs review based on linked evidence.
Review pack state Available.
Customer-safe output state Ready only when repo-backed; otherwise needs review.
Export state Available only for ready, non-expired pack with file metadata and authorization.
Diagnostics default Collapsed.

6. Findings Need Attention

Field Contract
Visible status Findings need attention
Reason One or more findings require customer review or operator follow-up.
Impact Review should not be treated as complete until findings are assigned, accepted, resolved, or otherwise addressed.
Primary next action Review findings.
Findings summary Required; show repo-backed counts and customer-safe row preview.
Accepted risks state Visible separately if accepted risks also exist.
Evidence state Available/missing from evidence truth.
Review pack state Available/required/generating/failed from pack truth.
Customer-safe output state Needs review unless repo truth proves no action remains.
Export state Available only when file truth supports it; export does not suppress findings attention.
Diagnostics default Collapsed.

7. Accepted Risks Present

Field Contract
Visible status Accepted risks present
Reason Some findings have accepted risk decisions.
Impact Customer stakeholders should review owner, rationale, and expiry/review date where available.
Primary next action Review accepted risks.
Findings summary Shows related finding context where repo-backed.
Accepted risks state Required; show owner/rationale/expiry/review date if present and missing-date copy if not.
Evidence state Available/missing from evidence truth.
Review pack state Available/required/generating/failed from pack truth.
Customer-safe output state Needs review or ready depending on validity and review-pack truth.
Export state Available only when file truth supports it.
Diagnostics default Collapsed.

8. No Findings Requiring Action

Field Contract
Visible status No findings requiring action
Reason This review has no open findings requiring customer action.
Impact Review can be consumed or exported if evidence and review pack are available.
Primary next action Open review pack or open evidence when authorized and repo-backed.
Findings summary Shows zero-action state only if repo-backed.
Accepted risks state Shows none/current state only if repo-backed.
Evidence state Available/missing from evidence truth.
Review pack state Available/required/generating/failed from pack truth.
Customer-safe output state Ready only when evidence/review-pack truth supports it.
Export state Available only when file truth supports it.
Diagnostics default Collapsed.

Unavailable Or Deferred Concepts

Concept Default Contract
Customer acknowledgement / attestation Do not implement in Spec 342. Show unavailable/deferred copy only if useful.
External delivery / email / PSA handoff Do not implement in Spec 342. Show unavailable/deferred copy only if useful.
Auditor-ready certification Do not claim unless future repo truth supports certification semantics.
Compliance/healthy claim Do not claim from absence of findings alone.
Generic customer portal Deferred follow-up outside Spec 342.