KArtSell.Aegis/docs/Design/kbx-foundation-v52-fe-operational-navigation-screen-anatomy/docs/golden-screen-t04-t05-v26.md

KBX v26 — Golden Screen T04 / T05

목적

v25에서 KbxDataGrid의 Fast Entry 생산성 계약을 만들었지만 실제 독립 T04 업무화면은 없었고, ERP-INV-001 T05는 Master/Detail 2개 Grid까지만 구현되어 있었다.

v26은 다음 두 화면을 표준 원형으로 승격한다.

• ERP-PRICE-001 — T04 Fast Grid Entry
• ERP-INV-001 — T05 Master / Detail Explorer

T04 — ERP-PRICE-001 품목 단가 일괄등록

사용자 흐름

화면 진입
  ↓
품목코드 입력 또는 F2 Lookup
  ↓
적용일 / 단가 입력
  ↓
Enter 연속 입력 또는 Excel 다중 Cell Paste
  ↓
필요 시 행 복제 / Fill Down
  ↓
Inline Validation + 첫/다음 오류 이동
  ↓
F8 저장
  ↓
Server Validation
  ↓
PostgreSQL Upsert + Audit + Outbox + Idempotency Receipt

경계

• 품목명은 입력값이 아니라 실제 Item Lookup 결과에서 채운다.
• 동일 요청 안의 (ItemId, EffectiveDate) 중복은 오류로 처리한다.
• 기존 DB 단가와 동일 Key가 있으면 서버에서 Update한다.
• 브라우저 값은 Business Truth가 아니다.
• 같은 저장 Command 재시도는 동일 Idempotency Key를 재사용한다.
• 성공 후 새 업무 입력이 시작될 때만 새 Idempotency Key를 만든다.

Persistence

erp.item_prices

• item_id
• effective_date
• unit_price
• remark
• version
• 생성/수정 Actor와 시각
• (item_id, effective_date) Unique

Audit는 before / after / effectiveDate를 기록하고, Outbox는 ErpItemPriceChanged를 동일 Transaction에서 기록한다.

T05 — ERP-INV-001 재고현황

사용자 흐름

품목 조회
  ↓
Master 품목 선택
  ├─→ 창고 / Location Detail
  ├─→ 재고이력
  └─→ 현재고/가용 Drill-down Drawer

Context 유지

재조회 전에 선택한 ItemId를 보존하고, 재조회 결과에 동일 품목이 존재하면 다시 활성화한다.

KbxDataGrid.activeRowKey는 Single Selection을 복원하고 해당 Row를 화면으로 이동시킨다. 화면이 AG Grid Column/Row API를 직접 조작하지 않는다.

Detail / History

• Detail: erp_inventory_snapshot_projection
• History: erp_inventory_ledger_projection

History 기본 순서:

occurred_at DESC

재고 숫자 Drill-down은 새로운 전체 Page를 열지 않고 Drawer에서 현재고·할당·보류·가용의 산정 근거를 설명한다. 실제 확정·변경 시 서버 재고 정책이 다시 검증된다.

Template 고도화

KbxMasterDetailPage 1.2.0

기존 임의 masterWidth보다 다음 Split Preset을 사용한다.

sm
md
lg

또한 다음 영역을 Template Contract로 고정했다.

• master header
• detail header
• bottom/history header
• current context strip

KbxDataGrid 1.4.0

추가:

activeRowKey

목적은 Master/Detail에서 선택 상태를 화면 코드가 AG Grid API로 직접 복원하지 않도록 하는 것이다.

Authorization normalization

Item Lookup 3개 API의 Permission을 oms.order.read에서 erp.item.read로 변경했다.

이는 ERP T04가 OMS 주문 권한에 의존하는 잘못된 경계를 만들지 않기 위한 의도된 breaking change다. 상세 migration은 docs/release/migration-guide.md를 따른다.

테스트

Canonical Golden Screen 범위를 7개에서 9개로 확대했다.

추가:

• scenario.erp.item-price.fast-entry
• scenario.erp.inventory.master-detail-context

Synthetic fixture와 Idempotency Key도 계약에 포함한다.