feat: own current KIS daily fill contract in Core

docs/srs/Integration/req-118_kis-broker-venue-parameterization.md

@@ -1,6 +1,6 @@
 # req-118: KIS 브로커 어댑터 venue 파라미터화 (EXCG_ID_DVSN_CD)
 
-- Status: Implemented
+- Status: Approved
 - Type: Integration
 - Priority: High
 - Owner: trex-core-dev
@@ -9,7 +9,8 @@
 
 - KIS 브로커 어댑터(`adapters/broker/kis.py`)에서 주문 거래소구분(`EXCG_ID_DVSN_CD`)을 `OrderRequest.venue`로부터 파라미터화하여 NXT(대체거래소) 주문·취소를 지원한다.
 - 동시에 `submit_order`에서 기존 EXCG 미전송 관행을 `"KRX"` 명시 전송으로 변경하여 서버 기본값 의존을 제거한다(동작 고정, 실측상 서버 기본값=KRX로 동일하나 명시화가 더 견고함).
-- `poll_fill`의 구 TR(`TTTC8001R`) NXT 체결 포함 여부를 확인하고, 미포함 시 신 TR(`TTTC0081R`, EXCG=ALL)으로 전환하여 NXT 체결 조회를 보장한다.
+- `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 설계다.
 
@@ -17,7 +18,9 @@
 
 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`: NXT 체결 조회를 보장한다. 구 TR `TTTC8001R`의 NXT 체결 포함 여부를 구현 시점에 확인(AC-4의 확인 방법 참조)하고, 미포함이 확인되면 신 TR `TTTC0081R`(EXCG 파라미터 `ALL` 또는 venue 지정)으로 전환한다. 확인 불가 시 Notes의 fallback 방침을 따른다.
+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"` 필드 추가만 다르며, 주문 수락 동작이 동일함을 회귀 테스트로 확인한다.
 
@@ -26,7 +29,9 @@
 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 `poll_fill` 구현 시, When 구 TR(`TTTC8001R`)의 NXT 체결 포함 여부를 확인하는 과정(KIS 개발자 센터 문서 조회 또는 NXT 체결 건 직접 조회 실측)을 수행하면, Then 그 결과를 구현 문서(batch design 또는 코드 주석)에 명시하고, 미포함이 확인된 경우 신 TR `TTTC0081R`으로 전환한다.
