KArtSell.Aegis/docs/Design/kbx-foundation-v60-status-canonical-contract-hardening/docs/operations-exception-center-v6.md

KBX v6 — Work Queue / Exception Center

목적

정상 건을 사람이 반복 확인하는 Dashboard를 만들지 않는다. OMS/WMS/ERP에서 사람이 판단하거나 복구해야 할 예외만 kbx.work_items 운영 Projection에 모은다.

Source of Truth

kbx.work_items는 업무 원장이 아니다. 주문은 OMS, 피킹은 WMS, 재고는 ERP/WMS의 소유 모델이 진실이다. 원천 모듈의 이벤트 Consumer가 OperationsProjectionWriter.UpsertAsync() 또는 ResolveBySourceAsync()를 호출한다.

기본 예외 분류

모듈	예시 코드	의미	기본 후속 행동
OMS	STOCK_SHORTAGE	주문 할당 재고 부족	주문/재고 근거 보기
OMS	ADDRESS_INVALID	배송주소 검증 필요	주문 배송정보 수정
OMS	SKU_UNMAPPED	외부 SKU와 내부 품목 연결 실패	Mapping 업무 이동
OMS	LABEL_FAILED	송장/라벨 연계 실패	등록된 Retry Handler
WMS	PICKING_SHORTAGE	실물 피킹 수량 부족	피킹 예외 화면 이동
WMS	LOCATION_MISMATCH	위치/재고 근거 불일치	실사/로케이션 확인
ERP/WMS	INVENTORY_MISMATCH	재고 Projection 불일치	Reconcile 근거 확인
COMMON	RECONCILE_MISMATCH	시스템 대사 불일치	대사 화면 이동

중요도

• critical: 출고/입고/주문 흐름을 멈추거나 SLA 초과 가능성이 높은 예외
• warning: 사람 확인이 필요하지만 즉시 전체 흐름을 중단하지 않는 예외
• info: 업무 담당자 확인/정리 대상

색상만으로 중요도를 표현하지 않는다. 중요도 텍스트와 정렬 우선순위를 함께 사용한다.

상태

open → claimed → resolved

ignored는 관리자 정책성 예외에만 제한적으로 사용한다. Domain 예외를 단순 숨김하기 위한 상태로 사용하지 않는다.

해결 원칙

1. 원천 Domain 오류는 원 업무 화면에서 해결한다.
2. 원천 정상화 이벤트가 work item을 자동 resolve한다.
3. allow_manual_resolution=true인 운영성 항목만 Exception Center에서 수동 해결한다.
4. Retry는 retry_action_key에 등록된 IWorkItemActionHandler만 실행한다.
5. 오류문구나 AI 자연어를 해석하여 임의 API를 호출하지 않는다.

UX

기본 정렬은 critical → warning → info, 이후 SLA/발생시각 순이다. 행을 더블클릭하면 Drawer가 열리고 Queue는 유지한다. 사용자는 원 주문번호와 원인을 잃지 않는다.

현장 운영

운영회의에서 Chart를 보는 것보다 critical 3건, 15분 초과 12건, 미지정 8건을 바로 담당자에게 할당하는 것이 우선이다. Exception Center는 모니터링 화면이 아니라 작업 Queue다.