# 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