+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 검사로 확인한다.
@@ -49,8 +54,13 @@
 
 - **고위험 경로**: `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 전환 판단**: 구 TR(`TTTC8001R`) NXT 체결 포함 여부가 구현 시점에 확인 불가능하면, 신 TR(`TTTC0081R`)으로 즉시 전환하는 것을 기본 방침으로 한다(보수적 접근). 신 TR로 전환 시 모의(VTS) 지원 여부가 미확인이므로, mock 모드에서의 fallback(구 TR 유지)을 설계에 포함한다.
-- **모의(VTS) NXT 미확인**: VTS(모의투자)에서 NXT EXCG_ID_DVSN_CD 동작이 확인되지 않았다. 검증은 단위 테스트(HTTP 목킹) + 실전 소액 스모크(운영 협의)로 진행한다. 모의 환경 검증은 선행 조건이 아니며, 배포 전 운영팀과 스모크 계획을 협의한다.
+- **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.
@@ -59,6 +69,51 @@
 
 ## 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

docs/srs/index.md

@@ -198,7 +198,7 @@
 | REQ-115 | 그날-시작 장중 무중단 보장 — 그날 고정 인증정보 캐시 + portfolio-hub 장애 비중단 | Non-Functional | Approved | High | trex-core-dev | [req-115](./Non-Functional/req-115_daystart-intraday-resilience-credential-cache.md) |
 | REQ-116 | `trex.slots.req` 전략 필드 노출 + `strategy` 요청 필터 (additive) | Interface | Implemented | High | trex-core-dev | [req-116](./Interface/req-116_slots-req-strategy-field-and-filter.md) |
 | REQ-117 | OrderRequest venue additive 필드 (KRX/NXT 거래소구분 포트 DTO) | Integration | Implemented | High | trex-core-dev | [req-117](./Integration/req-117_order-request-venue-field.md) |
-| REQ-118 | KIS 브로커 어댑터 venue 파라미터화 — EXCG_ID_DVSN_CD 전송 + NXT 지원 | Integration | Implemented | High | trex-core-dev | [req-118](./Integration/req-118_kis-broker-venue-parameterization.md) |
+| REQ-118 | KIS 브로커 어댑터 venue 파라미터화 — EXCG_ID_DVSN_CD 전송 + NXT 지원 | Integration | Approved | High | trex-core-dev | [req-118](./Integration/req-118_kis-broker-venue-parameterization.md) |
 | REQ-119 | fetched credential 공통 broker provider와 operator CLI truth 정합 | Integration | Implemented | High | trex-core-dev | [req-119](./Integration/req-119_fetched-credential-broker-provider-cli-parity.md) |
 | REQ-120 | KIS balance 인증 실패 fail-loud 및 broker/token lifecycle 정책 | Exception | Implemented | High | trex-core-dev | [req-120](./Exception/req-120_kis-balance-auth-failure-fail-loud-lifecycle-policy.md) |
 | REQ-121 | managed non-holding divergence 분류와 slot 존재 조회 계약 | Data | Implemented | High | trex-core-dev | [req-121](./Data/req-121_managed-non-holding-divergence-classification-query.md) |
@@ -216,6 +216,10 @@
 - 2026-07-16 :: REQ-123 **신규 생성(Proposed, draft-req, dcy-038)**: portfolio-hub canonical `cost_basis_per_unit` consumer parse, legacy alias precedence, WAC unavailable fail-closed sync/no-write, dry-run diagnostics, response-contract/regression tests, observability 및 rollback/release gate. portfolio-hub API/schema/auth·token/config·DB migration/direct edit·live sync·배포 제외.
 - 2026-07-15 :: REQ-119~122 **`Approved` → `Implemented`** (`confirm-req-implemented`, dcy-037/BAT-057): PR #42 merged to `main` (94e1489). Independent QC PASS-WITH-NOTES (acceptance blocker 0); 806 passed/47 skipped/1 deselected. `sync --live`, deployment, and production remediation remain separate release-approval work.
 - 2026-07-14 :: REQ-119~122 **승인(Approved, confirm-req, dcy-037)**: lead 검토로 각 REQ의 owner·priority·scope·검증 가능 AC와 Notes의 non-blocking 설계 제약을 확인했다. #39/#40/#41은 다음 `suggest-batch-reqs`에서 단일 emergency batch 후보이며, `sync --live`는 여전히 별도 release approval gate다.
+- 2026-07-29 :: REQ-118 CHG-20260729-01 **Implemented → Approved**:
+  KIS 공식 신형 일별주문체결조회(`TTTC0081R`/`VTTC0081R`,
+  `EXCG_ID_DVSN_CD=ALL`)를 일반·결과불명 `poll_fill`에 적용하고 BAT-063
+  검증 후 Implemented로 복귀한다.
 - 2026-07-06 :: REQ-117/118 **신규 생성(Implemented, draft-req, trex-tvr-v1 dcy-002 FR-6)**: KIS 브로커 venue 파라미터화 — REQ-117 OrderRequest.venue additive 필드(기본 KRX, 포트 DTO 계층), REQ-118 KIS 어댑터 EXCG_ID_DVSN_CD 전송 + cancel venue 의미론 + poll_fill NXT 체결 보장 + get_current_price market 파라미터화. 실측 근거: 2026-07-06 실전 NXT 주문/취소 rt_cd=0. 고위험(라이브 주문 경로) — worktree+PR+QC(opus) 필수. confirm-req 대기.
 - 2026-06-28 :: REQ-112/114 **`Approved` → `Implemented`**, REQ-113/115 **`Approved` 유지(confirm-req-implemented, dcy-036/BAT-053)**: BAT-053 PR #34 머지(01655ab). QC PASS-WITH-NOTES(opus, blocker 0). 745 passed/0 회귀. REQ-112(fetch 포트+어댑터+stub AC-1~8 완료), REQ-114(fail-closed 게이트 AC-1~9, BuyIntent 차단/SellIntent 통과 비대칭·CRITICAL 알람·opt-in off 비활성 완료). REQ-113/115 스캐폴드 완료 — KISBroker 런타임 재조립(REQ-113 AC-2, REQ-115 AC-1) M3 후속 batch 연기.
 - 2026-06-28 :: REQ-112~115 **`Proposed` → `Approved`(confirm-req 팀장 승인)**: dcy-036 FR/NFR 추적·AC testable·blocker 0. 진입 fail-closed/청산·DISPATCHED 통과 비대칭(REQ-114 AC-4/5), 그날 고정 캐시·ledger 무손실(REQ-115), TradingContext 원자 read(REQ-112), opt-in 회귀차단(REQ-113 AC-1). OQ-4(trex-notifier) Deferred. 선행 의존 portfolio-hub dcy-010(머지완료). 다음=suggest-batch-reqs.