115 lines
5.3 KiB
Markdown
115 lines
5.3 KiB
Markdown
# 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.
|