KArtSell.Aegis/docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/executable-scenario-governance-v18.md

KBX v18 Executable Scenario Governance

목적

정적 Screen/Field/API/권한 계약이 맞아도 실제 통합 흐름은 깨질 수 있다. v18은 KBX Definition of Done의 Vitest/Playwright/API Contract 요구를 업무 Scenario Catalog로 묶는다.

3계층

1. Contract — 순수 TypeScript/C# 계약, 상태머신, Mapping, Policy
2. Integration — ephemeral PostgreSQL, 실제 Migration/SQL/Domain/Idempotency/Outbox
3. E2E — Playwright로 Keyboard/Mouse/Focus/Scanner/Excel/Workspace 실제 흐름

Screenshot은 Evidence 중 하나일 뿐 업무 성공의 대체물이 아니다.

Canonical Scenario

Golden Screen과 주요 운영 경계는 최소 하나의 canonical scenario를 가져야 한다.

• OMS-ORD-001: 대량출고 부분성공 + Idempotency replay
• OMS-ORD-002: F2/F8 Keyboard + concurrency conflict
• OMS-ORD-003: Excel 4 valid / 2 invalid partial commit
• WMS-PICK-001: scan replay + wrong-item no-retry
• COMMON-OPS-001: stale event 방어
• COMMON-REC-001: grace period
• ERP-INV-MOVE-001: workflow/DB constraint
• Application Shell: unsaved tab

원칙

• Route 문자열 대신 API operationId를 Scenario에서 사용한다.
• idempotency=required API 호출 Scenario는 고정 idempotency key reference가 필수다.
• 실제 고객/주문/전화번호/주소를 Fixture로 복사하지 않는다.
• Test 결과는 Scenario ID + Contract Version + Evidence hash로 재현 가능해야 한다.