ahmido
bf10645dc3
## 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
193 lines
9.7 KiB
Markdown
193 lines
9.7 KiB
Markdown
# 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. |
|