trex-core/docs/srs/Integration/req-117_order-request-venue-field.md

req-117: OrderRequest venue additive 필드

• Status: Implemented
• Type: Integration
• Priority: High
• Owner: trex-core-dev

Intent

• KIS NXT(대체거래소) 주문 지원을 위해 OrderRequest DTO에 venue: str = "KRX" 필드를 additive 추가한다.
• 기본값 "KRX"로 미지정 시 기존 orb/tsl 경로와 wire 의미론이 byte-동일하게 유지되어 하위 호환을 보장한다.
• 포트-어댑터 경계에서 venue 의미론을 확립하고, 상위 intent→venue 전달(tvr 팬-인 batch)이 이 계층 설계를 건드리지 않아도 되도록 확장 경로를 열어 둔다.

Requirement

• trex_core/application/broker_port.py의 OrderRequest dataclass에 venue: str = "KRX" 필드를 추가한다.
• 필드는 frozen dataclass의 마지막 옵셔널 위치에 추가하여 기존 위치 인수 호출을 깨지 않는다.
• venue 값 의미론: "KRX" = 정규 KRX 거래소, "NXT" = 대체거래소(연장세션 포함), "SOR" = 최선집행(현재 비권고 — OQ-1 잔여 미확인).
• 이 필드는 포트 계층 DTO로서 venue 명시를 강제하지 않는다(기본값 "KRX" 허용). KIS 어댑터(REQ-118)가 이 값을 EXCG_ID_DVSN_CD로 변환한다.
• paper broker stub은 venue 필드를 수신하되 무시해도 무방하다(venue는 KIS-specific 개념, paper는 교환소 개념 없음). 단, OrderRequest 수신 시 venue 필드를 읽어 로깅/audit에 포함할 수 있다.

Acceptance Criteria

1. Given OrderRequest(slot_id="s1", side="buy", symbol="005930", qty=1)로 venue 미지정 시, When dataclass를 생성하면, Then req.venue == "KRX"이다.
2. Given OrderRequest(..., venue="NXT")로 NXT 지정 시, When dataclass를 생성하면, Then req.venue == "NXT"이다.
3. Given 기존 orb/tsl 코드가 OrderRequest 생성 시 venue를 지정하지 않는 경우, When 단위 테스트를 실행하면, Then 기존 테스트가 모두 통과한다(회귀 없음).
4. Given OrderRequest frozen dataclass 불변식, When venue 필드가 추가된 후에도, Then 기존 위치 인수(slot_id, side, symbol, qty) 순서가 변경되지 않고 기존 코드가 재컴파일 없이 동작한다.
5. Given paper broker stub이 submit_order(req: OrderRequest) 를 수신할 때, When req.venue가 "NXT"이든 "KRX"이든, Then paper stub은 주문을 정상 수락한다(venue 값에 무관하게 기존 동작 유지).

Impacted Area

• Docs: docs/interface-contract.md — OrderRequest DTO 스키마 섹션 venue 필드 추가 필요.
• Modules:
  • trex_core/application/broker_port.py — OrderRequest.venue 필드 추가(additive).
  • trex_core/adapters/broker/paper.py — venue 수신 허용(무시 또는 로깅), 기존 동작 유지.
  • 호출 측(execution, safety_sell 등)은 venue 미지정으로 자동 KRX 기본값 적용 — 변경 불필요.
• Tests:
  • tests/ — 기존 OrderRequest 생성 테스트 회귀 확인.
  • 신규: venue 기본값 및 NXT 지정 단위 테스트 추가.

Notes

• wire 계약 영향 없음: OrderRequest는 AMQP wire 위를 직접 흐르지 않는다. intent 메시지 계약(wire)에서 venue를 전달하는 것은 tvr 팬-인 batch(후속)의 범위이며, 본 REQ는 브로커 어댑터 계층 DTO까지만 다룬다.
• "SOR" 값은 정의만 하고 현재 KIS 운영 권고 대상 아님(OQ-1 잔여: SOR 체결거래소 식별·EXCG 미전송 기본값 미확인). SOR 동작은 REQ-118 AC에서 별도 처리하지 않는다.
• frozen dataclass 확장 시 기존 field(default_factory=...) 패턴이 없으므로 기본값 있는 단순 필드로 충분하다.
• 출처 Discovery: trex-tvr-v1 dcy-002_20260704_execution-cadence-slot-fetch.md FR-6, confirmed 2026-07-06.
• 실측 근거: 2026-07-06 실전 계좌 NXT 주문 rt_cd=0 접수·취소 rt_cd=0 확인.

Change Log

CHG-20260707-01

• Date: 2026-07-07
• Author: 팀장(Claude) — confirm-req-implemented

Change Summary

• Approved → Implemented: bat-056 구현 완료. 독립 QC opus PASS-WITH-NOTES(blocker 0) — 794 passed, 기존 주문 페이로드 불변(EXCG=KRX 추가만, 키 집합 잠금), 전 호출부 정합. PR #38 사장님 결재·머지(079fc04, 2026-07-07) = confirm-batch-verification 완료.
• 배포 게이트(NXT 라이브 사용 전): 실전 소액 스모크(KRX+NXT 각 1건)로 poll_fill 구 TR의 NXT 체결 포함 여부 실측(AC-4 OI-1 해소). 미포함 시 신 TR(TTTC0081R) 전환 별도 batch.

Delivery Trace Delta

• Batches: bat-056_20260706_kis-broker-venue (merged, PR #38)

Revalidation Impact

• Reverification Needed: no / Existing Implementation Invalidated: no
• Status Recommendation: Implemented

CHG-20260706-02

• Date: 2026-07-06
• Author: 팀장(Claude) — confirm-req

Change Summary

• Proposed → Approved: 팀장 검토·승인. dcy-002(tvr, confirmed 2026-07-06) NXT venue 트랙. 실측 근거(NXT 주문/취소 rt_cd=0, 2026-07-06) 확보 상태. 고위험(라이브 주문 경로) — worktree+PR+QC(opus) 플로.

Acceptance Criteria Delta

• Added/Updated/Removed: 없음

Revalidation Impact

• Reverification Needed: no / Existing Implementation Invalidated: no
• Status Recommendation: Approved

CHG-20260706-01

• Date: 2026-07-06
• Author: trex-core-dev

Change Summary

• REQ-117 신규 생성(Proposed). trex-tvr-v1 dcy-002 FR-6 기반 OrderRequest venue additive 필드.

Intent

• NXT 거래소구분 지원을 위한 포트 계층 DTO 확장. additive 설계로 기존 orb/tsl 무영향.

Acceptance Criteria Delta

• Added: AC-1~5 신규 작성.
• Updated: 없음.
• Removed: 없음.

Impacted Area Delta

• Docs: docs/interface-contract.md venue 필드 섹션 추가 예정.
• Modules: broker_port.py OrderRequest 확장, paper broker 수신 허용.
• Tests: 기존 회귀 + venue 기본값/NXT 신규 단위 테스트.

Delivery Trace Delta

• Batches: 미할당(suggest-batch-reqs 대기).
• Releases: 미할당.

Revalidation Impact

• Reverification Needed: no (신규 Proposed, 기존 구현 없음)
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: confirm-req 후 suggest-batch-reqs → REQ-118과 동일 batch로 묶을 것.

Validation Plan

• pytest 전체 통과(기존 회귀 없음) + venue 필드 단위 테스트 신규 통과.