Add dcy-003 (confirmed) + REQ-011~015: broker execution + KIS + outbox
dcy-003 confirmed (all OQ answered, operator-confirmed scope/risk): - OQ-1: paper/stub + real KIS Open API adapter (validated on KIS paper server; live account go-live config-gated, deferred). - OQ-2: unified async fill (submit -> poll); paper is a deterministic async double (no synchronous shortcut) for faithful path coverage. - OQ-3: option A — pending slot is the execution queue, broker_order_id is the idempotency guard; no separate outbox table (option B as a growth hook; intent_log stays dedup-only). - OQ-4: dedicated background execution loop (claim -> submit -> poll -> reconcile); intent API only transitions to pending. Decompose into REQ-011~015 (all Proposed): BrokerPort + paper double, KIS adapter, execution loop, durability+reconciliation (Exception), baseline alignment. NFR-1/2/3 absorbed. Update SRS index + dcy-003 created-REQ refs. Safety floor, KIS live account, strategy daemons, and auth remain deferred to follow-up Discoveries. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,72 @@
|
||||
# req-012: KIS Open API 브로커 어댑터
|
||||
|
||||
- Status: Proposed
|
||||
- Type: Integration
|
||||
- Priority: High
|
||||
- Owner: project maintainers
|
||||
|
||||
## Intent
|
||||
- `BrokerPort`(REQ-011)를 구현하는 실제 KIS(한국투자증권) Open API 어댑터를 추가해, 코어가 실제 주문 송신/취소/체결 조회를 수행할 수 있게 한다. 슬라이스에서는 KIS 모의투자 서버로 검증한다.
|
||||
|
||||
## Requirement
|
||||
- KIS Open API 로 `submit_order`/`cancel_order`/`poll_fill`(체결 조회)을 구현하고, 접속 토큰 발급·갱신, 레이트리밋, 모의투자/실계좌 base URL 전환을 어댑터 내부에서 처리한다. 자격증명은 env/.env(REQ-010 패턴)로 주입한다. 실계좌 라이브 전환은 config 게이팅(기본 모의투자)으로 둔다.
|
||||
|
||||
## Acceptance Criteria
|
||||
1. Given KIS 모의투자 자격증명, When 어댑터 기동, Then 토큰을 발급/갱신하고 인증된 호출이 가능하다.
|
||||
2. Given 매수/매도 주문, When `submit_order`, Then KIS 모의투자에 주문이 접수되고 broker_order_id(주문번호)를 반환한다.
|
||||
3. Given 접수된 주문, When `poll_fill`, Then KIS 체결 조회로 체결/부분체결/거부 상태를 반환한다.
|
||||
4. Given config, When 실계좌/모의투자 전환, Then 기본은 모의투자이며 실계좌는 명시적 게이팅 없이는 활성화되지 않는다.
|
||||
5. Given 자격증명 미설정/토큰 실패, When 호출, Then 명확한 오류로 실패하고 코어 슬롯 상태를 오염시키지 않는다.
|
||||
|
||||
## Impacted Area
|
||||
- Docs: docs/interface-contract.md(브로커 경계/KIS), docs/runtime-flows.md — REQ-015
|
||||
- Modules: trex_core/adapters/broker(kis), config(KIS 자격증명/base URL/게이팅), pyproject(HTTP 의존)
|
||||
- Tests: KIS 모의투자 통합테스트(자격증명 가용 시), 토큰/오류 처리 단위테스트
|
||||
|
||||
## Notes
|
||||
- 실거래 리스크(dcy-003 R-5): 슬라이스는 모의투자만, 실계좌 라이브는 Out of Scope(게이팅).
|
||||
- KIS 모의투자 자격증명이 검증 환경에 없으면 통합테스트는 skip, 단위(토큰/오류)만 수행 — verification 에서 분리 판단.
|
||||
- 출처: dcy-003 FR-1(KIS), OQ-1.
|
||||
|
||||
## Change Log
|
||||
|
||||
### CHG-20260604-01
|
||||
- Date: 2026-06-04
|
||||
- Author: Justin Ko
|
||||
|
||||
#### Change Summary
|
||||
- dcy-003 FR-1(KIS 어댑터) 로부터 최초 생성(Proposed).
|
||||
|
||||
#### Intent
|
||||
- 실제 KIS Open API 어댑터 요구사항을 backlog 로 정규화.
|
||||
|
||||
#### Acceptance Criteria Delta
|
||||
- Added:
|
||||
- 토큰, 주문 접수, 체결 조회, 모의투자/실계좌 게이팅, 오류 처리 5개 기준
|
||||
- Updated:
|
||||
- 없음
|
||||
- Removed:
|
||||
- 없음
|
||||
|
||||
#### Impacted Area Delta
|
||||
- Docs:
|
||||
- docs/interface-contract.md, docs/runtime-flows.md
|
||||
- Modules:
|
||||
- adapters/broker(kis), config, pyproject
|
||||
- Tests:
|
||||
- KIS 모의투자 통합 + 토큰/오류 단위
|
||||
|
||||
#### Delivery Trace Delta
|
||||
- Batches:
|
||||
- none
|
||||
- Releases:
|
||||
- none
|
||||
|
||||
#### Revalidation Impact
|
||||
- Reverification Needed: no
|
||||
- Existing Implementation Invalidated: no
|
||||
- Status Recommendation: keep-current
|
||||
- Follow-up Action: confirm-req 후 batch 편성
|
||||
|
||||
#### Validation Plan
|
||||
- KIS 모의투자 통합테스트(가용 시) + 토큰/오류 단위테스트로 검증.
|
||||
Reference in New Issue
Block a user