feat(broker): KIS venue parameterization — OrderRequest.venue + EXCG_ID_DVSN_CD (REQ-117/118, BAT-056)

- OrderRequest.venue: str = "KRX" additive 추가 (기존 위치 인수 순서 불변)
- BrokerPort.cancel_order: venue: str = "KRX" 파라미터 추가
- BrokerPort.get_current_price: market: str = "J" 파라미터 추가
- KISBroker.submit_order: EXCG_ID_DVSN_CD=req.venue 항상 명시 전송
- KISBroker.cancel_order: EXCG_ID_DVSN_CD=venue 항상 명시 전송
- KISBroker.get_current_price: FID_COND_MRKT_DIV_CODE=market 파라미터화
- PaperBroker: cancel_order/get_current_price 시그니처 정합 (venue/market 수신·무시)
- poll_fill TR 유지 (TTTC8001R) — NXT 체결 포함 여부 미확인 open item (코드 주석 기록)
- tests/adapters/broker/test_venue.py: REQ-117 AC-1~5 + REQ-118 AC-1~8 신규 17개
- docs: interface-contract.md OrderRequest/BrokerPort 섹션 + change log 추가
- docs: runtime-flows.md venue 전달 경로 명시 + change log 추가

결과: 794 passed, 47 skipped (기존 777+47 대비 신규 17개 추가 전부 통과)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01VHtM5Ws1HKCKQ4JGi6GRb5
This commit is contained in:
2026-07-06 23:24:51 +09:00
co-authored by Claude Fable 5
parent dc6d7a943b
commit ee3dc83a93
9 changed files with 638 additions and 11 deletions
@@ -0,0 +1,62 @@
# BAT-056 Planning
## Task Breakdown
### T-1: OrderRequest.venue 필드 추가 (REQ-117)
- 파일: `trex_core/application/broker_port.py`
- 작업: `OrderRequest` frozen dataclass에 `venue: str = "KRX"` 필드 추가 (마지막 위치)
- 제약: 기존 위치 인수 순서(`slot_id`, `side`, `symbol`, `qty`, `limit_price`, `order_type`) 불변
### T-2: BrokerPort.cancel_order 시그니처 venue 파라미터 추가 (REQ-118)
- 파일: `trex_core/application/broker_port.py`
- 작업: `cancel_order` 프로토콜 시그니처에 `venue: str = "KRX"` 파라미터 추가
- 설계 결정: 시그니처 파라미터 추가 방식 채택(호출자 보존 방식 대비 명시적, 기본값으로 하위 호환)
### T-3: KISBroker.submit_order EXCG 명시 전송 (REQ-118 AC-1,2)
- 파일: `trex_core/adapters/broker/kis.py`
- 작업: body에 `"EXCG_ID_DVSN_CD": req.venue` 항상 추가
### T-4: KISBroker.cancel_order venue 파라미터 + EXCG 전송 (REQ-118 AC-3,8)
- 파일: `trex_core/adapters/broker/kis.py`
- 작업: 시그니처에 `venue: str = "KRX"` 추가, body에 `"EXCG_ID_DVSN_CD": venue` 추가
### T-5: KISBroker.poll_fill TR 유지 + open item 기록 (REQ-118 AC-4)
- 파일: `trex_core/adapters/broker/kis.py`
- 작업: 구 TR(TTTC8001R/VTTC8001R) 유지, 코드 주석에 NXT 체결 포함 여부 미확인 명시
- 이유: 웹 접근 불가 환경 — KIS 개발자 센터 문서 확인 불가. 보수 원칙: 기존 TR 유지, open item으로 기록
### T-6: KISBroker.get_current_price market 파라미터 추가 (REQ-118 AC-5,6)
- 파일: `trex_core/adapters/broker/kis.py`
- 작업: 시그니처에 `market: str = "J"` 추가, `FID_COND_MRKT_DIV_CODE` → market 값 사용
### T-7: PaperBroker.cancel_order 시그니처 정합 (REQ-118 AC-8, REQ-117 AC-5)
- 파일: `trex_core/adapters/broker/paper.py`
- 작업: cancel_order 시그니처에 `venue: str = "KRX"` 추가, 내부 로직 무변경(venue 무시)
### T-8: 신규 테스트 작성 (REQ-117 AC-1~5, REQ-118 AC-1~8)
- 파일: `tests/adapters/broker/test_venue.py` (신규)
- 작업: 13개 AC 커버 테스트
### T-9: 기존 테스트 회귀 확인 (REQ-117 AC-3, REQ-118 AC-7)
- 기존 테스트가 `OrderRequest` venue 미지정 경로를 통과하는지 확인
- 기존 submit_order fixture가 EXCG 필드 추가로 인한 페이로드 변화 감지 확인
### T-10: 문서 업데이트
- `docs/interface-contract.md` — OrderRequest venue 필드 추가
- `docs/runtime-flows.md` — venue 전달 경로 명시
## Dependency Order
T-1 → T-2 → T-3, T-4, T-5, T-6 (병렬) → T-7 → T-8 → T-9 → T-10
## Risk Points
1. `cancel_order` 시그니처 변경: BrokerPort 프로토콜 + KIS + paper 3개 파일 정합 필요
2. 기존 테스트 중 `cancel_order` 호출하는 코드 — venue 파라미터 없이 호출해도 기본값 KRX로 동작해야 함
3. `get_current_price` safety-sell 호출 경로: 기본값 "J" 유지로 무영향 확인 필요
## Estimation
- 구현: T-1~T-7 → 약 1시간
- 테스트: T-8~T-9 → 약 30분
- 문서: T-10 → 약 20분