# KBX v36 Migration Guide

## 1. Screen Recipe `testProfile` 추가

`contracts/screens/kbx.screen-recipes.json`의 모든 T01~T09 Recipe는 다음을 가져야 한다.

```ts
interface KbxScreenRecipeTestProfile {
  requiredScenarioKinds: ('e2e'|'integration'|'contract')[]
  requiredTags: string[]
  requiredEvidence: string[]
  requiredChecks: string[]
}
```

Custom Recipe를 별도로 관리하는 소비자는 동일한 검증 정보를 추가해야 한다.

## 2. 새 Verification Manifest

생성 산출물이 하나 추가된다.

```text
generated/screen-recipe-verification-manifest.json
```

직접 수정하지 않는다.

```bash
node scripts/generate-screen-recipe-contracts.mjs
```

또는 `node scripts/validate-kbx.mjs`를 실행한다.

## 3. Scaffolder 생성 파일 추가

`kbx:new-screen`은 기존 Definition/Page/Route/README 외에:

```text
*.test-plan.ts
```

를 생성한다.

이 파일에는 Recipe의 Canonical Scenario, Required Check, Required Evidence가 들어간다. 삭제하지 말고 실제 Screen-specific Vitest/Playwright로 확장한다.

기존 보안 요구는 그대로다.

```text
master
transaction
fast-entry
```

은 계속 명시적인 `--write-permission`이 필요하다.

## 4. Home Attention API

신규 권장 API:

```ts
buildKbxHomeAttentionQueue(...)
```

반환:

```ts
{
  items,
  totalCount,
  overflowCount,
  sourceCounts,
}
```

기존:

```ts
buildKbxHomeAttention(...)
```

은 호환을 위해 유지되며 `items`만 반환한다.

`KbxHomeAttentionItem`에는 `occurredAt`이 필수다. 직접 Item을 생성하는 외부 코드가 있다면 발생 시각을 넣어야 한다.

## 5. Home 정렬 변경

업무 Priority 자체는 변경하지 않는다.

```text
미저장
→ 실패/부분완료
→ 중요 알림
→ 진행 작업
→ 일반 알림
```

동일 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로 선언한다.
