ahmido/TenantAtlas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects 1 Releases Wiki Activity
9e435ea91f
TenantAtlas/specs/326-customer-review-workspace-v1-productization/repo-truth-map.md
ahmido c8224843b3 Spec 326: productize customer review workspace (#386) 
## 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
2026-05-18 13:30:38 +00:00

84 lines
14 KiB
Markdown
Raw Blame History

# 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.
Reference in New Issue View Git Blame Copy Permalink