ahmido
c8224843b3
## Summary - productizes the Customer Review Workspace into a more decision-first, customer-safe review surface - updates the page class, Blade view, and localized copy for the new workspace presentation - expands feature and browser coverage for workspace behavior, localization, and access rules - adds the Spec 326 artifact package for this implementation ## Testing - not run in this session Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #386
14 KiB
14 KiB
Spec 326 Repo Truth Map
Status: implementation aligned Created: 2026-05-18 Purpose: classify each Customer Review Workspace runtime element before and during implementation. This map is based on repository inspection and the Spec 326 runtime diff.
Implementation update: Spec 326 productizes the existing CustomerReviewWorkspace page with page-local derived payloads only. The premium layout follow-up keeps the same scope and recomposes the existing UI into a compact main/aside workbench. No migration, package, env var, queue, scheduler, storage disk, deployment asset, public portal, external auth, review engine, evidence engine, review-pack engine, or legacy query alias support was added.
Classification Legend
repo-verified: exact runtime source exists and was inspected.foundation-real: backend model/service/policy exists, but exact page binding still needs implementation verification.derived from existing model: display value can be derived from existing persisted/domain truth.empty state / unavailable: no safe source/action exists for v1; show explicit unavailable or omit.deferred future capability: outside Spec 326 and must not be shown as live runtime truth.
Data Area Map
Required data areas preserved from preparation review: Tenant Reviews / Environment Reviews, Evidence Snapshots, Review Packs / exports, Accepted Risks / Risk Exceptions, Findings / Finding Exceptions, OperationRuns, Workspace entitlements/capabilities, Audit log.
| UI element | Source model/service/page | Status source | Authorization / capability | Workspace / Environment scope | OperationRun / audit link | Fallback / empty state | Classification |
|---|---|---|---|---|---|---|---|
| Customer Review Workspace route | CustomerReviewWorkspace, route admin/reviews/workspace |
Filament page slug reviews/workspace |
EnvironmentReviewRegisterService::canAccessWorkspace() plus authorized environments |
Workspace session via WorkspaceContext; optional page filter |
WorkspaceAuditLogger logs CustomerReviewWorkspaceOpened |
404 if no workspace/access/authorized environments | repo-verified |
| Header title and customer-safe mode | CustomerReviewWorkspace::getTitle(), Blade view |
Localization keys under localization.review.* |
Page access authorization | Workspace-wide unless environment_id filter present |
Page-open audit only | Static customer-safe disclosure | repo-verified |
| Environment filter chip | environmentFilterChip(), filament.partials.workspace-hub-environment-filter-chip |
WorkspaceHubEnvironmentFilter, table filter state |
Environment resolved inside current workspace and actor entitlement | ?environment_id={id} only |
Audit metadata includes tenant_filter_id |
no chip on clean URL | repo-verified |
| Clear environment filter | clearWorkspaceFilters(), ClearsWorkspaceHubEnvironmentFilterState, WorkspaceHubFilterStateResetter |
clean URL via WorkspaceHubRegistry::cleanUrl() |
Page access auth | clears canonical and session/table filter state | no OperationRun | clean workspace-wide URL | repo-verified |
| Legacy alias rejection | WorkspaceHubRegistry::forbiddenQueryKeys() and resetter |
forbidden keys include tenant, tenant_id, managed_environment_id, environment_id, environment, tenant_scope, tableFilters; canonical environment_id is preserved only when explicit |
page access plus environment resolver | legacy aliases neutralized; canonical filter scoped | no OperationRun | no filter state or safe 404 | repo-verified |
| Cross-workspace environment guard | WorkspaceHubEnvironmentFilter::fromRequest() |
environment lookup constrained by workspace_id |
User::canAccessTenant() |
current workspace only | no OperationRun | NotFoundHttpException |
repo-verified |
| Latest released review | EnvironmentReview, EnvironmentReviewRegisterService::latestPublishedQuery() |
EnvironmentReviewStatus::Published, published_at, generated_at, id |
EnvironmentReviewRegisterService authorized tenant query and policies on handoff routes |
current workspace and optional environment filter | EnvironmentReview::operationRun() relation exists; not default raw |
no active/released review empty state | repo-verified |
| Main decision card | latestReviewConsumptionPayload(), reviewReadinessForTenant() |
published review, package availability, evidence/decision summary | page access plus environment entitlement; pack action gated by Capabilities::REVIEW_PACK_VIEW |
workspace or canonical environment_id filter |
no new OperationRun | follow-up required/open latest review when pack unavailable | repo-verified |
| Main readiness state | current latestReviewStateLabel(), workspaceReviewNeedsAttention() and package/evidence helpers |
derived from published review, package availability, evidence/decision summary | page access plus environment entitlement | workspace or environment filter | no new OperationRun | no active review / follow-up required | repo-verified |
| Readiness reason and impact | review summary, governance package decision/evidence state, ReviewPack availability | EnvironmentReview.summary, governance_package.decision_summary, ReviewPackStatus |
same as review/pack access | workspace/environment scoped | no new OperationRun | customer-safe follow-up copy when source is unavailable | repo-verified |
| Primary next action | reviewPackDownloadUrl(), latestReviewUrl() |
ready downloadable pack vs latest review URL | Capabilities::REVIEW_PACK_VIEW, Environment Review view capability via resource route |
environment-bound review/pack | ReviewPack service may include source metadata; no run start | open review or unavailable | repo-verified |
| Readiness summary cards | readinessDimensionPayloads() |
review readiness, evidence state, accepted-risk state, review-pack availability | same as source section | workspace/environment scoped | no new OperationRun | unavailable/not applicable per card | repo-verified |
| Evidence snapshot availability | EvidenceSnapshot, EnvironmentReview::evidenceSnapshot() |
EvidenceSnapshotStatus, completeness_state, generated_at, expires_at, review summary |
EvidenceSnapshotPolicy / Capabilities::EVIDENCE_VIEW for detail link |
managed environment and workspace | EvidenceSnapshot::operationRun() relation exists |
evidence unavailable/not generated/stale if unsupported | foundation-real |
| Evidence freshness/staleness | EvidenceSnapshot fields and review summary completeness |
generated_at, expires_at, EvidenceCompletenessState, review summary |
evidence view capability where linking | managed environment and workspace | operation relation exists | explicit unavailable if no reliable freshness | derived from existing model |
| Evidence path panel | evidencePathForReview() over existing review/evidence/pack/operation relations |
per-item availability states | source-specific policies/capabilities; evidence link checks Capabilities::EVIDENCE_VIEW |
workspace/environment scoped | existing OperationRun relations only |
unavailable/not applicable rows | repo-verified |
| Review pack status | ReviewPack, ReviewPackStatus, currentExportReviewPack |
queued/generating/ready/failed/expired/file path/expiry | ReviewPackPolicy, Capabilities::REVIEW_PACK_VIEW for open/download |
managed environment/workspace | ReviewPack::operationRun() relation exists |
not generated/preparing/unavailable/expired | repo-verified |
| Review pack download URL | ReviewPackService::generateDownloadUrl() |
ready status, file path/disk, not expired | Capabilities::REVIEW_PACK_VIEW |
managed environment/workspace | source metadata only; no run start | no URL if unauthorized/unavailable | repo-verified |
| Review pack generation action | existing Review Pack resource/job may support generation | GenerateReviewPackJob, ReviewPackResource |
manage capability required | environment-owned resource | OperationRun-backed generation may exist | do not show in default customer-safe surface | empty state / unavailable |
| Accepted risk summary | FindingException model and governance_package.accepted_risks in review summary |
status, current_validity_state, review_due_at, accepted-risk summary entries |
page consumes released-review summary without raw internal approval detail | managed environment/workspace | decisions/audit may exist in related workflow | no accepted risks recorded / unavailable | repo-verified |
| Expiring/expired/pending accepted-risk counts | FindingException fields |
current_validity_state, status, expires_at, review_due_at |
finding exception view capability or released-review summary | managed environment/workspace | related decisions/audit only if linked | show unavailable if not safely derivable | derived from existing model |
| Customer-safe follow-ups | customerSafeFollowUpsForReview() over governance-package decision-summary entries |
title, summary, next action where present; proof label from decision trail | released-review customer-safe summary only | managed environment/workspace | no new OperationRun | explicit no-follow-ups state | repo-verified |
| Decision trail | review governance_package.decision_summary |
decision summary status/entries | released-review safe summary | managed environment/workspace | audit may exist on decisions | unavailable/fallback copy if no decision summary | repo-verified |
| Operation proof | EnvironmentReview::operationRun, EvidenceSnapshot::operationRun, ReviewPack::operationRun |
existing run relation presence | existing OperationRunLinks handoff only when a run is linked |
workspace and managed environment entitlement | existing OperationRun only | proof unavailable if no relation | repo-verified |
| Stored report / export artifact proof | ReviewPack, review/export links |
review-pack ready/download URL state | review-pack view capability through existing download route | managed environment/workspace | may relate to operation/audit if linked | unavailable unless current pack download is ready | repo-verified |
| Diagnostics disclosure | diagnosticsDisclosureForReview() |
safe explanatory disclosure only; no raw metadata rendered | no diagnostic payload/action exposed in customer-safe default | workspace/environment scoped | may link to OperationRun/support diagnostics in future specs only | collapsed by default; raw/support details absent | repo-verified |
| Raw payload / provider diagnostics | raw summary payloads, provider errors, Graph data | not safe default source | support-only if ever exposed | N/A for customer default | N/A | never default-visible | deferred future capability |
| Workspace entitlements/capabilities | CapabilityResolver, WorkspaceCapabilityResolver, policies |
capability strings in Capabilities |
existing policy/capability calls | workspace and managed environment | audit for access/mutations as existing | hidden/unavailable actions | repo-verified |
| Audit page open | WorkspaceAuditLogger, AuditActionId::CustomerReviewWorkspaceOpened |
page-open event metadata | page access auth | workspace resource id | audit log entry | skip only if no user/workspace | repo-verified |
Required Runtime Element Decisions
| Element | v1 decision |
|---|---|
| New external customer portal | deferred future capability; do not build |
| Public share/invite/email delivery | deferred future capability; do not show |
| Review generation engine | existing backend only; no new engine |
| Evidence refresh action | show only if existing route/action/capability is verified and safe; otherwise unavailable |
| Review pack generation/regeneration | do not show on customer-safe default surface |
| Diagnostics | collapsed/secondary and authorized only; default hidden |
| Green/success state | allowed only when repo-backed proof supports the exact statement |
| Legacy query aliases | rejected/neutralized; do not support |
Implemented Surface Classification
| Runtime section | Implemented source | Final classification | Notes |
|---|---|---|---|
| Scope and shell context | existing workspace session, canonical environment_id, chip partial |
repo-verified | Clean entry stays workspace-wide; filtered entry remains Workspace shell with visible chip. |
| Decision-first card | page-local payload from released review, package availability, evidence/follow-up helpers | repo-verified | Shows ready/follow-up state, reason, impact, and one primary repo-real action. |
| Readiness dimensions | released review, evidence state, accepted-risk summary, review-pack state | repo-verified | Uses derived display labels only; no new persisted state family. |
| Evidence path | evidence snapshot, review pack, decision trail, accepted-risk records, OperationRun relation, export artifact | repo-verified | Missing sources render unavailable states instead of success claims. |
| Review pack panel | ReviewPackStatus, generated timestamp, evidence snapshot timestamp, download URL, operation relation |
repo-verified | Download appears only when existing pack/view capability and ready artifact support it. |
| Right-side evidence path | evidence snapshot, review pack, decision trail, existing OperationRun relation | repo-verified | Aside rows show proof state only; actions stay in the main decision card or existing detail routes. |
| Accepted-risk aside | released review governance_package.accepted_risks and governance_package.governance_decisions |
repo-verified | Counts and records derive from existing review-package arrays; no live metric or new status family is introduced. |
| Disclosure rule aside | customer-safe page disclosure policy from Spec 326 | repo-verified | Decision and evidence are visible, diagnostics are collapsed, and raw/support detail is hidden by default. |
| Customer-safe follow-ups | governance-package decision summary entries | repo-verified | Owner/due fields are not invented; absent data becomes no-follow-ups copy. |
| Diagnostics | collapsed <details> with safe disclosure copy |
repo-verified | Raw payloads, provider secrets, stack traces, fingerprints, and internal exception text are not rendered by default. |
| Secondary table | existing Filament table over authorized latest published reviews | repo-verified | Kept as secondary context; no Graph calls added. |
Implementation Update Rule
If implementation discovers that a planned UI element has no safe source, no authorization path, or would require new persisted truth, the element must become empty state / unavailable or deferred future capability. Do not create backend foundation inside Spec 326 without updating spec.md, plan.md, and this map first.