79 lines
3.7 KiB
Markdown
79 lines
3.7 KiB
Markdown
# Customer Experience Contract
|
|
|
|
This contract defines observable behaviour. Exact endpoint paths may remain compatible with existing
|
|
routes or be introduced additively during implementation.
|
|
|
|
## Common Response State
|
|
|
|
Every customer-facing state-bearing response provides:
|
|
|
|
- canonical `state` and `severity`;
|
|
- `observed_at` and explicit freshness when not live;
|
|
- plain-language `summary` and customer impact;
|
|
- stable non-secret `code` for support correlation;
|
|
- ordered `next_actions`, filtered by authorization;
|
|
- `correlation_id` when an operation or failure is involved.
|
|
|
|
Raw exceptions, stack traces, signed license material, credentials, tokens, document content, and
|
|
secret-bearing command output MUST NOT appear.
|
|
|
|
## Readiness Interface
|
|
|
|
The readiness interface returns the ApplianceReadiness model. It MUST distinguish:
|
|
|
|
- product/API unreachable from a degraded dependent capability;
|
|
- licensed from provisioned, hardware-supported, and currently available;
|
|
- ready from stale last-known-ready;
|
|
- customer impact from technical diagnostic detail.
|
|
|
|
Phase 1 may extend the existing readiness-report route additively. Existing fields remain until all
|
|
packaged consumers move to the versioned contract.
|
|
|
|
## Operation Interface
|
|
|
|
Supported behaviours:
|
|
|
|
1. **Create/acknowledge**: validates authorization, prerequisites, conflicts, scope, and confirmation.
|
|
2. **Read**: returns durable current state by operation ID after refresh, restart, or session change.
|
|
3. **List**: returns role-filtered recent and active operations.
|
|
4. **Act**: exposes only valid retry/resume/cancel/recovery actions for the current state.
|
|
|
|
Creation MUST be idempotent for duplicate customer submissions within the defined request window.
|
|
Conflicting operations return a customer-facing explanation and reference the blocking operation.
|
|
Every operation interface enforces server-side authorization and is tested for both permitted and
|
|
denied roles. Removal additionally exposes retained/deleted data categories and preserves backups by
|
|
default unless a separately confirmed policy explicitly requires deletion.
|
|
|
|
## Error Contract
|
|
|
|
Errors provide status, stable `code`, plain-language `message`, `affected_scope`, safe
|
|
`remediation`, and optional `correlation_id`. Validation errors identify fields without discarding
|
|
other valid setup progress. Authorization errors do not reveal protected resource existence.
|
|
|
|
## Entitlement Contract
|
|
|
|
Customer-facing output uses Workstation and Server S/M/L/Max labels. Compatibility identifiers may
|
|
appear only in authorized diagnostics. Every capability state identifies one primary reason:
|
|
licensed, not licensed, not provisioned, unsupported by hardware, degraded, or unavailable.
|
|
|
|
## Audit Contract
|
|
|
|
Every privileged, security-sensitive, licensing, configuration, and lifecycle action records actor,
|
|
time, category, redacted scope, result, and correlation ID. Secret values and signed payloads are
|
|
never recorded. Denied and failed actions are auditable where safe.
|
|
|
|
## Accessibility Contract
|
|
|
|
- All functionality is operable by keyboard with visible focus and logical order.
|
|
- Dynamic status and validation feedback is programmatically announced without stealing focus.
|
|
- Labels, instructions, errors, and confirmations are programmatically associated.
|
|
- Status and severity never rely on colour alone.
|
|
- Content supports required contrast, zoom, reflow, and reduced-motion behaviour.
|
|
- Acceptance requires automated and representative manual WCAG 2.2 AA evidence.
|
|
|
|
## Release Evidence Contract
|
|
|
|
Each phase records source revision, package/ISO identity and checksum, test environment, product
|
|
configuration, validation results, known limitations, pilot findings, resolutions, and joint approval
|
|
from product ownership and delivery/support.
|