5.3 KiB
5.3 KiB
Data Model: Enterprise Appliance Experience Hardening
ApplianceReadiness
Customer-facing aggregate of appliance state.
| Field | Rules |
|---|---|
schema_version |
Required contract version |
state |
One of loading, empty, ready, degraded, failed, restricted, unavailable, stale |
severity |
info, warning, critical |
observed_at |
UTC timestamp for underlying observation |
freshness_seconds |
Non-negative age at response time |
summary |
Plain-language customer impact |
affected_capabilities |
Customer-facing capability identifiers, not raw service names |
next_actions |
Ordered safe actions with required role and action kind |
checks |
Component/capability observations using the same state contract |
entitlement |
Reference to current EntitlementState summary |
State precedence: failed/critical impact outranks degraded; stale MUST be reported when freshness is outside the defined check window even if the previous observation was ready.
Operation
Durable record for installation and consequential or long-running actions.
| Field | Rules |
|---|---|
id |
Stable opaque identifier |
correlation_id |
Stable across API, audit, logs, and support evidence |
kind |
setup, install, backup, restore, upgrade, restart, remove, reconcile, diagnostic_export, other |
actor_id / actor_name |
Authenticated actor or explicit system/installer identity |
scope |
Redacted description of affected appliance resources |
state |
requested, validating, queued, running, awaiting_reboot, succeeded, failed, cancelled, recovery_required |
progress_percent |
0–100 only when meaningful; otherwise omitted |
progress_label |
Plain-language current phase |
requested_at, started_at, updated_at, finished_at |
UTC timestamps |
result_code |
Stable non-secret machine-readable result |
customer_message |
Plain-language outcome and impact |
recovery_actions |
Safe retry/resume/rollback/restore/restart/escalate actions |
metadata |
Allowlisted, versioned, non-secret details only |
Transitions are monotonic except explicit retry, which creates a new Operation linked to its parent. Terminal states are succeeded, failed, cancelled, and recovery_required. Concurrent conflicting operations MUST be rejected or queued with an explanation.
Removal operation metadata includes an allowlisted retained-data inventory, deleted-data categories, backup preservation status, and rollback limitations; it never includes protected content values.
EntitlementState
| Field | Rules |
|---|---|
category |
workstation or server |
commercial_label |
Workstation or Server S/M/L/Max |
compatibility_tier |
workstation or starter/basic/pro/max; not primary customer text |
license_state |
valid, missing, expired, invalid, mismatch, other stable states |
licensed_capabilities |
Capability keys from signed entitlement evaluation |
provisioned_capabilities |
Derived from install record and deployed roles |
hardware_capabilities |
Derived from feasibility evidence |
available_capabilities |
Current intersection adjusted for runtime health |
observed_at |
UTC evaluation time |
The model MUST distinguish why a capability is unavailable: commercial entitlement, provisioning, hardware, or current runtime condition.
AuditEvent
| Field | Rules |
|---|---|
id |
Monotonic appliance-local identifier |
occurred_at |
UTC timestamp |
actor_id / actor_name |
Actor identity when known |
action_category |
Stable category rather than secret-bearing free text |
scope |
Redacted affected resource |
result |
success, failure, denied, partial |
correlation_id |
Links to Operation and support evidence |
detail |
Allowlisted, redacted context |
SupportEvidencePackage
Logical export; raw secret-bearing files are excluded by default.
| Field | Rules |
|---|---|
package_id |
Opaque identifier |
created_at / created_by |
UTC time and authorized actor |
product_identity |
Product category, commercial label, version/build identity |
entitlement_summary |
Status and capability summary without signed payload or key |
readiness_snapshot |
ApplianceReadiness contract |
operations |
Selected redacted Operation records |
audit_events |
Selected redacted AuditEvent records |
component_evidence |
Allowlisted health/version/status data |
redaction_report |
Categories excluded or transformed |
checksum |
Integrity checksum of the completed export |
GuidanceItem
| Field | Rules |
|---|---|
id |
Stable local identifier |
journey |
setup, readiness, administration, recovery, support |
trigger_state |
Optional state or result code |
required_role |
Minimum role permitted to execute actions |
title, summary, steps |
Plain-language local guidance |
action_kind |
navigate, retry, resume, rollback, restore, restart, escalate |
version |
Guidance revision aligned to packaged product |
Relationships
- ApplianceReadiness references one current EntitlementState and zero or more active Operations.
- Operation produces AuditEvents and may be included in a SupportEvidencePackage.
- SupportEvidencePackage contains snapshots, never live mutable references.
- GuidanceItems are selected by journey, state, role, and result code.