TenantAtlas/specs/275-customer-facing-localization-adoption/data-model.md

Data Model — Customer-Facing Localization Adoption v1

Spec: /Users/ahmeddarrazi/Documents/projects/wt-plattform/specs/275-customer-facing-localization-adoption/spec.md

No new persisted tables, locale stores, or glossary registries are required for this feature. The slice reuses existing locale truth, current review and artifact truth, and current translation catalogs, then tightens the derived localized view contracts for the customer-facing review flow.

Supported Locale Set

Value	Meaning	Notes
en	English	Controlled fallback locale for this slice
de	German	Only additional supported locale in scope

Reused Source Truth

Locale Context

Purpose: Resolve the effective locale for the current customer-facing review request.

Reused carriers:

• session override tenantpilot.locale_override
• users.preferred_locale
• existing workspace setting localization.default_locale
• config('app.fallback_locale')

Relevant fields:

• locale
• source
• fallback_locale
• user_preference_locale
• workspace_default_locale
• machine_artifacts_invariant

Validation rules:

• the only supported values remain en and de
• unsupported input falls back through the existing precedence chain until a supported locale is found
• locale changes affect only rendered copy and feedback, not authorization or machine-readable artifacts

Workspace / Tenant Entitlement Context

Purpose: Keep the current workspace boundary and entitled tenant set authoritative before any localized workspace row or released-review detail is composed.

Reused carriers:

• existing workspace membership rows
• existing tenant membership and role assignments
• existing capability registry and role-capability map
• current workspace and remembered-tenant session context

Validation rules:

• non-members remain 404
• only entitled tenants in the active workspace may appear in the localized customer review workspace
• locale changes must not widen tenant or artifact visibility

TenantReview

Purpose: Canonical source for the released customer review detail, current package truth, proof pointers, and existing summary copy inputs.

Reused carrier: existing tenant_reviews rows via App\Models\TenantReview

Relevant fields / relationships:

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

Validation rules:

• the customer-safe path continues to use the latest published review per entitled tenant only
• localized wording may change, but the underlying review truth and route ownership do not
• the released-review detail remains the only secondary context surface in customer-workspace mode

ReviewPack and EvidenceSnapshot

Purpose: Existing supporting artifact truth for package availability, proof availability, and blocked or expired reasons.

Reused carriers:

• existing review_packs rows via App\Models\ReviewPack
• existing evidence_snapshots rows via App\Models\EvidenceSnapshot

Relevant fields / relationships:

• ReviewPack.status
• ReviewPack.expires_at
• ReviewPack.file_path
• EvidenceSnapshot.status
• EvidenceSnapshot.completeness_state
• EvidenceSnapshot.expires_at

Validation rules:

• localized package and proof reasons stay derived from existing truth
• signed review-pack download behavior stays unchanged
• secondary proof access remains capability-gated and lower priority than the review summary

Translation Catalog Assets

Purpose: Derived presentation assets that hold the approved customer-facing glossary and locale feedback copy.

Reused carriers:

• apps/platform/lang/en/localization.php
• apps/platform/lang/de/localization.php

Relevant key families:

• review.*
• notifications.*
• validation.*

Validation rules:

• in-scope customer-facing terms must resolve to approved EN or DE copy
• missing in-scope German lines must fall back to English
• raw translation keys must not appear on the default customer-safe path
• provider-specific artifact names stay secondary and already-gated

Audit / Machine Artifact Boundary

Purpose: Preserve stable machine truth while customer-facing copy changes.

Reused carriers:

• existing audit_logs
• current review-pack files and signed download responses
• raw JSON and other machine-readable artifact payloads already produced by the product

Validation rules:

• audit action IDs and metadata remain untranslated
• review-pack file bytes, hashes, identifiers, timestamps, and raw payloads remain unchanged
• localization changes only the surrounding UI language and feedback text

Derived View Contracts

LocalizedCustomerReviewWorkspacePageModel

Purpose: Request-time localized page contract for /admin/reviews/workspace.

Persistence: none; derived at request or Livewire render time

Fields:

• workspace_id
• tenant_filter_id (nullable)
• resolved_locale
• heading_copy
• intro_copy
• disclosure_copy
• entries[]
• empty_state_copy (nullable)
• untranslated_keys_detected = false
• machine_artifacts_invariant = true

Validation rules:

• locale changes must not reset tenant filters or remembered workspace context
• all default-visible copy must resolve from approved EN or DE lines
• the page keeps one dominant row action: Open review

LocalizedAccessMessage

Purpose: Reused localized access-state message object for governance-package and proof availability on the current customer-safe review flow.

Persistence: none; derived from existing review-pack and evidence truth

Fields:

• state
• label
• description (nullable)
• translation_key (nullable)

Validation rules:

• the only allowed states stay inside the existing derived disclosure set: available, partial, unavailable, blocked, and expired
• any current not-ready wording remains a reason-level description under the existing unavailable state instead of becoming a new state family
• the optional translation_key is trace-only and must never leak to the rendered customer-safe surface

LocalizedCustomerReviewWorkspaceEntry

Purpose: Localized row-level summary for one entitled tenant in the customer review workspace.

Persistence: none; derived from existing tenant, review, pack, and proof truth

Fields:

• tenant_id
• tenant_name
• latest_published_review_id (nullable)
• review_status_label
• accepted_risk_summary (nullable)
• governance_package (LocalizedAccessMessage)
• proof_access (LocalizedAccessMessage)
• next_step_label (nullable)
• primary_action_label
• primary_action_url (nullable)

Validation rules:

• optional package or proof restrictions must not hide the readable review row
• accepted-risk summary copy must use the same approved glossary as the released-review detail
• glossary terms must match the released-review detail surface
• untranslated or mixed-language states are treated as defects, not acceptable partials

LocalizedCustomerReviewDetailModel

Purpose: Request-time localized detail contract for /admin/t/{tenant}/reviews/{review} when launched from the customer review workspace.

Persistence: none; derived from the existing review record and current customer_workspace query flag

Fields:

• review_id
• tenant_id
• resolved_locale
• launched_from_customer_workspace
• dominant_action_label
• section_labels[]
• accepted_risk_summary (nullable)
• governance_package (LocalizedAccessMessage)
• proof_access (LocalizedAccessMessage)
• helper_copy[]
• operator_actions_hidden = true
• machine_artifacts_invariant = true

Validation rules:

• customer-workspace mode remains read-only
• Download governance package remains the single dominant header action when available
• detail section labels and accepted-risk summary must align with the workspace glossary
• localized helper text must not invent new artifact or workflow states

LocalizedLocaleFeedbackMessage

Purpose: Existing session-backed feedback contract returned by locale override and personal preference updates.

Persistence: session flash only

Fields:

• route_name
• resolved_locale
• status_message

Validation rules:

• feedback renders in the newly effective locale
• unsupported locale input uses the existing localized validation message path
• no new notification framework is introduced

CustomerFacingGlossaryInventory

Purpose: Planning-only inventory of the terms that must stay aligned across workspace, detail, and locale-feedback surfaces.

Persistence: none; maintained as catalog coverage, not a new table or registry

Core terms:

• customer review
• governance package
• current review pack
• proof access
• next step
• review status
• evidence
• accepted risk
• customer-safe detail

Validation rules:

• the same term should not appear with conflicting customer-facing synonyms across workspace and detail
• out-of-scope artifacts such as raw JSON, audit payloads, and export file contents remain outside the glossary inventory

Derived Disclosure States

This slice introduces no new persisted enum or state family. It reuses the current customer-facing labels and reasons as derived presentation only:

• available
• partial
• unavailable
• blocked
• expired

These remain localized labels and helper text over existing review-pack and proof truth. They do not become new stored lifecycle values.

Invariance Boundaries

The following remain unlocalized in v1:

• review-pack file contents and hashes
• raw JSON and machine-readable payloads
• audit action identifiers and metadata keys or values
• identifiers, slugs, route parameters, and query semantics
• workspace and tenant entitlement outcomes