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,232 @@
|
||||
# 0. 문서 상태
|
||||
이 문서의 현재 상태와 식별 정보를 기록한다. 문서 추적과 승인 흐름에 필요한 최소 메타데이터를 적는다.
|
||||
|
||||
- 상태: confirmed
|
||||
- 문서 ID: dcy-003_20260604_broker-execution-and-outbox
|
||||
- 이슈명: 브로커 단일 세션 + 주문 집행 + durable outbox (intent→실제 주문, 불변식 B)
|
||||
- 작성 시각(KST): 2026-06-04
|
||||
- 마지막 갱신 시각(KST): 2026-06-04 (draft-req)
|
||||
- 대체됨: 없음
|
||||
- 후속 Discovery 참조: 없음
|
||||
- 생성된 REQ 참조: REQ-011, REQ-012, REQ-013, REQ-014, REQ-015
|
||||
|
||||
# 1. 계획 상태 요약
|
||||
현재 Discovery가 어떤 배경에서 작성되고 있는지, 연계 문서가 있는지, 지금 시점의 해석이 무엇인지 짧게 요약한다.
|
||||
|
||||
- 연계 문서 현황:
|
||||
- 관련 점수 파일: 미생성
|
||||
- 관련 TODO/메모: trex-orbit `orbit-v2_plan.md`(불변식 B·Order Execution·forced_close 소비자 사전 설계), dcy-002(슬롯 코어 데몬·intent API, 브로커/outbox 를 본 Discovery 로 Deferred)
|
||||
- 해석:
|
||||
- dcy-002/BAT-002 로 코어가 intent 를 받아 슬롯을 `pending_buy`/`pending_sell` 로 전이까지는 하지만, **실제 브로커 주문이 없어 pending 슬롯이 체결로 진행되지 않는다**(거래 미완성, dcy-002 R-1).
|
||||
- 이번 Discovery 는 코어에 **단일 브로커 세션(불변식 B)** + **주문 집행/체결 처리** + **durable 주문 핸드오프(outbox 승격)**를 더해 intent 를 실제 주문으로 잇는다.
|
||||
|
||||
# 2. 요구사항 판정 결과
|
||||
이번 요청이 기존 요구사항과 비교해 신규인지, 유사한지, 중복인지 판단하고 그 근거를 남긴다.
|
||||
|
||||
- 판정: 신규
|
||||
- 근거
|
||||
- dcy-002 는 명시적으로 브로커 집행·완전 outbox 를 Out of Scope 로 두고 본 후속 Discovery 로 Deferred 했다.
|
||||
- 기존 REQ 본문 수정이 아니라 신규 능력(브로커 세션·주문 집행·체결·outbox)이라 `change-req` 가 아니라 새 Discovery 다.
|
||||
|
||||
# 3. 문제점의 요약
|
||||
문제의 현재 상태, 기대 상태, 관련 이해관계자, 제약사항을 정리한다. Discovery의 핵심 맥락을 가장 먼저 이해할 수 있어야 한다.
|
||||
|
||||
- 현재 상태
|
||||
- 코어 데몬은 intent 수락 → 슬롯 `idle→pending_buy`/`holding→pending_sell` 전이까지 수행(단일 writer, 불변식 A). 그러나 브로커/주문 집행/체결 처리 레이어가 없다(상태탐색: broker/order-exec/fill/dispatch 모듈 0).
|
||||
- `pending_buy`/`pending_sell` 슬롯을 `holding`/`closed` 로 진행시키는 **시스템 경로가 없다**(전이는 허용 정의만 있고 구동 주체 부재 — 현재는 테스트만 수동 전이).
|
||||
- `intent_log` 는 dedup 게이트 전용(비동기 outbox 아님, dcy-002 OQ-1).
|
||||
- 기대 상태
|
||||
- 코어가 **단일 브로커 세션**을 소유(불변식 B)하고, pending 슬롯을 집행해 매수/매도 주문을 송신한다.
|
||||
- 체결 시 `pending_buy→holding`(매수 체결) / `pending_sell→closed`(매도 체결), 거부/취소 시 `pending_buy→idle` 롤백을 코어가 단독 수행.
|
||||
- 주문 핸드오프가 durable 하여 크래시 후 reconciliation 가능(중복 주문 없이 재개).
|
||||
- 이해관계자
|
||||
- 문서 작성자/구현자(AI agent)
|
||||
- 리뷰어/승인자(운영자, genichin@gmail.com)
|
||||
- 코어 API 소비자(매수·매도 전략 데몬) — 집행 결과(체결/거부)를 슬롯 상태로 관측
|
||||
- 제약사항
|
||||
- 불변식 A — `daily_slot` 단일 writer 는 코어뿐(유지).
|
||||
- 불변식 B — 브로커 주문/취소는 코어의 단일 세션만(전략은 브로커 직접 접근 금지).
|
||||
- 도메인 순수성 — `trex_core.domain.slot` 은 브로커/네트워크 의존 0 유지(브로커는 adapters 레이어).
|
||||
- 실거래 안전 — 중복 주문 금지(멱등), 크래시 reconciliation, 안전한 기본값.
|
||||
|
||||
## 주요 사용자 시나리오
|
||||
사용자 또는 운영자가 실제로 어떤 상황에서 이 변경을 필요로 하는지 대표 시나리오를 적는다.
|
||||
|
||||
- 매수 intent 가 `pending_buy` 로 전이된 뒤, 코어 집행이 브로커에 매수 주문을 송신하고 체결되면 슬롯이 `holding` 으로 진행된다.
|
||||
- 매도 intent 로 `pending_sell` 이 된 슬롯을 코어가 매도 주문 송신 → 체결 시 `closed` 로 진행, 재진입 카운트 +1(recovery).
|
||||
- 데몬이 주문 송신 직후 크래시 → 재기동 시 reconciliation 으로 미체결/중복 주문을 정리(중복 주문 없음).
|
||||
|
||||
# 4. 이번에 정의할 변경
|
||||
이번 Discovery에서 다루는 핵심 변경 항목을 목록으로 적는다. 기능, 구조, 규칙 변경을 함께 포함해도 된다.
|
||||
|
||||
- 브로커 포트 + 단일 세션 어댑터(불변식 B): `BrokerPort`(submit_order/cancel/poll_fill 등) + 어댑터(슬라이스는 paper/stub 브로커 우선).
|
||||
- 주문 집행 루프(OQ-4 결정=별도 백그라운드 루프): pending 슬롯 claim → 주문 송신 → `broker_order_id` 기록 → 체결 폴링/처리 → 슬롯 전이(holding/closed) + 거부 시 롤백(idle) + reconcile. intent API 는 pending 전이까지만, 집행은 루프가 비동기.
|
||||
- durable 주문 핸드오프(OQ-3 결정=옵션 A): pending 슬롯 자체가 실행 큐. `broker_order_id` 멱등 가드 + 재기동 reconciliation. 별도 outbox 테이블 미신설(부분체결/재시도 본격화 시 옵션 B 승격 hook).
|
||||
- baseline 갱신: runtime-flows(집행/체결 흐름)·interface-contract(브로커 경계)·project-structure(broker adapter/execution 레이어)·data-model(주문/체결 상태).
|
||||
|
||||
## 영향 범위
|
||||
변경이 미칠 코드/문서/운영 범위를 명시해 REQ 정제와 batch planning에서 추정 누락을 줄인다.
|
||||
|
||||
- 코드 영향:
|
||||
- 신규: `trex_core/` 하위 broker 포트 + 어댑터 2종(paper/stub + **KIS**), 주문 집행 컴포넌트(루프/워커), 체결 폴링/처리, reconciliation. `pyproject` 에 KIS 호출용 HTTP 의존(httpx 등) + KIS 자격증명 config(.env).
|
||||
- 기존: 집행이 SlotService 로 `pending→holding/closed`/`pending_buy→idle` 전이를 구동(단일 writer 유지).
|
||||
- 문서 영향:
|
||||
- runtime-flows/interface-contract/project-structure/data-model 갱신.
|
||||
- 운영 영향:
|
||||
- 실주문 송신 → 실거래 리스크. 브로커 자격증명/세션 관리, 레이트리밋, 장애 시 reconciliation 운영 절차 신설.
|
||||
|
||||
# 5. 요구사항 목록
|
||||
실제로 구현과 검증으로 이어질 요구사항을 기능/비기능으로 나누어 정리하고, 범위 경계를 명확히 적는다.
|
||||
|
||||
## 기능 요구사항
|
||||
- FR-1: `BrokerPort` 추상화와 단일 세션 어댑터를 제공하고(불변식 B), 코어만 주문/취소를 송신한다. 어댑터는 (a) 결정적 검증용 paper/stub 와 (b) **실제 KIS(한국투자증권) Open API 어댑터**를 모두 포함한다(OQ-1 결정). KIS 어댑터는 슬라이스에서 **KIS 모의투자 서버**로 검증하고, 실계좌 라이브 전환은 config 게이팅(운영 결정)으로 둔다.
|
||||
- FR-2: 주문 집행 컴포넌트가 `pending_buy` 슬롯을 `FOR UPDATE SKIP LOCKED`(status=pending_buy AND broker_order_id IS NULL)로 claim 해 매수 주문을 송신하고 `broker_order_id` 를 기록한다(옵션 A 실행 큐, 멱등 가드로 중복 디스패치 방지).
|
||||
- FR-3: 집행 루프가 `poll_fill` 로 체결을 **비동기 관측**(paper·KIS 동일 경로)해, 매수 체결 시 `pending_buy→holding`(avg_price/qty 반영), 거부/취소 시 `pending_buy→idle` 롤백을 코어가 단독 수행한다.
|
||||
- FR-4: `pending_sell` 슬롯을 claim 해 매도 주문 송신, `poll_fill` 비동기 체결 관측으로 체결 시 `pending_sell→closed`(recovery 시 재진입 +1)로 진행한다.
|
||||
- FR-5: 주문 핸드오프가 durable/멱등하다(옵션 A) — pending 슬롯 + `broker_order_id` 가 큐+멱등 가드이며, 재기동 시 `broker_order_id` 있는 pending 슬롯을 브로커 주문 상태와 대조하는 reconciliation 으로 미체결/중복을 정리한다(중복 주문 0). 별도 outbox 테이블은 두지 않는다.
|
||||
- FR-6: baseline 문서(runtime-flows/interface-contract/project-structure/data-model)를 집행/브로커 레이어에 맞게 갱신한다.
|
||||
|
||||
## 비기능 요구사항
|
||||
성능, 운영성, 일관성, 자동화 안정성 등 기능 외 요구사항을 적는다.
|
||||
|
||||
- NFR-1: 불변식 B — 브로커 세션/주문 송신은 코어 집행 경로에서만. 도메인/전략은 브로커 미접근.
|
||||
- NFR-2: 도메인 순수성 유지 — `trex_core.domain.slot` 은 브로커/네트워크 의존 0(어댑터 격리, import 스윕).
|
||||
- NFR-3: 멱등/내구성 — 동일 슬롯/주문에 대해 중복 주문이 발생하지 않으며, 크래시 재개 시 정확히 1회 의미를 보존한다.
|
||||
|
||||
## 범위 경계
|
||||
이번 반복에서 반드시 포함할 범위와 명시적으로 제외할 범위를 구분한다.
|
||||
|
||||
- In Scope
|
||||
- 브로커 포트 + paper/stub 어댑터(불변식 B), 주문 집행 루프, 체결/거부 처리(슬롯 전이), durable 핸드오프 + reconciliation, baseline 갱신.
|
||||
- In Scope (추가, OQ-1 결정)
|
||||
- 실제 KIS Open API 어댑터(주문 송신/취소/체결 조회), KIS 모의투자 서버 검증, 세션/토큰 관리·레이트리밋.
|
||||
- Out of Scope (후속 Discovery)
|
||||
- safety floor(forced_close/EOD/손절 backstop, liveness gating, sell_evaluation_log) — 별도 Discovery(브로커 집행 위에 얹음).
|
||||
- KIS **실계좌 라이브 go-live**(실자금 거래) — 어댑터는 구현하되 라이브 전환은 config 게이팅된 운영 결정으로 분리.
|
||||
- 매수·매도 전략 데몬, API 인증/인가, 수평 확장.
|
||||
|
||||
# 6. 리스크/가정 목록
|
||||
불확실성과 전제 조건을 분리해서 적는다. 리스크는 영향과 완화 방안을, 가정은 현재 판단의 전제를 기록한다.
|
||||
|
||||
## 리스크
|
||||
- R-1 (High): 실주문 중복/유실 — 크래시 타이밍에 따라 중복 주문 또는 미체결 방치 위험.
|
||||
- 완화 방안(OQ-3 결정=옵션 A): `broker_order_id` 멱등 가드(채워지면 재디스패치 안 함) + 재기동 reconciliation(broker_order_id 있는 pending 슬롯을 브로커 상태와 대조, FR-5). paper async 더블로 크래시 시나리오 테스트.
|
||||
- R-2 (High): KIS 비동기 체결 — 주문 송신과 체결이 분리(체결 조회/폴링)되어 부분체결·지연·실패 처리 복잡.
|
||||
- 완화 방안(OQ-2 결정): paper·KIS 통일 비동기 체결 계약(submit→poll). paper async 더블이 지연/부분/거부 체결을 **결정적으로 재현**해 운영과 동일 경로를 검증 + KIS 모의투자로 실 API 체결 확인 + 멱등 전이.
|
||||
- R-5 (High): KIS 실 API — 자격증명/토큰 만료·레이트리밋·API 변경·실자금 손실 위험.
|
||||
- 완화 방안: 슬라이스는 KIS **모의투자 서버**로만 검증, 실계좌 라이브는 config 게이팅 분리(Out of Scope). 자격증명은 .env/시크릿(REQ-010 패턴), 토큰 갱신·레이트리밋 어댑터 내 처리.
|
||||
- R-3 (Medium): 도메인 순수성/단일 writer 침식 — 집행 컴포넌트가 broker+slot 을 함께 다뤄 경계가 흐려질 위험.
|
||||
- 완화 방안: broker 는 adapters, 슬롯 쓰기는 SlotService 단일 경로(NFR-1/2), import 스윕 가드. 집행 루프(OQ-4)는 코어 내 단일 주체로 단일 writer/세션 유지(같은 프로세스 백그라운드).
|
||||
- R-4 (Medium): 실거래 안전 — 잘못된 집행이 금전 손실.
|
||||
- 완화 방안: 슬라이스 1 비실거래(paper), 안전 기본값, safety floor 는 후속이지만 본 설계가 그 hook 을 남긴다.
|
||||
|
||||
## 가정
|
||||
아직 확정되지 않았지만 현재 문서 작성의 기반이 되는 전제를 적는다.
|
||||
|
||||
- A-1: 코어는 단일 인스턴스로 `daily_slot` 단일 writer + 단일 브로커 세션을 소유한다(수평 확장 비대상).
|
||||
- A-2: 집행·체결의 결정적 검증은 paper/stub 로, 실 API 검증은 KIS **모의투자 서버**로 수행한다. 실계좌 라이브(실자금)는 본 슬라이스 비대상(config 게이팅 운영 결정).
|
||||
- A-3: safety floor 는 본 Discovery 가 아니라 후속에서 다루되, 본 집행 설계가 그 hook(강제청산 소비 지점)을 남긴다.
|
||||
|
||||
## 오픈 질문
|
||||
답을 아직 모르는 항목을 적는다. 추정으로 덮지 말고 REQ 초안 작성 이전에 확인할 질문으로 남긴다.
|
||||
|
||||
- OQ-1: 브로커 어댑터 범위 — paper/stub 만(슬라이스 1) vs 실제 증권사(예: KIS) 어댑터까지.
|
||||
- 상태: Answered (2026-06-04)
|
||||
- 결정: **실제 KIS(한국투자증권) Open API 어댑터까지 구현.** paper/stub(결정적 테스트)와 KIS 어댑터를 모두 제공하고, KIS 는 **모의투자 서버**로 슬라이스 검증, 실계좌 라이브 go-live 는 config 게이팅으로 분리(Out of Scope). 근거: 실제 거래 능력 확보가 목표이고 KIS 모의투자로 안전하게 실 API 를 검증 가능.
|
||||
- 반영 위치: `# 4`(코드 영향), `# 5` FR-1·In Scope·Out of Scope, `# 6` R-2/R-4·A-2. OQ-2(체결 모델)는 KIS 비동기 체결을 반드시 포함하도록 파급.
|
||||
- OQ-2: 체결 처리 모델 — paper 도 KIS 와 동일한 **비동기 체결 구조**로 통일할지(검증 정확도).
|
||||
- 상태: Answered (2026-06-04)
|
||||
- 결정: **단일 비동기 체결 계약으로 통일.** `BrokerPort` 는 `submit_order`(→ accepted + broker_order_id) 와 `poll_fill`(체결 관측)로 분리하고, 집행 루프가 폴링으로 체결을 반영한다. paper/stub 은 즉시체결이 가능하더라도 **동기로 단축하지 않고** 동일한 submit→poll 구조를 따르되, 체결 시점·부분체결·거부를 **프로그래밍 가능한 결정적 더블**로 제공한다. KIS 는 체결 조회 API 폴링. 근거: 테스트(paper)와 운영(KIS)이 **같은 집행 코드 경로**를 타야 검증이 정확하고, paper 의 결정적 제어가 즉시체결보다 엣지 케이스(지연/부분/거부) 검증력이 높다.
|
||||
- 반영 위치: `# 5` FR-1(paper 도 async 더블)·FR-3·FR-4, `# 6` R-2 완화, `# 7` S-1/S-2/S-6. 집행 루프 폴링 → OQ-4(별도 execution 루프) 방향 강화.
|
||||
- OQ-3: 주문 핸드오프 durability 형태 — pending 슬롯 자체를 실행 큐로(orbit `claim ... FOR UPDATE SKIP LOCKED`) vs 별도 order outbox 테이블 vs intent_log 의 outbox 승격.
|
||||
- 상태: Answered (2026-06-04)
|
||||
- 결정: **옵션 A — pending 슬롯 자체가 실행 큐.** 별도 테이블 없이 `daily_slot.status IN (pending_buy,pending_sell) AND broker_order_id IS NULL` 을 `FOR UPDATE SKIP LOCKED` 로 claim, 주문 송신 후 `broker_order_id` 기록(멱등 가드 — 채워지면 재디스패치 안 함). reconciliation 은 `broker_order_id` 있는 pending 슬롯을 브로커 상태와 대조. dcy-002 `intent_log` 는 dedup 용도로 유지(outbox 승격 안 함, 옵션 C 지양). 부분체결/재시도가 본격화되면 별도 order 테이블(옵션 B)로 승격하는 hook 을 남긴다. 근거: 단순·orbit 검증·슬롯 단일 진실, 한 슬롯=한 주문 모델에 충분.
|
||||
- 반영 위치: `# 4`(변경 항목), `# 5` FR-2·FR-5, `# 6` R-1 완화. 별도 outbox 테이블 미신설.
|
||||
- OQ-4: 집행 트리거 — 별도 execution 워커 루프(주기적 claim) vs intent 수락 직후 인라인 디스패치.
|
||||
- 상태: Answered (2026-06-04)
|
||||
- 결정: **별도 execution 루프(데몬 프로세스 내 백그라운드).** 루프가 ① claim→주문 송신→broker_order_id 기록 ② poll_fill→체결 전이 ③ reconcile 를 주기적으로 수행한다. intent API 는 슬롯 pending 전이까지만(빠른 응답), 집행은 루프가 비동기. 인라인 nudge 는 선택적 후속 최적화로 보류. 근거: OQ-2(폴링 체결)·OQ-3(claim 큐+reconciliation)가 지속 집행 주체를 요구 → 루프가 정합. 단일 writer/세션은 같은 프로세스 내 단일 루프로 유지.
|
||||
- 반영 위치: `# 4`(변경 항목), `# 5` FR-2~FR-5(집행 루프 주체), `# 6` R-3. 폴링 주기·배치 크기는 config(구현 세부).
|
||||
|
||||
### 오픈 질문 처리 기준
|
||||
- `Open`: 아직 답이 없고 다음 단계 진행에 영향이 있는 상태다. 문서에 유지한다.
|
||||
- `Answered`: 답이 확정된 상태다. 관련 본문/요구사항에 반영한 뒤 오픈 질문 목록에서는 제거하거나 resolved 기록으로 이동한다.
|
||||
- `Deferred`: 지금 단계에서 결정하지 않고 다음 단계 또는 후속 이슈로 넘기는 상태다. 넘길 대상과 이유를 반드시 적는다.
|
||||
- `Dropped`: 더 이상 유효하지 않은 질문이다. 삭제 사유를 짧게 남기고 목록에서 제거한다.
|
||||
- 처리 원칙 1: 질문만 남기지 말고 반드시 `상태`, `처리 방안`, `종료 조건`을 함께 적는다.
|
||||
- 처리 원칙 2: 답이 나온 질문은 본문 반영 없이 단순 삭제하지 않는다. 반영 위치를 먼저 갱신한다.
|
||||
- 처리 원칙 3: High 영향 질문은 `Deferred` 처리 후 처리 방안에 REQ 인계 추적 방식을 명시한다.
|
||||
|
||||
# 7. 초기 성공 기준
|
||||
이 변경이 성공했다고 판단할 기준을 측정 가능하게 정의한다. 가능하면 데이터 출처까지 연결한다.
|
||||
|
||||
- S-1: paper 브로커로, 매수 intent → pending_buy → 집행 주문 송신(accepted) → **폴링 체결** → `holding` 까지 코어가 자동 진행한다.
|
||||
- S-2: 매도 intent → pending_sell → 집행 → 폴링 체결 → `closed` + 재진입 +1 까지 자동 진행한다.
|
||||
- S-3: 동일 슬롯에 대해 집행이 두 번 돌아도 중복 주문이 생기지 않는다(broker_order_id 멱등).
|
||||
- S-4: 주문 송신 직후 크래시 시뮬레이션 후 재기동 → reconciliation 으로 중복 주문 없이 일관 상태로 수렴.
|
||||
- S-5: 도메인 import 스윕에서 브로커/네트워크 의존이 0 으로 유지된다(불변식 B/순수성).
|
||||
- S-6: paper async 더블이 비동기 체결(즉시/지연/부분/거부)을 결정적으로 재현하고, 동일 집행 경로가 KIS 모의투자에서도 동작한다(검증 정확도).
|
||||
|
||||
## 측정 방식 및 데이터 출처
|
||||
각 성공 기준을 어떻게 측정할지와 어떤 데이터나 문서를 근거로 쓸지 적는다.
|
||||
|
||||
- S-1/S-2 측정 방식: paper 브로커 통합테스트(전체 lifecycle) / 데이터 출처: 테스트 결과, 슬롯 상태·transition_log.
|
||||
- S-3 측정 방식: 집행 중복 호출 테스트(같은 슬롯) / 데이터 출처: 브로커 주문 호출 수, broker_order_id.
|
||||
- S-4 측정 방식: 크래시 주입 후 reconciliation 테스트 / 데이터 출처: 주문 수·슬롯 상태 일관성.
|
||||
- S-5 측정 방식: 정적 import 스윕 / 데이터 출처: `trex_core/domain` import 목록.
|
||||
- S-6 측정 방식: paper 더블의 fill 시나리오(즉시/지연/부분/거부) 파라미터화 테스트 + KIS 모의투자 lifecycle / 데이터 출처: 테스트 결과, 체결 로그.
|
||||
|
||||
# 8. REQ로 넘기기 전 확인 체크
|
||||
REQ 초안 작성 단계로 넘기기 전에 무엇이 확정되어야 하는지 확인한다. 미완료 항목은 후속 결정이 필요함을 뜻한다.
|
||||
|
||||
- [x] 범위(In Scope/Out of Scope) 확정 — 특히 safety floor·실 브로커 제외
|
||||
- 기준: 운영자가 슬라이스 경계를 확인했다. → confirm-discovery 에서 문서대로 확정(2026-06-04).
|
||||
- [x] 성공 지표의 측정 방식/데이터 출처 확정
|
||||
- 기준: S-1~S-5 측정 방식·출처 명시(본 문서 # 7).
|
||||
- [x] High 영향 리스크(R-1 중복주문, R-2 KIS 체결, R-5 KIS 실 API) 처리 방침 확정
|
||||
- 기준: paper/stub + KIS 모의투자 검증 + reconciliation + 라이브 게이팅으로 수용. → 운영자 수용(2026-06-04).
|
||||
- [x] 모든 오픈 질문(OQ) `Open` 상태 없음 확인
|
||||
- 기준: OQ 목록에 `Open` 0개 또는 잔여 전부 `Deferred` (OQ-1~OQ-4 전부 Answered → `Open` 0개)
|
||||
- [x] Freeze 확정 담당자(CONFIRMED_BY) 지정
|
||||
- 기준: 운영자가 confirm-discovery 시점에 CONFIRMED_BY 를 지정한다. → Confirmed By: Justin.
|
||||
|
||||
# 9. 파일 처리 결과
|
||||
이 Discovery 문서 생성/갱신 결과와 참조 문서를 기록한다. 이후 추적과 리뷰 시 근거로 사용한다.
|
||||
|
||||
- 처리 결과: 생성
|
||||
- 생성 경로: docs/discovery/dcy-003_20260604_broker-execution-and-outbox.md
|
||||
- 참조 문서:
|
||||
- docs/discovery/dcy-002_20260603_slot-core-daemon-http-api.md (슬롯 코어 데몬·intent·intent_log — 본 Discovery 가 집행을 잇는다)
|
||||
- docs/project-structure.md, docs/runtime-flows.md, docs/interface-contract.md, docs/data-model.md (baseline — 본 Discovery 가 갱신 요구)
|
||||
- trex-orbit `orbit-v2_plan.md` (불변식 B·Order Execution·forced_close 소비자 설계 참고)
|
||||
|
||||
# 10. 사용자 결정 필요 항목 요약
|
||||
사용자나 승인자가 결정해야 하는 항목만 모아 정리한다. 결정, 확인, 데이터 요청을 구분해서 적는다.
|
||||
|
||||
## DECIDE
|
||||
- ~~브로커 어댑터 범위~~ → 결정됨: paper/stub + **실제 KIS 어댑터**(모의투자 검증, 실계좌 go-live 는 게이팅) (OQ-1, 2026-06-04)
|
||||
- ~~주문 핸드오프 durability~~ → 결정됨: **옵션 A(pending 슬롯=실행큐 + broker_order_id 멱등)**, 별도 테이블 미신설, B 승격 hook (OQ-3, 2026-06-04)
|
||||
|
||||
## CONFIRM
|
||||
- ~~체결 모델~~ → 결정됨: paper·KIS 통일 **비동기 체결**(submit→poll), paper 는 결정적 async 더블 (OQ-2, 2026-06-04)
|
||||
- ~~집행 트리거~~ → 결정됨: **별도 execution 루프**(데몬 내 백그라운드), 인라인 nudge 보류 (OQ-4, 2026-06-04)
|
||||
- ~~범위 경계(deferral) + High 리스크 수용~~ → 확정됨: safety floor·KIS 실계좌 라이브·전략 데몬·인증을 후속으로 미루고 슬라이스(브로커 포트+paper/stub+KIS 모의투자+집행 루프+비동기 체결+reconciliation) 승인. R-1/R-2/R-5 완화책(멱등+reconciliation, paper async 더블+KIS 모의투자, 실계좌 게이팅) 수용 (confirm-discovery, 2026-06-04)
|
||||
|
||||
## DATA
|
||||
- 없음 (별도 외부 데이터 요청 없음)
|
||||
|
||||
# 11. Discovery Freeze
|
||||
REQ 초안 작성 인계 시점의 확정 플래그와 섹션 참조만 기록한다. 내용 재작성 없이 원본 섹션을 링크로 대신한다.
|
||||
|
||||
## 섹션 참조
|
||||
- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
|
||||
- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
|
||||
- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
|
||||
- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
|
||||
- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
|
||||
|
||||
## Freeze 플래그
|
||||
- Handoff Decision: 승인
|
||||
- Handoff Rationale: OQ-1~OQ-4 전부 Answered(KIS 어댑터까지 / 통일 비동기 체결 / 옵션 A 실행큐 / 별도 execution 루프). 범위 경계(safety floor·KIS 실계좌·전략 데몬·인증 후속 Deferred)와 High 리스크(R-1/R-2/R-5) 완화책을 confirm-discovery 에서 운영자 확정·수용, CONFIRMED_BY 지정 완료. REQ Drafting 으로 인계 가능.
|
||||
- Ready for REQ Drafting: true
|
||||
- Confirmed By: Justin
|
||||
- Confirmed At (KST): 2026-06-04
|
||||
@@ -7,4 +7,5 @@
|
||||
| ID | 날짜 | 이슈명 | 문서 | 상태 |
|
||||
|---|---|---|---|---|
|
||||
| dcy-001_20260603_slot-pure-domain-migration | 20260603 | trex-core 베이스 수립 및 slot 순수 도메인 이식 | [Discovery](./dcy-001_20260603_slot-pure-domain-migration.md) | confirmed |
|
||||
| dcy-002_20260603_slot-core-daemon-http-api | 20260603 | trex-core 슬롯 코어 데몬화 + HTTP intent API | [Discovery](./dcy-002_20260603_slot-core-daemon-http-api.md) | confirmed |
|
||||
| dcy-002_20260603_slot-core-daemon-http-api | 20260603 | trex-core 슬롯 코어 데몬화 + HTTP intent API | [Discovery](./dcy-002_20260603_slot-core-daemon-http-api.md) | confirmed |
|
||||
| dcy-003_20260604_broker-execution-and-outbox | 20260604 | 브로커 단일 세션 + 주문 집행 + durable outbox (불변식 B) | [Discovery](./dcy-003_20260604_broker-execution-and-outbox.md) | confirmed |
|
||||
@@ -0,0 +1,69 @@
|
||||
# req-015: 브로커/집행 baseline 문서 정합
|
||||
|
||||
- Status: Proposed
|
||||
- Type: Documentation
|
||||
- Priority: Medium
|
||||
- Owner: project maintainers
|
||||
|
||||
## Intent
|
||||
- 브로커 세션·주문 집행·체결·reconciliation 레이어가 추가된 뒤 baseline 문서를 실제 구조/흐름/계약과 일치시킨다.
|
||||
|
||||
## Requirement
|
||||
- `docs/runtime-flows.md`(집행 루프·체결·reconciliation 흐름), `docs/project-structure.md`(broker adapter·execution 레이어), `docs/interface-contract.md`(BrokerPort 경계·KIS), `docs/data-model.md`(broker_order_id 를 실행큐/멱등 가드로 쓰는 의미)를 갱신한다.
|
||||
|
||||
## Acceptance Criteria
|
||||
1. Given 집행 구현 완료, When runtime-flows 확인, Then 집행 루프(claim→송신→poll→전이)·reconciliation 흐름이 실제와 일치한다.
|
||||
2. Given project-structure 확인, Then broker adapter(paper/KIS)·execution 레이어가 반영된다.
|
||||
3. Given interface-contract/data-model 확인, Then BrokerPort 경계와 broker_order_id 의 실행큐/멱등 역할이 반영된다.
|
||||
|
||||
## Impacted Area
|
||||
- Docs: docs/runtime-flows.md, docs/project-structure.md, docs/interface-contract.md, docs/data-model.md
|
||||
- Modules: 없음
|
||||
- Tests: 없음
|
||||
|
||||
## Notes
|
||||
- dcy-003 FR-6. REQ-011~014 구현 완료 후 수행(순서 의존).
|
||||
- 출처: dcy-003 FR-6.
|
||||
|
||||
## Change Log
|
||||
|
||||
### CHG-20260604-01
|
||||
- Date: 2026-06-04
|
||||
- Author: Justin Ko
|
||||
|
||||
#### Change Summary
|
||||
- dcy-003 FR-6 로부터 최초 생성(Proposed).
|
||||
|
||||
#### Intent
|
||||
- 브로커/집행 baseline 정합 요구사항을 backlog 로 정규화.
|
||||
|
||||
#### Acceptance Criteria Delta
|
||||
- Added:
|
||||
- runtime-flows, project-structure, interface-contract/data-model 정합 3개 기준
|
||||
- Updated:
|
||||
- 없음
|
||||
- Removed:
|
||||
- 없음
|
||||
|
||||
#### Impacted Area Delta
|
||||
- Docs:
|
||||
- docs/runtime-flows.md, docs/project-structure.md, docs/interface-contract.md, docs/data-model.md
|
||||
- Modules:
|
||||
- 없음
|
||||
- Tests:
|
||||
- 없음
|
||||
|
||||
#### Delivery Trace Delta
|
||||
- Batches:
|
||||
- none
|
||||
- Releases:
|
||||
- none
|
||||
|
||||
#### Revalidation Impact
|
||||
- Reverification Needed: no
|
||||
- Existing Implementation Invalidated: no
|
||||
- Status Recommendation: keep-current
|
||||
- Follow-up Action: REQ-011~014 구현 후 batch verification 단계에서 수행
|
||||
|
||||
#### Validation Plan
|
||||
- baseline 문서와 실제 구현(레이어/흐름/계약) 대조로 검증.
|
||||
@@ -0,0 +1,70 @@
|
||||
# req-014: 주문 핸드오프 durability + reconciliation
|
||||
|
||||
- Status: Proposed
|
||||
- Type: Exception
|
||||
- Priority: High
|
||||
- Owner: project maintainers
|
||||
|
||||
## Intent
|
||||
- 집행 도중 크래시가 나도 중복 주문 없이 일관 상태로 복구되도록, 옵션 A(pending 슬롯=실행큐 + broker_order_id 멱등)에 재기동 reconciliation 을 더한다.
|
||||
|
||||
## Requirement
|
||||
- 재기동 시 코어가 `broker_order_id` 가 채워진 pending 슬롯을 브로커 주문 상태와 대조해 reconciliation 한다: 체결됨→해당 전이(holding/closed), 거부/취소됨→롤백(idle), 미체결→계속 poll. `broker_order_id` 가 비어 있는 pending 슬롯은 미송신으로 보고 정상 claim 경로로 재개한다. 동일 슬롯/주문에 대해 중복 주문이 발생하지 않는다.
|
||||
|
||||
## Acceptance Criteria
|
||||
1. Given 주문 송신 후 broker_order_id 기록까지 된 상태에서 크래시, When 재기동 reconciliation, Then 같은 슬롯에 재주문하지 않고 브로커 상태로 전이를 정리한다(중복 주문 0).
|
||||
2. Given 주문 송신 전(broker_order_id NULL) 크래시, When 재기동, Then 정상 claim 으로 재개해 1회만 송신한다.
|
||||
3. Given 브로커에서 이미 체결된 주문, When reconciliation, Then 슬롯이 holding/closed 로 수렴한다.
|
||||
4. Given 동일 집행이 두 번 수행(루프 중복 틱), When 점검, Then broker_order_id 멱등 가드로 중복 주문이 생기지 않는다. (NFR-3)
|
||||
|
||||
## Impacted Area
|
||||
- Docs: docs/runtime-flows.md(reconciliation 흐름) — REQ-015
|
||||
- Modules: trex_core 집행/복구 컴포넌트(REQ-013 루프에 reconcile 단계), 브로커 주문 상태 조회 재사용
|
||||
- Tests: 크래시 주입(송신 전/후) 후 reconciliation, 중복 주문 0, 멱등 재틱
|
||||
|
||||
## Notes
|
||||
- 옵션 A 기반(별도 outbox 테이블 없음). 부분체결/재시도 본격화 시 옵션 B 승격은 후속.
|
||||
- 출처: dcy-003 FR-5, NFR-3. 핵심 안전(R-1) 완화의 실현.
|
||||
|
||||
## Change Log
|
||||
|
||||
### CHG-20260604-01
|
||||
- Date: 2026-06-04
|
||||
- Author: Justin Ko
|
||||
|
||||
#### Change Summary
|
||||
- dcy-003 FR-5 로부터 최초 생성(Proposed). NFR-3 흡수.
|
||||
|
||||
#### Intent
|
||||
- durable 핸드오프 + reconciliation(크래시 복구·멱등) 요구사항을 backlog 로 정규화.
|
||||
|
||||
#### Acceptance Criteria Delta
|
||||
- Added:
|
||||
- 송신후 크래시 reconciliation, 송신전 크래시 재개, 체결 수렴, 멱등 재틱 4개 기준
|
||||
- Updated:
|
||||
- 없음
|
||||
- Removed:
|
||||
- 없음
|
||||
|
||||
#### Impacted Area Delta
|
||||
- Docs:
|
||||
- docs/runtime-flows.md
|
||||
- Modules:
|
||||
- 집행/복구 컴포넌트(reconcile)
|
||||
- Tests:
|
||||
- 크래시 주입 reconciliation 테스트
|
||||
|
||||
#### 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
|
||||
- 크래시 주입(송신 전/후) reconciliation + 중복 주문 0 테스트로 검증.
|
||||
@@ -0,0 +1,69 @@
|
||||
# req-011: BrokerPort 추상화 + paper/stub async 더블
|
||||
|
||||
- Status: Proposed
|
||||
- Type: Integration
|
||||
- Priority: High
|
||||
- Owner: project maintainers
|
||||
|
||||
## Intent
|
||||
- 브로커를 코어에서 추상화하는 `BrokerPort` 를 정의하고(불변식 B 의 단일 경계), 결정적 검증용 paper/stub 어댑터를 제공한다. 이후 KIS 어댑터(REQ-012)와 집행 루프(REQ-013)가 이 포트 위에서 동작한다.
|
||||
|
||||
## Requirement
|
||||
- `BrokerPort`(application 포트)에 `submit_order(side, symbol, qty, ...) -> broker_order_id`, `cancel_order(broker_order_id)`, `poll_fill(broker_order_id) -> FillStatus(accepted/partially_filled/filled/rejected/cancelled, avg_price, filled_qty)` 를 정의한다. paper/stub 어댑터는 동기 단축 없이 submit→poll 비동기 계약을 따르되 체결 시점·부분체결·거부를 프로그래밍 가능한 결정적 더블로 제공한다. 어댑터는 adapters 레이어에 두고 도메인은 의존하지 않는다.
|
||||
|
||||
## Acceptance Criteria
|
||||
1. Given `BrokerPort` 정의, When paper 어댑터로 `submit_order`, Then `accepted` + broker_order_id 를 반환하고 즉시 `filled` 로 단축하지 않는다(다음 `poll_fill` 에서 체결).
|
||||
2. Given paper 더블의 fill 시나리오 설정(즉시/N틱 후/부분/거부), When `poll_fill` 반복, Then 설정대로 결정적으로 상태가 진행된다.
|
||||
3. Given 코드, When import 스윕, Then `trex_core.domain.slot` 은 broker/네트워크 의존이 0이고 BrokerPort 구현은 adapters 레이어에만 있다. (NFR-1/NFR-2)
|
||||
|
||||
## Impacted Area
|
||||
- Docs: docs/interface-contract.md(브로커 경계) — REQ-015 에서 정합
|
||||
- Modules: trex_core/application(BrokerPort), trex_core/adapters/broker(paper/stub)
|
||||
- Tests: paper 더블 fill 시나리오 테스트
|
||||
|
||||
## Notes
|
||||
- 불변식 B 의 단일 경계. KIS 어댑터는 REQ-012, 집행 루프는 REQ-013.
|
||||
- 출처: dcy-003 FR-1(포트+paper), NFR-1/NFR-2 흡수.
|
||||
|
||||
## Change Log
|
||||
|
||||
### CHG-20260604-01
|
||||
- Date: 2026-06-04
|
||||
- Author: Justin Ko
|
||||
|
||||
#### Change Summary
|
||||
- dcy-003 FR-1(포트+paper) 로부터 최초 생성(Proposed).
|
||||
|
||||
#### Intent
|
||||
- BrokerPort + paper async 더블 요구사항을 backlog 로 정규화.
|
||||
|
||||
#### Acceptance Criteria Delta
|
||||
- Added:
|
||||
- submit→poll 비동기 계약, 결정적 fill 시나리오, 도메인 순수성 3개 기준
|
||||
- Updated:
|
||||
- 없음
|
||||
- Removed:
|
||||
- 없음
|
||||
|
||||
#### Impacted Area Delta
|
||||
- Docs:
|
||||
- docs/interface-contract.md
|
||||
- Modules:
|
||||
- application(BrokerPort), adapters/broker(paper)
|
||||
- Tests:
|
||||
- paper 더블 시나리오 테스트
|
||||
|
||||
#### 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
|
||||
- paper 더블 비동기 체결 시나리오 단위테스트로 검증.
|
||||
@@ -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 모의투자 통합테스트(가용 시) + 토큰/오류 단위테스트로 검증.
|
||||
@@ -0,0 +1,72 @@
|
||||
# req-013: 주문 집행 루프 (claim·송신·체결·롤백)
|
||||
|
||||
- Status: Proposed
|
||||
- Type: Integration
|
||||
- Priority: High
|
||||
- Owner: project maintainers
|
||||
|
||||
## Intent
|
||||
- 코어 데몬 내 백그라운드 execution 루프가 pending 슬롯을 집행해 브로커에 주문을 송신하고 체결을 슬롯 상태로 반영한다(불변식 A 단일 writer 유지). intent API 는 pending 전이까지만, 집행은 루프가 비동기 수행.
|
||||
|
||||
## Requirement
|
||||
- 데몬 프로세스 내 별도 execution 루프가 주기적으로: ① `pending_buy`/`pending_sell` 슬롯을 `FOR UPDATE SKIP LOCKED`(broker_order_id IS NULL)로 claim → `BrokerPort.submit_order` → `broker_order_id` 기록(옵션 A), ② broker_order_id 있는 pending 슬롯을 `poll_fill` 로 비동기 관측해 매수 체결 시 `pending_buy→holding`(avg_price/qty), 매도 체결 시 `pending_sell→closed`(recovery 재진입 +1), ③ 거부/취소 시 `pending_buy→idle` 롤백을 수행한다. 모든 슬롯 쓰기는 SlotService(advisory lock) 단일 경로.
|
||||
|
||||
## Acceptance Criteria
|
||||
1. Given pending_buy 슬롯(paper), When 집행 루프 1회, Then 매수 주문 송신 + broker_order_id 기록, broker_order_id 채워진 슬롯은 재디스패치되지 않는다(멱등). (NFR-2 단일 writer)
|
||||
2. Given 송신된 매수 주문이 체결(poll), When 루프, Then `pending_buy→holding`(avg_price/qty 반영).
|
||||
3. Given 매수 주문 거부(poll), When 루프, Then `pending_buy→idle` 롤백.
|
||||
4. Given pending_sell 슬롯, When 집행+체결, Then 매도 주문 송신 → `pending_sell→closed` + 재진입 +1.
|
||||
5. Given 슬롯 쓰기 경로, When 점검, Then 집행 루프도 SlotService(advisory lock)로만 슬롯을 전이한다(브로커 직접 슬롯 쓰기 없음).
|
||||
|
||||
## Impacted Area
|
||||
- Docs: docs/runtime-flows.md(집행/체결 흐름) — REQ-015
|
||||
- Modules: trex_core/application 또는 runtime(execution 루프), SlotService 재사용
|
||||
- Tests: paper 더블로 매수/매도 lifecycle, 멱등 재디스패치, 거부 롤백, 체결→전이
|
||||
|
||||
## Notes
|
||||
- OQ-3(옵션 A 실행큐)·OQ-4(별도 루프)·OQ-2(비동기 poll) 결정 반영. 폴링 주기/배치 크기는 config.
|
||||
- reconciliation·크래시 복구는 REQ-014. KIS 어댑터는 REQ-012, paper 는 REQ-011.
|
||||
- 출처: dcy-003 FR-2, FR-3, FR-4. NFR-2 흡수.
|
||||
|
||||
## Change Log
|
||||
|
||||
### CHG-20260604-01
|
||||
- Date: 2026-06-04
|
||||
- Author: Justin Ko
|
||||
|
||||
#### Change Summary
|
||||
- dcy-003 FR-2·FR-3·FR-4 로부터 최초 생성(Proposed). NFR-2 흡수.
|
||||
|
||||
#### Intent
|
||||
- 주문 집행 루프(매수/매도 claim·송신·체결·롤백) 요구사항을 backlog 로 정규화.
|
||||
|
||||
#### Acceptance Criteria Delta
|
||||
- Added:
|
||||
- 매수 claim/멱등, 매수 체결→holding, 거부 롤백, 매도 체결→closed, 단일 writer 5개 기준
|
||||
- Updated:
|
||||
- 없음
|
||||
- Removed:
|
||||
- 없음
|
||||
|
||||
#### Impacted Area Delta
|
||||
- Docs:
|
||||
- docs/runtime-flows.md
|
||||
- Modules:
|
||||
- application/runtime(execution 루프)
|
||||
- Tests:
|
||||
- paper lifecycle/멱등/롤백/체결 테스트
|
||||
|
||||
#### 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
|
||||
- paper 더블 매수/매도 lifecycle + 멱등 + 롤백 테스트로 검증.
|
||||
+7
-1
@@ -74,7 +74,7 @@
|
||||
|
||||
## Next Requirement ID
|
||||
|
||||
- Current: `REQ-011`
|
||||
- Current: `REQ-016`
|
||||
- Rule: `Requirement Register`에 있는 가장 큰 REQ 번호보다 정확히 1 커야 한다.
|
||||
|
||||
## Requirement Register
|
||||
@@ -91,9 +91,15 @@
|
||||
| REQ-008 | 슬롯 read-only 조회 HTTP API | Interface | Implemented | High | project maintainers | [req-008](./Interface/req-008_slot-readonly-query-api.md) |
|
||||
| REQ-009 | 데몬/API/영속화 baseline 문서 정합 | Documentation | Implemented | Medium | project maintainers | [req-009](./Documentation/req-009_daemon-api-baseline-alignment.md) |
|
||||
| REQ-010 | 데몬 설정 .env 파일 로딩 | Configuration | Implemented | Medium | project maintainers | [req-010](./Configuration/req-010_daemon-dotenv-loading.md) |
|
||||
| REQ-011 | BrokerPort 추상화 + paper/stub async 더블 | Integration | Proposed | High | project maintainers | [req-011](./Integration/req-011_broker-port-and-paper-double.md) |
|
||||
| REQ-012 | KIS Open API 브로커 어댑터 | Integration | Proposed | High | project maintainers | [req-012](./Integration/req-012_kis-broker-adapter.md) |
|
||||
| REQ-013 | 주문 집행 루프 (claim·송신·체결·롤백) | Integration | Proposed | High | project maintainers | [req-013](./Integration/req-013_order-execution-loop.md) |
|
||||
| REQ-014 | 주문 핸드오프 durability + reconciliation | Exception | Proposed | High | project maintainers | [req-014](./Exception/req-014_order-handoff-durability-reconciliation.md) |
|
||||
| REQ-015 | 브로커/집행 baseline 문서 정합 | Documentation | Proposed | Medium | project maintainers | [req-015](./Documentation/req-015_broker-execution-baseline-alignment.md) |
|
||||
|
||||
## Recent Change Log Summary
|
||||
|
||||
- 2026-06-04 :: REQ-011~015 최초 생성(Proposed) — dcy-003 FR-1~FR-6 분해. (draft-req)
|
||||
- 2026-06-04 :: REQ-010 Approved → Implemented — BAT-003 verification evidence 기반. (confirm-req-implemented)
|
||||
- 2026-06-04 :: REQ-010 생성 + Approved — 데몬 .env 로딩 (minor-change). (draft-req/confirm-req)
|
||||
- 2026-06-03 :: REQ-005~009 Approved → Implemented — BAT-002 verification evidence 기반. (confirm-req-implemented)
|
||||
|
||||
Reference in New Issue
Block a user