# 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 필드 단위 테스트 신규 통과.