TenantAtlas/specs/249-customer-review-workspace/data-model.md

Data Model — Customer Review Workspace v1

Spec: spec.md

No new persisted tables or customer-review entities are required for v1. The feature reuses existing tenant-owned review, review-pack, evidence, findings, and audit truth, then derives one workspace-scoped read model for page presentation.

Persisted Truth Reused

Workspace / Tenant Entitlement Context

Purpose: Establish the current workspace boundary and the entitled tenant set before any review rows are composed.

Persisted carriers:

• existing workspace membership records
• existing tenant membership pivot records and tenant role assignments
• existing capability registry and role-capability map

Relevant fields / contracts:

• workspace_id
• tenant_id
• tenant membership role
• capability grants derived from ../../apps/platform/app/Support/Auth/Capabilities.php

Validation rules:

• current actor must be a member of the current workspace or the page resolves as not found
• tenant rows may only be composed for tenants in the current workspace where the actor is entitled through the canonical role-capability map
• no cross-workspace or cross-tenant fallback lookups are allowed

TenantReview

Purpose: Canonical source for the latest customer-safe review posture, summary text, findings summary, accepted-risk summary, and primary inspect target.

Persisted carrier: existing tenant_reviews rows via TenantReview

Relevant fields / relationships:

• id
• workspace_id
• tenant_id
• status
• generated_at
• published_at
• summary
• evidence_snapshot_id
• current_export_review_pack_id
• tenant
• evidenceSnapshot
• currentExportReviewPack
• sections

Validation / usage rules:

• the default customer-safe path uses the latest published review per entitled tenant
• draft, ready, failed, archived, and superseded reviews stay off the default-visible page summary unless explicitly reused as internal proof elsewhere
• summary data already shaped into the review artifact remains the preferred source for findings and review-level posture messaging

TenantReviewSection

Purpose: Supporting persisted proof for accepted-risk and section-level disclosure without introducing a new workspace summary store.

Persisted carrier: existing tenant_review_sections rows

Relevant fields / relationships:

• tenant_review_id
• section_key
• title
• completeness_state
• summary_payload
• render_payload

Validation / usage rules:

• accepted-risk summaries should come from the existing review section payloads that were already composed for the review artifact
• section payload reuse must remain read-only and redaction-safe

ReviewPack

Purpose: Canonical packaged artifact for customer-safe review consumption and download.

Persisted carrier: existing review_packs rows via ReviewPack

Relevant fields / relationships:

• id
• workspace_id
• tenant_id
• tenant_review_id
• status
• generated_at
• expires_at
• summary
• file_path
• file_disk
• sha256
• tenantReview
• evidenceSnapshot

Validation / usage rules:

• download is available only when the current pack is ready and not expired
• the workspace page may surface availability and a signed download path only when REVIEW_PACK_VIEW applies
• the workspace page must not start generation, regeneration, or recovery flows

EvidenceSnapshot

Purpose: Existing proof artifact for freshness and evidence completeness when the actor explicitly asks for supporting detail.

Persisted carrier: existing evidence_snapshots rows via EvidenceSnapshot

Relevant fields / relationships:

• id
• workspace_id
• tenant_id
• status
• completeness_state
• generated_at
• expires_at
• summary
• items

Validation / usage rules:

• evidence detail is not part of the default-visible customer path
• drilldown remains explicit and capability-gated by EVIDENCE_VIEW
• evidence truth remains tenant-owned and derived from the existing snapshot lifecycle

Audit Log Event Family

Purpose: Existing audit truth for explicit review-artifact access and download actions.

Persisted carrier: existing audit_logs rows via WorkspaceAuditLogger

Relevant fields / contracts:

• stable AuditActionId
• workspace_id
• optional tenant_id
• actor metadata
• target resource type / id / label
• action context metadata

Validation / usage rules:

• no new audit store is introduced
• explicit artifact open/download events should reuse the current audit pipeline
• page render itself should not become a noisy new audit family

Derived Read Model

CustomerReviewWorkspaceEntry

Purpose: Derived page row or card summarizing the latest customer-safe review state for one entitled tenant.

Persistence: none; computed at request time

Fields:

• workspace_id
• tenant_id
• tenant_name
• latest_published_review_id (nullable)
• latest_review_generated_at (nullable)
• latest_review_published_at (nullable)
• review_outcome_label (nullable, derived from existing artifact truth)
• review_outcome_explanation (nullable)
• key_findings_summary (nullable, derived from existing review summary)
• accepted_risk_summary (nullable, derived from existing review section payloads)
• review_pack_id (nullable)
• review_pack_available (boolean)
• review_pack_status_note (nullable derived string)
• evidence_snapshot_id (nullable)
• primary_review_url (nullable)
• review_pack_download_url (nullable)
• evidence_detail_url (nullable)
• redaction_note (nullable)
• absence_note (nullable derived string)

Derivation rules:

• exactly one entry exists per entitled tenant visible in the current workspace scope
• when a published review exists, the entry derives customer-safe posture from that latest published review only
• when no published review exists for an entitled tenant, the entry may carry a derived absence note such as No published review available yet; this remains view logic, not domain state
• raw JSON, raw provider payloads, unrestricted audit metadata, fingerprints, and debug-only context are never part of the entry

Validation rules:

• entries may only be built for tenants in the current workspace and current entitlement scope
• review_pack_download_url is present only when a current pack exists and the actor can view it
• evidence_detail_url is present only when the actor can view evidence detail
• absence or unavailable wording must not hint at hidden drafts or hidden operator-only artifacts

Request-Scoped Page State

CustomerReviewWorkspaceState

Purpose: Livewire-safe page state carrying tenant launch context and remembered filters.

Persistence: request, query, and session-backed page state only

Fields:

• tenant_id (nullable requested prefilter)
• highlight_tenant_id (nullable)
• launch_source (nullable string such as review, review_pack, evidence, or dashboard)
• search (nullable)
• tableFilters (session-backed when the implementation uses table filters)

Validation rules:

• requested tenant filters must resolve to an entitled tenant or the page should respond as not found for explicit tenant targeting
• state that needs to survive Livewire interactions must remain hydrated public or query/session-backed state
• if implementation adds a secondary status filter, it must operate on customer-safe derived labels only, not raw internal lifecycle states

State Transition Summary

This slice introduces no new persisted lifecycle or status family. Only derived page-state transitions are expected:

• default workspace view -> tenant-prefiltered view
• tenant-prefiltered view -> cleared workspace view
• published review available -> inspect or download action available subject to capability checks
• no published review available -> truthful absence message only

No queue, publish, generate, regenerate, remediate, or archive transition belongs to this page.