3.9 KiB
KBX v36 Migration Guide
1. Screen Recipe testProfile 추가
contracts/screens/kbx.screen-recipes.json의 모든 T01~T09 Recipe는 다음을 가져야 한다.
interface KbxScreenRecipeTestProfile {
requiredScenarioKinds: ('e2e'|'integration'|'contract')[]
requiredTags: string[]
requiredEvidence: string[]
requiredChecks: string[]
}
Custom Recipe를 별도로 관리하는 소비자는 동일한 검증 정보를 추가해야 한다.
2. 새 Verification Manifest
생성 산출물이 하나 추가된다.
generated/screen-recipe-verification-manifest.json
직접 수정하지 않는다.
node scripts/generate-screen-recipe-contracts.mjs
또는 node scripts/validate-kbx.mjs를 실행한다.
3. Scaffolder 생성 파일 추가
kbx:new-screen은 기존 Definition/Page/Route/README 외에:
*.test-plan.ts
를 생성한다.
이 파일에는 Recipe의 Canonical Scenario, Required Check, Required Evidence가 들어간다. 삭제하지 말고 실제 Screen-specific Vitest/Playwright로 확장한다.
기존 보안 요구는 그대로다.
master
transaction
fast-entry
은 계속 명시적인 --write-permission이 필요하다.
4. Home Attention API
신규 권장 API:
buildKbxHomeAttentionQueue(...)
반환:
{
items,
totalCount,
overflowCount,
sourceCounts,
}
기존:
buildKbxHomeAttention(...)
은 호환을 위해 유지되며 items만 반환한다.
KbxHomeAttentionItem에는 occurredAt이 필수다. 직접 Item을 생성하는 외부 코드가 있다면 발생 시각을 넣어야 한다.
5. Home 정렬 변경
업무 Priority 자체는 변경하지 않는다.
미저장
→ 실패/부분완료
→ 중요 알림
→ 진행 작업
→ 일반 알림
동일 Priority에서는 v36부터 occurredAt DESC로 정렬한다.
6. Release Governance
Screen Recipe의 testProfile과 canonicalScenarioIds 변경이 Release Impact에 기록된다. requiredPolicies, recoveryPolicies, securityPolicies, defaultCommands, scaffoldSurfaces 변경은 구조적 영향으로 취급한다.
7. DB / API Migration
v36 자체는 PostgreSQL schema나 backend API route 변경을 요구하지 않는다. Frontend Screen Recipe/Test/Home Navigation 계약의 강화다.
Foundation v50 — Template retryability
Templates that bind a known permanent KbxProblem should now pass errorRetryable=false rather than render a meaningless retry action. Existing callers remain backward compatible because the default is true.
WMS-WORK-001 specifically treats WMS_WORK_QUERY_NOT_CONNECTED as non-retryable. When the real production endpoint is connected, classify transient network/service failures separately and set retryability according to the returned Problem contract.
Foundation v60 — OMS 주문 상태 Canonical API 전환
OMS 주문 상세/등록/확정 응답의 status는 더 이상 한국어 display label을 반환하지 않는다.
| 이전 표시 기반 값 | v60 canonical value | 사용자 표시 |
|---|---|---|
작성 |
DRAFT |
작성 |
확정 |
CONFIRMED |
확정 |
할당 |
ALLOCATED |
할당 |
피킹 |
PICKING |
피킹 |
검수 |
CHECKED |
검수 |
출고완료 |
SHIPPED |
출고완료 |
Frontend/외부 소비자는 status === "작성" 같은 비교를 제거하고 canonical code를 사용해야 한다. 사용자 Label, 색상, Filter 표시명은 kbxStatusCatalog에서 해석한다.
신규 주문의 저장 전 NEW는 FE-local 상태이며 DB에 저장하지 않는다. 첫 저장 성공 응답은 DRAFT다.
주문 조회의 shipmentStatus는 별도 Projection 상태 계약이며 NEW / READY / CONFIRMED / HOLD / SHIPPED / ERROR를 사용한다. Aggregate lifecycle status와 의미를 혼합하지 않는다.
이 변경은 API 응답의 의미계약을 바로잡는 breaking change이므로 v60은 major change로 선언한다.