trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
56b35b257b2228d286c459df9c3f9e8baaa0d7b8
trex-core/docs/srs/Integration/req-118_kis-broker-venue-parameterization.md
T

11 KiB
Raw Blame History

req-118: KIS 브로커 어댑터 venue 파라미터화 (EXCG_ID_DVSN_CD)

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

Intent

  • KIS 브로커 어댑터(adapters/broker/kis.py)에서 주문 거래소구분(EXCG_ID_DVSN_CD)을 OrderRequest.venue로부터 파라미터화하여 NXT(대체거래소) 주문·취소를 지원한다.
  • 동시에 submit_order에서 기존 EXCG 미전송 관행을 "KRX" 명시 전송으로 변경하여 서버 기본값 의존을 제거한다(동작 고정, 실측상 서버 기본값=KRX로 동일하나 명시화가 더 견고함).
  • poll_fill은 신 TR(TTTC0081R/VTTC0081R)과 EXCG_ID_DVSN_CD=ALL을 사용하여 KRX·NXT 체결 조회를 보장한다.
  • get_current_price의 시장구분(FID_COND_MRKT_DIV_CODE) "J" 하드코딩을 파라미터로 전환한다(기본 "J", "UN" 옵션).
  • 이 모든 변경은 venue 미지정(기본 KRX) 경로에서 orb/tsl 기존 동작과 byte-동일하게 유지되는 additive 설계다.

Requirement

  1. submit_order: body에 "EXCG_ID_DVSN_CD": req.venue 항상 명시 전송한다. req.venue 기본값은 "KRX"이므로 venue 미지정 호출에서도 EXCG_ID_DVSN_CD=KRX가 전송된다.
  2. cancel_order: 취소 요청 body에 "EXCG_ID_DVSN_CD": <원주문 venue> 를 전송한다. 원주문 venue는 cancel_order 시그니처에 venue: str = "KRX" 파라미터를 추가하거나, 호출자가 원주문 venue를 보존·전달하는 방식으로 구현한다(설계 방식은 구현 batch에 위임 — 의미론 확정: 취소는 원주문 venue와 동일한 EXCG를 사용해야 한다).
  3. poll_fill: 일반 주문과 결과불명 주문 조회 모두 실전 TTTC0081R, 모의 VTTC0081R을 사용하고 EXCG_ID_DVSN_CD=ALL을 전달하여 KRX·NXT 체결을 하나의 조회로 확인한다.
  4. get_current_price: 시그니처에 market: str = "J" 파라미터를 추가하고, FID_COND_MRKT_DIV_CODE를 해당 값으로 전달한다. 기본 "J" 유지로 기존 safety-sell 경로 무영향. 호출자가 "UN" 지정 가능.
  5. orb/tsl 무영향: venue 미지정 경로에서 submit_order 페이로드는 기존 대비 EXCG_ID_DVSN_CD="KRX" 필드 추가만 다르며, 주문 수락 동작이 동일함을 회귀 테스트로 확인한다.

