kjh2064
52bdf926ad
Document startup-only provider switching, immutable-artifact rollback, and mandatory visual/accessibility/performance evidence. Status remains IN_PROGRESS until rehearsal and predecessor evidence exist.
73 lines
4.8 KiB
Markdown
73 lines
4.8 KiB
Markdown
# UI provider switch and rollback runbook
|
||
|
||
**WBS / Requirement / UI / Test:** AEG-V16-015 / REQ-V16-UI4-07 / UI-V16-UI4-07 / T-V16-UI4-07
|
||
**Owners:** FE Lead (primary), UX/QA (secondary)
|
||
**Mode:** human-approved deployment operation only; provider selection is startup-only.
|
||
|
||
## Source / Assumption / Unknown / Decision Required
|
||
|
||
- **Source:** `contracts/ui/ui-adapter.v4.json`, `frontend/src/main.ts`, `frontend/src/shared/ui/provider/resolveUiProvider.ts`, `tools/validate_v16.py`.
|
||
- **Assumption:** deployment configuration supplies `VITE_UI_ADAPTER` before building the immutable frontend artifact. The application does not read a mutable provider setting after bootstrap.
|
||
- **Unknown:** visual-regression baseline, keyboard/focus acceptance artifact, and production performance budget approval are not present in this workspace.
|
||
- **Decision Required:** FE Lead and UX/QA must approve the named target provider and attach all required evidence before a production switch. This runbook never authorizes an automatic provider switch.
|
||
|
||
## Safety invariants
|
||
|
||
1. Allowed provider values are `primevue` and `native`; any other value fails closed at startup.
|
||
2. No feature source may import PrimeVue or AG Grid. Vendor imports are confined to `frontend/src/shared/ui/adapter/primevue/`.
|
||
3. Changing a provider means building and deploying a new artifact. Do not mutate the active application's global provider.
|
||
4. Rollback restores the last approved artifact and its recorded provider value. It does not alter data, decisions, evidence, or audit records.
|
||
|
||
## Preflight — required before approval
|
||
|
||
Record the operator, UTC/KST timestamp, source commit SHA, artifact hash, previous/target provider, and correlation/change reference in the release evidence.
|
||
|
||
| Check | Required evidence | Result field |
|
||
| --- | --- | --- |
|
||
| Contract conformance | `pnpm test -- --run src/shared/ui/adapter/tests/uiAdapter.contract.spec.ts src/shared/ui/tests/adapterCompatibility.spec.ts` | test output path/hash |
|
||
| Vendor boundary | `python tools/validate_v16.py` returns `PASS=1` | output path/hash |
|
||
| Startup selection | fresh artifact starts once with the target `VITE_UI_ADAPTER` value | startup log reference |
|
||
| Keyboard/focus | approved keyboard/focus test for fields, dialog, grid, and tabs | QA evidence ID |
|
||
| Accessible name | automated/manual accessibility report for changed screens | QA evidence ID |
|
||
| State matrix | T01–T10 result for the affected screen catalogue | QA evidence ID |
|
||
| Visual regression | approved baseline comparison for target viewport set | visual evidence ID |
|
||
| Performance | approved large-list interaction evidence using the agreed budget | performance evidence ID |
|
||
|
||
Any missing, failed, expired, or mismatched evidence blocks the switch. Do not replace a missing target or baseline with a guessed threshold.
|
||
|
||
## Approved switch procedure
|
||
|
||
1. Confirm a human change approval references the exact commit, artifact hash, target provider, and all preflight evidence.
|
||
2. Build a new frontend artifact with `VITE_UI_ADAPTER=<target>`; preserve the build output and configuration hash.
|
||
3. Deploy via the approved release process. Do not change the provider inside a running application.
|
||
4. Verify the startup log identifies the target provider and that the version/hash matches the approved artifact.
|
||
5. Run the approved smoke route and the affected T01–T10 checks. Stop on the first failure and begin rollback.
|
||
6. Append the outcome, timestamps, operator, artifact hash, and evidence links to the release ledger; never overwrite a prior entry.
|
||
|
||
## Rollback procedure
|
||
|
||
Use rollback when startup selection fails, a required state/keyboard/accessibility check fails, the visual comparison is rejected, or the approved performance evidence is not reproduced.
|
||
|
||
1. Declare the change stopped; record the incident/change reference and preserve browser/server logs.
|
||
2. Select the previously approved immutable artifact and its recorded provider configuration.
|
||
3. Deploy that artifact through the approved release process; do not hot-swap the provider in memory.
|
||
4. Verify its startup provider, artifact hash, critical smoke route, and a focused regression check.
|
||
5. Append a rollback outcome with reason, timestamps, operator, evidence links, and owner/secondary notification. Retain the failed artifact and its evidence for diagnosis.
|
||
6. Open a corrective WBS/issue for the failed contract, accessibility, visual, or performance condition. A rollback does not silently waive the failed gate.
|
||
|
||
## Evidence record template
|
||
|
||
```text
|
||
Change reference:
|
||
Operator / secondary:
|
||
Previous provider + artifact SHA:
|
||
Target provider + artifact SHA:
|
||
Contract / boundary evidence:
|
||
Keyboard / accessible-name / T01–T10 evidence:
|
||
Visual / performance evidence:
|
||
Startup log reference:
|
||
Outcome: switched | blocked | rolled back
|
||
Rollback reason (if applicable):
|
||
Recorded at (UTC) / display time (KST):
|
||
```
|