docs: define provider rollback evidence runbook (AEG-V16-015)

Document startup-only provider switching, immutable-artifact rollback, and mandatory visual/accessibility/performance evidence. Status remains IN_PROGRESS until rehearsal and predecessor evidence exist.
2026-08-08 12:58:05 +09:00
parent b78c19646f
commit 52bdf926ad
2 changed files with 73 additions and 0 deletions
@@ -8,6 +8,7 @@ AEG-X-006,S0,Cross,Outbox publisher 고도화,COMPLETED,2026-08-04,"docs/CURRENT
 AEG-X-007,S0,Cross,Serilog/OTel correlation 고도화,COMPLETED,2026-08-06,"tests/KArtSell.ArchitectureTests/PiiRedactionTests.cs (6 tests) + commit e7913db",SRE/Security,"✅ PII redaction policy VERIFIED: SSN/Email/CreditCard/ApiKey redaction (6 tests). Commit e7913db adds pattern-based sanitization validation. All tests PASS (249/253)."
 AEG-V16-017,S6,Cross,FieldShell 표준,IN_PROGRESS,TBD,"docs/CURRENT/AEG-V16-017_FIELDSHELL_SLICE_NOTE.md; frontend/src/shared/ui/components/FieldShell.vue; frontend/src/shared/ui/components/tests/FieldShell.spec.ts","FE Lead","2026-08-08: FieldShell now owns label/error/help/ARIA relationships for KsTextField, KsTextArea, KsSelect, KsDateField, and KsNumberField. Actual evidence: frontend pnpm typecheck PASS; pnpm test PASS (19 files, 42 tests); pnpm build PASS. Build emitted unrelated tracked .js drift, excluded from this Slice. COMPLETED is blocked pending WBS Master/tracker reconciliation and AEG-V16-016 vendor-boundary acceptance evidence."
 AEG-V16-016,S0,VS-00,Vendor boundary fitness,IN_PROGRESS,TBD,"docs/CURRENT/AEG-V16-016_VENDOR_BOUNDARY_SLICE_NOTE.md; tools/validate_v16.py; frontend/src/shared/ui/adapter/tests/uiAdapter.contract.spec.ts","FE Lead","2026-08-08: Removed stale fixed WBS row-count assertion; validator now verifies WBS ID integrity and reports vendor imports outside the approved adapter boundary. Actual evidence: python tools/validate_v16.py PASS=1 WARN=2 FAIL=0; targeted adapter tests 4/4 PASS; frontend typecheck PASS. COMPLETED is blocked because dependency AEG-V16-015 has no approved acceptance evidence in the tracker."
 AEG-V16-015,S0,VS-00,Adapter rollback runbook,IN_PROGRESS,TBD,"docs/CURRENT/ui-provider-switch.md","FE Lead","2026-08-08: Created startup-only provider switch and rollback runbook with fail-closed configuration, immutable-artifact rollback, and append-only evidence record. Visual/a11y/performance rehearsal evidence is not present and is explicitly required before completion; dependency AEG-V16-014 is also not evidenced in the tracker."
 AEG-X-008,S0,Cross,OpenAPI artifact 고도화,COMPLETED,2026-08-04,.gitea/workflows/openapi-gate.yml + docs/api/openapi.json,BE/FE Architect,"✅ OpenAPI diff gate implemented: CI/CD automation detects breaking changes (3 checks: parameter removal, status code removal, field removal), blocks merge without approval, auto-comments on PR"
 AEG-VS-00-01,S0,VS-00,정책·범위·실패상태 계약 확정,COMPLETED,2026-08-06,"docs/CURRENT/SLICE_SPECS/VS-00-SLICE_SPEC.md + commit e7913db",PM/Architect,"✅ SLICE_SPEC produced: VS-00-SLICE_SPEC.md (state transitions, RBAC, governance gates, DQ rules, compliance). Commit e7913db. 249/253 tests PASS."
 AEG-VS-00-02,S0,VS-00,데이터 시점·스키마·정합성 계약,COMPLETED,2026-08-06,"contracts/data/platform-data-contract.v1.json + commit e7913db",Data Architect/DBA,"✅ DATA_CONTRACT v1.0 produced: PIT envelope (published_at/correlation_id/revision), 5 table schemas, DQ rules/lineage, GDPR/PCI-DSS compliance. JSON schema + validation. 249/253 tests PASS."
@@ -0,0 +1,72 @@
 # 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):
 ```