Acceptance Criteria

  1. Given OrderRequest(..., venue="KRX")(또는 venue 미지정 기본값)로 submit_order 호출 시, When KIS HTTP 요청이 생성되면, Then 요청 body에 "EXCG_ID_DVSN_CD": "KRX"가 포함된다.
  2. Given OrderRequest(..., venue="NXT")로 submit_order 호출 시, When KIS HTTP 요청이 생성되면, Then 요청 body에 "EXCG_ID_DVSN_CD": "NXT"가 포함된다.
  3. Given NXT 주문의 broker_order_id와 venue="NXT"로 cancel_order 호출 시, When KIS HTTP 요청이 생성되면, Then 요청 body에 "EXCG_ID_DVSN_CD": "NXT"가 포함된다.
  4. Given 일반 주문번호 또는 결과불명 주문 메타데이터를 조회할 때, When inquire-daily-ccld 요청을 생성하면, Then 실전은 TTTC0081R, 모의는 VTTC0081R을 사용하고 EXCG_ID_DVSN_CD=ALL을 전달한다.
  5. Given get_current_price(symbol, market="J") 기본 호출(또는 market 미지정) 시, When KIS HTTP 요청이 생성되면, Then FID_COND_MRKT_DIV_CODE=J가 전달된다(기존 동작 동일).
  6. Given get_current_price(symbol, market="UN") 호출 시, When KIS HTTP 요청이 생성되면, Then FID_COND_MRKT_DIV_CODE=UN이 전달된다.
  7. Given 기존 orb/tsl가 venue 미지정으로 submit_order를 호출하는 경로, When 단위 테스트를 실행하면, Then 기존 submit_order 관련 테스트 전체가 통과한다(회귀 없음). 페이로드 차이는 EXCG_ID_DVSN_CD="KRX" 추가뿐임을 fixture 검사로 확인한다.
  8. Given paper broker stub이 cancel_order 시그니처 변경(venue 파라미터 추가)을 반영한 후, When paper broker로 cancel_order 호출 시, Then 기존 취소 동작이 유지된다.

Impacted Area

  • Docs:
    • docs/interface-contract.md — KIS 브로커 어댑터 EXCG 전송 명세 추가.
    • docs/runtime-flows.md — 주문 집행 흐름 중 venue 전달 경로 명시.
  • Modules:
    • trex_core/adapters/broker/kis.py — submit_order, cancel_order, poll_fill, get_current_price 변경.
    • trex_core/application/broker_port.py — BrokerPort.cancel_order 시그니처 venue 파라미터 추가(또는 호출자 보존 방식에 따라 설계 batch에서 결정).
    • trex_core/adapters/broker/paper.py — cancel_order 시그니처 정합 유지.
  • Tests:
    • tests/adapters/broker/ — submit_order EXCG 필드 포함 fixture, cancel_order venue 전달 검증, get_current_price market 파라미터 검증.
    • tests/ — 전체 회귀(기존 venue 미지정 경로 pass 확인).

Notes

  • 고위험 경로: submit_order·cancel_order·poll_fill은 라이브 주문 직결 경로다. worktree+PR+QC(opus) 플로 필수.
  • cancel_order 설계 위임: 취소 시 venue 전달 방식(cancel_order 시그니처 추가 vs. execution context 보존)은 구현 batch design에서 확정한다. 본 REQ는 의미론만 확정한다 — "취소 요청은 원주문 venue와 동일한 EXCG_ID_DVSN_CD를 사용해야 한다."
  • poll_fill TR 계약: KIS 공식 주식일별주문체결조회[v1_국내주식-005] 기준 3개월 이내 실전은 TTTC0081R, 모의는 VTTC0081R이며 거래소 구분 ALL은 전체 거래소 조회다. 구형 TTTC8001R/VTTC8001R은 사전고지 없이 중단될 수 있으므로 사용하지 않는다.
  • 모의(VTS) 범위: 모의투자는 KRX만 제공되지만 동일 신형 VTTC0081R 요청 형식과 ALL 파라미터를 유지해 실전·가상 계약을 분기시키지 않는다.
  • 토큰 캐시: 실측(2026-07-06)에서 토큰 재요청 1분 rate-limit 확인. 현행 kis.py 토큰 캐시 방식과 정합 — 신 TR 전환 시에도 토큰 캐시 재사용 경로를 유지해야 한다.
  • SOR: "SOR" 값 전달은 설계 경로에서 차단하지 않되, 현재 권고하지 않는다(체결거래소 식별·정정취소 EXCG 일치 보장이 미확인).
  • 출처 Discovery: trex-tvr-v1 dcy-002_20260704_execution-cadence-slot-fetch.md FR-6, confirmed 2026-07-06.
  • 실측 근거: 2026-07-06 실전 계좌 NXT 주문(TTTC0012U + EXCG=NXT) rt_cd=0, 취소(TTTC0013U + EXCG=NXT) rt_cd=0·잔여 0건 확인.
  • 선행 REQ: REQ-117(OrderRequest.venue 필드) 구현 완료 후 본 REQ 구현 가능.

