feat: own current KIS daily fill contract in Core

2026-07-29 21:46:42 +09:00
parent b47d7418e8
commit 56b35b257b
12 changed files with 365 additions and 54 deletions
@@ -0,0 +1,33 @@
+# BAT-063 Design
+
+- Status: confirmed
+- Batch: BAT-063
+
+## Architecture Summary
+
+- KIS 일별 체결조회 거래 ID와 공통 파라미터는 `KISBroker`의 private helper가
+  한 번만 생성한다.
+- 실전은 `TTTC0081R`, 모의는 `VTTC0081R`을 사용한다.
+- 일반 주문번호 조회와 결과불명 주문 탐색 모두
+  `EXCG_ID_DVSN_CD=ALL`을 전달한다.
+- 체결·부분체결·취소·거부·결과불명 해석과 폴링 간격은 그대로 유지한다.
+
+## Changed Areas
+
+- Module: `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`
+
+## Key Decisions
+
+1. sidecar가 거래 ID를 바꾸지 않아도 Core 단독으로 KRX·NXT 체결을 조회한다.
+2. 거래소별 분기 대신 `ALL` 하나로 주문번호와 결과불명 후보를 찾는다.
+3. 공개 `BrokerPort.poll_fill` 시그니처는 변경하지 않는다.
+4. 구형 거래 ID fallback을 두지 않는다. 공식 명세가 구형 거래 ID 중단 가능성을
+   명시하기 때문이다.
+
+## Architecture Impact
+
+- KIS broker transport
+- 주문 상태 해석과 도메인·애플리케이션 경계에는 영향 없음
@@ -0,0 +1,39 @@
+# BAT-063 Implementation
+
+- Status: completed
+- Batch: BAT-063
+
+## Plan Summary
+
+- KIS 일별 체결조회 요청 계약을 Core의 단일 private helper로 모으고 일반 주문과
+  결과불명 주문 조회가 동일한 신형 거래 ID와 전체 거래소 조건을 사용하게 한다.
+
+## Changed Files
+
+- `trex_core/adapters/broker/kis.py`
+- `tests/adapters/broker/test_kis.py`
+- `docs/interface-contract.md`
+- `docs/runtime-flows.md`
+- `docs/srs/Integration/req-118_kis-broker-venue-parameterization.md`
+- `docs/batches/bat-063_20260729_kis-daily-fill-all/*`
+
+## Execution Log
+
+1. 날짜·종목·주문번호를 받는 `_daily_fill_request`를 추가했다.
+2. 실전 `TTTC0081R`, 모의 `VTTC0081R`, `EXCG_ID_DVSN_CD=ALL`을 한 곳에
+   고정했다.
+3. 일반 `poll_fill`과 결과불명 주문 복구가 같은 helper를 사용하도록 바꿨다.
+4. 기존 응답 파싱, 상태 판정, 공개 포트와 재시도 주기는 변경하지 않았다.
+5. 일반·결과불명·실전·모의 요청 계약을 단위검사로 고정했다.
+
+## Validation
+
+- KIS broker 집중검사: 59 passed, 1 skipped.
+- Core 전체 회귀: 922 passed, 51 skipped.
+- 변경 파일 Ruff: PASS.
+- 공용 가상 인증은 커밋 후 깨끗한 작업트리에서 1~7단계로 실행한다.
+
+## Remaining Risks
+
+- 가상 인증은 실전 KIS 응답이나 주문 가능 상태를 증명하지 않는다.
+- 이 배치는 실주문, 계정 설정, 주문 게이트, 배포를 변경하지 않는다.
@@ -0,0 +1,29 @@
+# BAT-063: KIS 전체 거래소 일별 체결조회
+
+- Status: in-progress
+- Profile: standard
+- Source Discovery: REQ-118 CHG-20260729-01
+- Source REQ: REQ-118
+- Included REQ: REQ-118 CHG-20260729-01
+- Excluded REQ: 없음
+
+## Scope
+
+### In Scope
+
+- 일반 주문과 결과불명 주문의 일별 체결조회 거래 ID를 KIS 신형 계약으로 전환
+- `EXCG_ID_DVSN_CD=ALL`을 통한 KRX·NXT 통합 체결조회
+- 요청 계약 단위검사, 전체 회귀, 가상거래소 주문 수명주기 인증
+- 인터페이스·런타임 문서 동기화
+
+### Out of Scope
+
+- 주문 제출·취소·수량·가격·전략 신호 변경
+- 실주문 생성 또는 계좌·주문 게이트 변경
+- KIS sidecar 배포와 제거
+
+## Notes
+
+- KIS 공식 예제와 저장소 내 KIS REST 명세가 신형 거래 ID와 `ALL`을 동일하게
+  요구한다.
+- Core 인증 통과 뒤 docker-local sidecar 축소를 별도 저장소에서 수행한다.
@@ -0,0 +1,34 @@
+# BAT-063 Planning
+
+- Status: confirmed
+- Batch: BAT-063
+- Profile: standard
+
+## Included REQ
+
+- REQ-118 CHG-20260729-01 (Approved): KIS 전체 거래소 일별 체결조회
+
+## Delivery Plan
+
+1. KIS 공식 거래 ID·거래소 파라미터 계약을 테스트로 고정한다.
+2. 일반 주문과 결과불명 주문 조회에 하나의 요청 생성 함수를 적용한다.
+3. 기존 체결·취소·거부·결과불명 상태 해석을 변경하지 않는다.
+4. 집중검사, 전체 회귀, 가상 주문 수명주기 1~7단계를 순서대로 검증한다.
+5. 문서와 검증 증거를 동기화하고 Draft PR로 제출한다.
+
+## Dependencies
+
+- Internal: `KISBroker.poll_fill`, `_poll_unknown_submission`
+- External: KIS `inquire-daily-ccld` 신형 요청 계약
+
+## Design Gate
+
+- Design Required Before Implementation: yes
+- Reason: 실전 주문 체결조회 경로이므로 요청 생성 책임과 불변 동작을 먼저 고정한다.
+
+## Risks
+
+- 결과불명 주문 조회만 구형 계약에 남을 수 있다.
+  - 대응: 일반·결과불명 두 경로의 거래 ID와 `ALL`을 별도 회귀검사로 고정한다.
+- 체결 상태 해석이 바뀔 수 있다.
+  - 대응: 요청 생성만 변경하고 응답 파싱 함수와 공개 포트 시그니처를 보존한다.
@@ -0,0 +1,37 @@
+# BAT-063 Verification
+
+- Status: pending
+- Batch: BAT-063
+- Verified By: delivery-runner
+
+## Acceptance Mapping
+
+| AC | 결과 | 근거 |
+| --- | --- | --- |
+| REQ-118 AC-4 일반 조회 | PASS | `test_poll_fill_uses_current_daily_fill_contract_for_all_venues` |
+| REQ-118 AC-4 결과불명 조회 | PASS | `test_unknown_submission_resolves_from_recent_daily_orders` |
+| 실전·모의 거래 ID | PASS | `test_daily_fill_request_uses_current_live_and_mock_contract` |
+| 기존 주문·취소·상태 해석 | PASS | KIS broker 집중검사와 Core 전체 회귀 |
+| 가상 주문 수명주기 | PENDING | 공용 인증 1~7단계 실행 전 |
+
+## Evidence
+
+- Test:
+  - KIS broker 집중검사: 59 passed, 1 skipped.
+  - Core 전체: 922 passed, 51 skipped.
+  - 변경 파일 Ruff: PASS.
+- Certification:
+  - 공용 인증 산출물 경로는 실행 후 기록한다.
+
+## Result
+
+- Ready for Release: false
+- Blocking Issues:
+  - 깨끗한 커밋 기준 공용 가상 인증 1~7단계가 아직 실행 전이다.
+
+## Safety Classification
+
+- `research_only=true`
+- `official_comparable=false`
+- `real_order_allowed=false`
+- `order_adapter=virtual_locked_replay`
@@ -66,3 +66,4 @@
 | BAT-058 | standard | release-candidate | REQ-123 | dcy-038 | [bat-058](./bat-058_20260716_cost-basis-safe-sync-seed/) |
 | BAT-059 | standard | release-candidate | REQ-124 | dcy-039 | [bat-059](./bat-059_20260727_intent-venue-fanin/) |
 | BAT-062 | standard | release-candidate | REQ-127 | dcy-042 | [bat-062](./bat-062_20260729_shared-account-capital-allocation/) |
+| BAT-063 | standard | in-progress | REQ-118 (CHG-20260729-01) | REQ-118 change-req | [bat-063](./bat-063_20260729_kis-daily-fill-all/) |