# KBX v9 Production Readiness

## 목적

v9는 새 화면 문법을 추가하는 버전이 아니라, 기존 KBX 화면이 실제 운영에서 실패·지연·동시수정·네트워크 장애를 만났을 때 사용자에게 거짓 성공이나 불명확한 상태를 보여주지 않도록 하는 운영 UX 계층이다.

## 운영 UX 원칙

1. **정상/지연/실패/읽기전용을 숨기지 않는다.** 시스템이 불완전한 상태면 `KbxRuntimeBanner`로 알려준다.
2. **오래된 값은 최신 값처럼 보이지 않게 한다.** 중요한 Projection은 observedAt을 내려주고 `KbxFreshnessIndicator`로 표현한다.
3. **동시수정은 자동 덮어쓰지 않는다.** version conflict는 `KbxConflictResolver`로 최신 값을 다시 확인하게 한다.
4. **3초 이상 걸리는 대량 업무는 사용자를 화면에 묶어두지 않는다.** Operation Run으로 승격하고 작업센터에서 추적한다.
5. **완료·부분실패·운영주의는 Notification Center에 남긴다.** Toast만으로 장시간 작업 결과를 전달하지 않는다.
6. **예상치 못한 오류에는 Correlation ID를 제공한다.** 사용자는 기술 Stack Trace 대신 지원팀에 전달 가능한 참조번호를 본다.
7. **Mutation 자동 Retry는 Idempotency가 확보된 경우만 허용한다.** UI disable은 중복방지 수단이 아니다.

## Runtime Mode

- `normal`: 일반 운영.
- `degraded`: 일부 연계나 기능이 지연되나 핵심 업무 가능.
- `read-only`: 조회는 가능하지만 데이터 변경을 차단.
- `offline`: 서버 연결 불가. WMS에서 명시적으로 Offline 허용된 Command 외에는 성공 처리 금지.

## 장시간 작업

Excel Import, 대량 출고지시, 대량 동기화처럼 foreground 3초를 안정적으로 넘는 작업은 `kbx.operation_runs`에 등록한다.

사용자가 페이지를 닫더라도 PostgreSQL 상태가 Source of Truth이며, SignalR은 실시간 갱신 채널일 뿐이다.

## Freshness

Read Projection은 업무 중요도에 따라 `observedAt`과 `staleAfterSeconds`를 전달할 수 있다. stale 기준은 화면마다 임의 지정하지 않고 업무군 정책으로 관리한다.

권장 출발값:

- WMS 작업 상태: 5~15초
- OMS 운영 Queue: 30~60초
- 일반 ERP 조회: 1~5분
- 기준정보: 변경 빈도에 따라 더 길게 허용

이 수치는 절대 규칙이 아니라 현장 Telemetry로 조정하는 초기 기준이다.

## 운영자 진단

사용자에게 노출하는 정보:

- 화면 ID
- 발생시각
- Correlation ID
- 현재 Runtime Mode

일반 사용자에게 노출하지 않는 정보:

- Stack Trace
- SQL
- DB 연결정보
- 내부 Secret
- 고객 민감 데이터

## Source of Truth

`kbx.operation_runs`, `kbx.user_notifications`, `kbx.runtime_incidents`는 운영 Projection이다. 주문·재고·피킹과 같은 업무 진실을 이 테이블에서 변경하지 않는다.