Change Log

CHG-20260729-01

  • Date: 2026-07-29
  • Author: Codex — 형님 승인 남은 작업 진행하자

Change Summary

  • KIS 공식 신형 일별주문체결조회 계약을 Core가 직접 소유하도록 TTTC0081R/VTTC0081R과 EXCG_ID_DVSN_CD=ALL을 poll_fill 및 결과불명 주문 조회에 적용한다.

Intent

  • NXT 체결 조회를 Docker sidecar의 거래 ID 변환에 의존하지 않고 Core KIS transport에서 완결해 주문·체결·취소 거래시장 정본을 Core 하나로 단일화한다.

Acceptance Criteria Delta

  • Updated: AC-4를 공식 명세 확인 단계에서 신형 거래 ID와 전체 거래소 조회를 직접 검증하는 실행 기준으로 변경한다.
  • Added: 일반 주문과 결과불명 주문 조회가 같은 신형 계약을 사용하는 회귀검사.
  • Removed: 구형 거래 ID 유지와 sidecar 변환 의존.

Impacted Area Delta

  • Modules: trex_core/adapters/broker/kis.py
  • Tests: tests/adapters/broker/test_kis.py, tests/adapters/broker/test_venue.py
  • Docs: docs/interface-contract.md, docs/runtime-flows.md, docs/batches/bat-063_20260729_kis-daily-fill-all/

Delivery Trace Delta

  • Batches: BAT-063 신규
  • Releases: 미할당

Revalidation Impact

  • Reverification Needed: yes
  • Existing Implementation Invalidated: yes — 구형 거래 ID와 NXT 포함 여부 미확인 상태는 최신 KIS 공식 계약 및 sidecar 제거 목표와 맞지 않는다.
  • Status Recommendation: Implemented → Approved, BAT-063 검증 후 Implemented 복귀

Validation Plan

  • 일반·결과불명 poll_fill 요청이 실전 TTTC0081R, 모의 VTTC0081R, EXCG_ID_DVSN_CD=ALL을 사용하는 단위검사를 통과한다.
  • 기존 KRX/NXT 주문·취소·결과불명·재시작 회귀와 Core 전체 테스트를 통과한다.
  • 가상거래소 logic부터 ledger_reconcile까지 1~7단계 인증을 통과한다.
  • FROZEN 영향: 저장소 내 FROZEN 목록이 없으며 공개 포트 시그니처는 변경하지 않는다.
  • BT 영향: 전략 신호·가격·수량·자본 정책은 변경하지 않으므로 수익률 BT 대상이 아니다. 주문 수명주기 가상 인증으로 회귀를 검증한다.

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-118 신규 생성(Proposed). trex-tvr-v1 dcy-002 FR-6 기반 KIS 브로커 어댑터 venue 파라미터화.

Intent

  • NXT 거래소구분 지원을 위한 KIS 어댑터 EXCG_ID_DVSN_CD 전송 구현. 기존 orb/tsl 하위 호환 유지.

Acceptance Criteria Delta

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

Impacted Area Delta

  • Docs: interface-contract.md, runtime-flows.md venue 경로 명세 추가 예정.
  • Modules: kis.py 4개 메서드 변경, broker_port.py cancel_order 시그니처 정합, paper.py 정합.
  • Tests: 신규 EXCG 필드 검증 + 전체 회귀.

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: REQ-117과 동일 batch 묶기 권고. QC opus 지정(고위험 주문 경로).

Validation Plan

  • pytest 전체 통과(기존 회귀 없음) + 신규 AC-1~8 단위 테스트 통과.
  • 배포 전 실전 소액 스모크(KRX + NXT 각 1건) 운영 협의.
Reference in New Issue View Git Blame Copy Permalink