# KBX v36 — Screen Recipe Verification · Generated Test Plan · Home Attention Hardening

## 1. 배경

v35에서 T01~T09는 `type + templateCode + Screen Recipe`로 명시적 결합되었고, Scaffolder도 실제 KBX Component 조합과 명시적 쓰기 권한을 생성하게 되었다. 남은 문제는 Recipe가 Canonical Scenario ID만 참조할 뿐, **그 Scenario들이 정말 해당 화면유형의 핵심 위험을 커버하는지 자동 증명하지 못한다는 점**이었다.

또한 Home Attention은 업무 우선순위는 명확했지만 동일 우선순위 내 정렬이 key 기반이어서 사용자가 방금 발생한 실패보다 오래된 항목을 먼저 볼 수 있었고, 표시 상한 때문에 실제 전체 확인 필요 건수와 화면에 보이는 건수가 혼동될 여지가 있었다.

## 2. T01~T09 Test Profile

각 Recipe는 이제 다음을 명시한다.

```text
requiredScenarioKinds
requiredTags
requiredEvidence
requiredChecks
```

예를 들어 T03 Transaction은 Keyboard/Lookup/Conflict/Workflow를, T08 Import는 Excel/Mapping/Staging/Partial Success/Job을, T09 WMS Mobile은 Scanner/Idempotency/Network/Retry Policy를 Canonical 검증 범위로 요구한다.

이는 Domain Rule을 UI Metadata로 끌어올리는 것이 아니다. **표준 화면 유형이 반드시 검증해야 할 UX/Recovery/Security 계약**만 Recipe에서 고정한다.

## 3. Recipe Verification Manifest

`generate-screen-recipe-contracts.mjs`는 Screen Recipe와 Test Scenario Contract를 함께 읽어 다음을 생성한다.

```text
generated/screen-recipe-manifest.json
generated/screen-recipe-verification-manifest.json
packages/kbx-contracts/src/generated/screenRecipeCatalog.ts
```

Verification Manifest는 Recipe별로 다음을 계산한다.

```text
실제 Scenario Kind
실제 Tag
실제 Evidence
누락 Scenario Kind
누락 Tag
누락 Evidence
complete
```

v36 기준 T01~T09 모두 `complete=true`다.

## 4. Representative E2E Closure

단순히 아무 E2E Scenario가 연결되었다고 통과시키지 않는다.

각 T01~T09 Recipe는 최소 하나의 Canonical E2E Scenario가:

```text
Scenario.screenId
  ↓
ScreenDefinition.templateCode
  ↓
Recipe.code
```

와 실제로 일치해야 한다.

따라서 T04 Recipe를 T03 주문등록 Scenario만으로 채우는 식의 잘못된 검증 우회를 차단한다.

v36에서 부족했던 영역을 다음과 같이 보강했다.

- T02: `scenario.erp.item-master.keyboard-recovery`
- T06: `scenario.common.operations.queue-recovery`
- T07: `scenario.common.reconcile.mismatch-recovery`

## 5. Secure Scaffolder Test Plan

신규 화면 생성 시 기존 파일 외에 다음이 추가된다.

```text
{screen}.test-plan.ts
```

내용은 Recipe에서 직접 생성한다.

```text
screenId
templateCode
canonicalScenarioIds
requiredChecks
requiredEvidence
```

개발자는 이를 삭제하거나 임의로 축소하는 대신 Screen별 실제 Playwright/Vitest 증적을 추가한다.

Master / Transaction / Fast Entry의 `--write-permission` 명시 요구는 그대로 유지한다. Test Plan 강화가 보안 Fail-Closed 정책을 약화하지 않는다.

## 6. Home Attention Queue

업무 우선순위는 유지한다.

```text
1. 미저장 업무
2. 실패 / 부분완료 Job
3. 중요 Warning / Error 알림
4. 진행 / 대기 Job
5. 일반 미확인 알림
```

v36에서는 동일 우선순위 안에서:

```text
occurredAt DESC
```

로 정렬한다.

Dirty Tab은 `lastActivatedAt`, Job은 `completedAt → startedAt → requestedAt`, Notification은 `createdAt`을 사용한다.

따라서 사용자가 가장 최근에 발생한 문제부터 처리할 수 있다.

## 7. Exact Count / Overflow

새 `buildKbxHomeAttentionQueue()`는 다음을 반환한다.

```text
items
totalCount
overflowCount
sourceCounts
```

Home에서 상위 8건만 표시하더라도 실제 허용된 확인 필요 업무가 14건이면:

```text
전체 14개 · 상위 8개 표시
```

로 표현한다.

`buildKbxHomeAttention()`은 기존 호출자를 위해 item-only 호환 API로 유지한다.

## 8. 보안 경계

v31~v35의 Navigation hardening은 그대로 유지한다.

- 현재 권한으로 Runtime operation/notification 재필터링
- persisted recent route query/hash 제거
- encoded slash/backslash/control/encoded `..` 차단
- URL 길이 제한
- Notification route 재검증
- `screenRoutePatterns` capability allowlist
- 잘못된 Workspace route 제거/복구

Home Queue가 route를 신뢰하거나 권한을 새로 결정하지 않는다. 최종 Navigation은 App Shell에서 다시 검증한다.

## 9. Release Governance

Release Analyzer가 Screen Recipe의 다음 변경을 추적한다.

```text
type
templateComponent
defaultCommands
requiredPolicies
recoveryPolicies
securityPolicies
scaffoldSurfaces
canonicalScenarioIds
testProfile
```

특히 Recipe Security/Process 구조 변경은 Major 위험으로 보고, Test Profile/Canonical Scenario 변경도 Test Coverage Risk로 기록한다.

## 10. 결과

v36의 핵심은 Component 수 증가가 아니다.

```text
Template 선택
  ↓
Recipe 선택
  ↓
보안/복구/업무 UX 계약
  ↓
Canonical Scenario Coverage
  ↓
Generated Screen Test Plan
  ↓
Screen-specific Playwright/Vitest Evidence
```

까지 한 흐름으로 만든 것이다.
