ahmido
55338a88c6
Some checks failed
Main Confidence / confidence (push) Failing after 59s
## Summary - sync platform-dev back into dev with the latest integrated feature and spec work - include the customer review workspace productization flow and its related review, review-pack, evidence, audit, and test updates - carry forward the recent governance and roadmap/spec updates already merged on platform-dev ## Included highlights - customer review workspace productization and customer-safe released-review drilldown - governance decision convergence work - cross-tenant compare and promotion work - external support desk handoff work - product, roadmap, permissions, and spec artifact updates ## Validation context - platform-dev currently contains the already-validated feature work from the merged branch PRs - latest customer review workspace batch included focused Pest suites, one bounded browser smoke, and Pint ## Notes - this is an integration PR from platform-dev into dev - no separate provider-registration or asset-strategy expansion is introduced by the customer review workspace slice Co-authored-by: Ahmed Darrazi <ahmed.darrazi@live.de> Reviewed-on: #311
156 lines
11 KiB
Markdown
156 lines
11 KiB
Markdown
# Research — Customer Review Workspace Productization v1
|
|
|
|
**Date**: 2026-04-30
|
|
**Spec**: [spec.md](spec.md)
|
|
|
|
This document resolves the planning decisions for the smallest safe productization follow-up to Spec 249.
|
|
|
|
## Decision 1 — Keep the existing customer review workspace as the canonical landing surface
|
|
|
|
**Decision**: Productize the existing [../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php](../../apps/platform/app/Filament/Pages/Reviews/CustomerReviewWorkspace.php) page instead of creating a second customer-review page, new Resource, new panel, or customer portal shell.
|
|
|
|
**Rationale**:
|
|
- The repo already has the canonical admin-plane route, current tenant prefilter behavior, and bounded test family for this page.
|
|
- The gap is productization of the current disclosure contract, not missing routing or missing persistence.
|
|
- Reusing the existing page keeps the follow-up aligned with Spec 249 and avoids a second customer-review vocabulary.
|
|
|
|
**Alternatives considered**:
|
|
- Add a second customer-facing page or shell.
|
|
- Rejected: duplicates the existing workspace route and widens scope into shell-level IA.
|
|
- Convert the workspace into a new Resource.
|
|
- Rejected: this is still a read-only workspace report, not a new persisted object family.
|
|
|
|
## Decision 2 — Keep the existing released-review detail route as the only secondary context surface
|
|
|
|
**Decision**: Continue to use [../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php](../../apps/platform/app/Filament/Resources/TenantReviewResource/Pages/ViewTenantReview.php) as the secondary context surface reached from the workspace by the existing `customer_workspace` query flag.
|
|
|
|
**Rationale**:
|
|
- The current detail page already suppresses management actions when launched from the customer-workspace flow.
|
|
- The current route already writes customer-workspace review-open audit metadata.
|
|
- Productization should deepen understanding on the current drilldown path instead of inventing a second detail page.
|
|
|
|
**Alternatives considered**:
|
|
- Add a customer-only review detail page.
|
|
- Rejected: would duplicate detail truth and drift from the current policy/audit path.
|
|
- Push all new explanation back onto the workspace page only.
|
|
- Rejected: would keep the first drilldown operator-heavy and incomplete.
|
|
|
|
## Decision 3 — Reuse the existing review summary and artifact-truth seams for findings, accepted-risk, and proof framing
|
|
|
|
**Decision**: Reuse the current `TenantReview.summary` payload, [../../apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php](../../apps/platform/app/Support/Ui/GovernanceArtifactTruth/ArtifactTruthPresenter.php), and current review/evidence/pack relationships for customer-safe findings, accepted-risk, and proof framing.
|
|
|
|
**Rationale**:
|
|
- The workspace page already derives `finding_outcomes` and `risk_acceptance` summary content from the current review payload.
|
|
- `ArtifactTruthPresenter` already normalizes review and pack freshness/publication semantics.
|
|
- The productization gap is wording, priority, and explicit unavailable-state behavior, not missing domain truth.
|
|
|
|
**Alternatives considered**:
|
|
- Introduce a customer-review presenter or new derived persistence layer.
|
|
- Rejected: adds structure without new source-of-truth need.
|
|
- Inline a second page-local taxonomy for findings and proof states.
|
|
- Rejected: creates shared-language drift across workspace, review, and pack surfaces.
|
|
|
|
## Decision 4 — Keep accepted-risk accountability rooted in existing finding-exception truth
|
|
|
|
**Decision**: Accepted-risk accountability remains derived from existing `FindingException` and current decision truth where available; missing accountable-person or accountable-role data must surface as partial/unavailable disclosure rather than a fabricated customer-safe summary.
|
|
|
|
**Rationale**:
|
|
- The spec explicitly forbids new persistence and new decision stores.
|
|
- Existing `FindingException` truth already includes owner, approver, current decision, validity, review due, and evidence reference relationships.
|
|
- Productization requires better accountability framing, but not a parallel accepted-risk model.
|
|
|
|
**Alternatives considered**:
|
|
- Add a new customer-accountability projection.
|
|
- Rejected: violates the no-new-persistence goal.
|
|
- Hide accepted-risk accountability when details are incomplete.
|
|
- Rejected: weakens the governance-of-record objective and obscures truthful partiality.
|
|
|
|
## Decision 5 — Keep workspace and tenant isolation on the current capability-first seams
|
|
|
|
**Decision**: Reuse [../../apps/platform/app/Services/TenantReviews/TenantReviewRegisterService.php](../../apps/platform/app/Services/TenantReviews/TenantReviewRegisterService.php), [../../apps/platform/app/Services/Auth/RoleCapabilityMap.php](../../apps/platform/app/Services/Auth/RoleCapabilityMap.php), and [../../apps/platform/app/Support/Auth/Capabilities.php](../../apps/platform/app/Support/Auth/Capabilities.php) as the isolation and entitlement seams.
|
|
|
|
**Rationale**:
|
|
- The current workspace page already uses `canAccessWorkspace(...)`, `authorizedTenants(...)`, and the current workspace context.
|
|
- The existing test family already proves `404` semantics for out-of-scope tenant targeting on the workspace route.
|
|
- Capability-first reuse avoids new role families or customer-only policy forks.
|
|
|
|
**Alternatives considered**:
|
|
- Add new customer-review roles or customer-specific policy branches.
|
|
- Rejected: outside scope and unnecessary for the current admin-plane audience.
|
|
- Resolve optional proof access by hiding the entire review.
|
|
- Rejected: the review should remain readable even when optional proof is unavailable.
|
|
|
|
## Decision 6 — Treat access, absence, unavailable, expired, and redacted conditions as derived disclosure states only
|
|
|
|
**Decision**: The follow-up should make access, absence, unavailable, expired, and redacted conditions explicit across workspace, review, evidence, and pack paths, but these remain derived view semantics rather than new persisted statuses.
|
|
|
|
**Rationale**:
|
|
- The current workspace page already distinguishes `No published review available yet` and pack availability from persisted review lifecycle state.
|
|
- The spec explicitly rejects new state families and new persistence.
|
|
- Explicit customer-safe disclosure is the sellability gap; a new persisted taxonomy is not.
|
|
|
|
**Alternatives considered**:
|
|
- Add a new customer-availability enum family.
|
|
- Rejected: presentation-only distinction with no new lifecycle consequence.
|
|
- Leave absence and unavailable states implicit.
|
|
- Rejected: that is the current productization gap.
|
|
|
|
## Decision 7 — Reuse the current review-pack and evidence proof routes instead of adding new proof viewers
|
|
|
|
**Decision**: Keep [../../apps/platform/app/Http/Controllers/ReviewPackDownloadController.php](../../apps/platform/app/Http/Controllers/ReviewPackDownloadController.php), [../../apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php](../../apps/platform/app/Filament/Resources/ReviewPackResource/Pages/ViewReviewPack.php), and [../../apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php](../../apps/platform/app/Filament/Resources/EvidenceSnapshotResource/Pages/ViewEvidenceSnapshot.php) as the only proof/detail routes reused by this feature.
|
|
|
|
**Rationale**:
|
|
- Current pack download already enforces tenant access, capability checks, readiness, expiry, and audit logging.
|
|
- Current evidence resource routing already exists and is referenced by review and pack truth presenters.
|
|
- The follow-up only needs clearer proof-pointer semantics and explicit unavailable states, not a new viewer family.
|
|
|
|
**Alternatives considered**:
|
|
- Add a new customer-proof page or customer-only download endpoint.
|
|
- Rejected: duplicates existing review-pack and evidence seams.
|
|
- Surface raw evidence payloads directly on the workspace page.
|
|
- Rejected: violates customer-safe disclosure hierarchy.
|
|
|
|
## Decision 8 — Reuse the existing audit pipeline and extend it only where access moments are still missing
|
|
|
|
**Decision**: Keep all auditing on [../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php](../../apps/platform/app/Services/Audit/WorkspaceAuditLogger.php) and [../../apps/platform/app/Support/Audit/AuditActionId.php](../../apps/platform/app/Support/Audit/AuditActionId.php). Existing review-open and pack-download actions stay authoritative, and only bounded additive action IDs should be considered if workspace access or proof access moments are not yet covered.
|
|
|
|
**Rationale**:
|
|
- The current customer-workspace review handoff already logs `TenantReviewOpened`.
|
|
- The current signed pack download route already logs `ReviewPackDownloaded`.
|
|
- The repo does not currently show a matching evidence-proof-open audit on the customer-workspace flow, so that is the bounded gap to evaluate.
|
|
|
|
**Alternatives considered**:
|
|
- Create a new customer-review audit table or analytics stream.
|
|
- Rejected: unnecessary persistence and duplication.
|
|
- Leave workspace/proof access unaudited.
|
|
- Rejected: the spec explicitly requires auditability for those consumption moments.
|
|
|
|
## Decision 9 — Keep browser coverage bounded to the existing smoke harness
|
|
|
|
**Decision**: Reuse [../../apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php](../../apps/platform/tests/Browser/Reviews/CustomerReviewWorkspaceSmokeTest.php) as the single browser smoke proof and expand only the existing `tests/Feature/Reviews/*` family for the rest.
|
|
|
|
**Rationale**:
|
|
- The repo already has a browser harness for the review-detail-to-workspace handoff and calm disclosure checks.
|
|
- The rest of the productization contract is better proven in focused feature tests for omission rules, access states, and audit metadata.
|
|
- Adding a broader browser family would expand governance cost without clearer business proof.
|
|
|
|
**Alternatives considered**:
|
|
- Add multiple new browser tests for each proof path.
|
|
- Rejected: too heavy for a bounded productization follow-up.
|
|
- Rely on browser testing alone.
|
|
- Rejected: feature tests remain the narrower proof for RBAC and disclosure-state coverage.
|
|
|
|
## Decision 10 — Keep the feature asset-light and non-search-expanding
|
|
|
|
**Decision**: Do not add a new asset bundle, new panel assets, or any new global-search scope as part of this follow-up.
|
|
|
|
**Rationale**:
|
|
- The work is a content/disclosure/productization pass over existing Filament surfaces.
|
|
- Existing review, review-pack, and evidence resources already avoid global-search exposure in this customer-safe path.
|
|
- The user explicitly scoped out heavy asset strategy and new global-search work.
|
|
|
|
**Alternatives considered**:
|
|
- Add new visual infrastructure or customer-safe asset loading.
|
|
- Rejected: no product need for this slice.
|
|
- Add a new search entry point for the customer workspace.
|
|
- Rejected: outside the tenant-safe reuse boundary and unnecessary for the current route. |