Add enterprise appliance experience Phase 1 foundation

specs/001-enterprise-experience/research.md

@@ -0,0 +1,94 @@
+# Research: Enterprise Appliance Experience Hardening
+
+## Decision 1: Evolve the Existing Architecture
+
+**Decision**: Retain the static portal, FastAPI management API, SQLite appliance store, shell/Ansible
+installer, Nginx, and systemd deployment model.
+
+**Rationale**: The current architecture already exposes authentication, audit, readiness, entitlement,
+backup/restore, health, and installation flows. Enterprise quality depends first on consistent state,
+durability, recovery, and validation—not a framework rewrite that would expand risk.
+
+**Alternatives considered**: Rebuild the portal as a single-page application; split the backend into
+services; adopt an external workflow engine. Deferred because none is required to satisfy Phase 1.
+
+## Decision 2: Use Durable Operations as the Cross-Surface Backbone
+
+**Decision**: Represent installation and later consequential actions as durable operation records
+with lifecycle, progress, actor, scope, timestamps, result, recovery action, and correlation ID.
+
+**Rationale**: Browser setup currently keeps install status in process memory, while the API runs
+multiple workers and appliance actions can outlive sessions or processes. A durable record provides
+one truth for refresh, restart, audit, diagnostics, and support.
+
+**Alternatives considered**: Continue process-local status; infer progress exclusively from logs; add
+a separate message broker. Process-local status is not recoverable, logs are not a stable customer
+contract, and a broker is unnecessary for the current appliance scale.
+
+## Decision 3: Define One Customer-Facing State Vocabulary
+
+**Decision**: Normalize state into `loading`, `empty`, `ready`, `degraded`, `failed`, `restricted`,
+`unavailable`, and `stale`, with severity, freshness, impact, and next action.
+
+**Rationale**: Existing pages use several incompatible labels and colour treatments. A shared contract
+prevents each page from inventing meaning and supports accessibility and acceptance tests.
+
+**Alternatives considered**: Preserve page-specific vocabularies; expose raw service states. Both
+produce inconsistent customer meaning and leak implementation concepts.
+
+## Decision 4: Keep Entitlement Logic Canonical and Additive
+
+**Decision**: Preserve Workstation separation and Server compatibility identifiers. Treat
+`scripts/cezen_license.py` as canonical and verify parity with installer/backend deployed copies.
+
+**Rationale**: The repository already documents the separation and copies license helpers into more
+than one runtime location. Replacing identifiers would create avoidable upgrade and license risk.
+
+**Alternatives considered**: Rename internal tiers; merge Workstation into the Server ladder; allow
+each surface to derive its own mapping. Rejected for compatibility and drift risk.
+
+## Decision 5: Introduce Explicit SQLite Schema Evolution
+
+**Decision**: Use versioned, idempotent database migrations for new operation/support-evidence fields
+and tables, with pre-change backup and compatibility checks.
+
+**Rationale**: The backend creates many tables directly during startup. New enterprise lifecycle data
+must be safely introduced on existing customer appliances and included in backup/restore validation.
+
+**Alternatives considered**: Add only new tables through startup creation; replace SQLite; reset data
+on upgrade. Startup creation lacks controlled evolution, replacement is disproportionate, and reset is
+unacceptable for customer appliances.
+
+## Decision 6: Shared Portal Primitives Without Immediate Framework Migration
+
+**Decision**: Add shared browser-native helpers and CSS primitives for states, operations, errors,
+focus, announcements, confirmation, and entitlement rather than rewriting all pages at once.
+
+**Rationale**: The portal is a large static HTML/JavaScript surface already deployed by file sync.
+Shared primitives enable phased adoption and reduce visual/behavioural drift with minimal packaging
+change.
+
+**Alternatives considered**: Full portal rewrite; page-by-page independent cleanup. A rewrite conflicts
+with phased risk reduction; independent cleanup preserves inconsistency.
+
+## Decision 7: WCAG 2.2 AA Requires Automated and Manual Evidence
+
+**Decision**: Combine automated checks with manual keyboard, focus, status-announcement, zoom/reflow,
+and representative assistive-technology journeys.
+
+**Rationale**: Automated checks cannot prove complete accessibility, especially for dynamic status,
+error recovery, and consequential operations.
+
+**Alternatives considered**: Automated checks only; informal review; AAA. The first two are
+insufficient for formal AA acceptance; AAA exceeds the approved scope.
+
+## Decision 8: Release Through Evidence Gates
+
+**Decision**: Require internal evidence, controlled pilot evidence, joint product and delivery/support
+approval, then general release; validate both source revision and packaged artifact identity.
+
+**Rationale**: Installation and recovery changes need customer-like appliance evidence, while the
+repository contains multiple source and ISO delivery surfaces that can diverge.
+
+**Alternatives considered**: Direct general release after local tests; UI-only acceptance; checksum
+without journey validation. Each leaves a material enterprise-appliance risk untested.