trex-core/docs/srs/Integration/req-011_broker-port-and-paper-double.md

req-011: BrokerPort 추상화 + paper/stub async 더블

• Status: Implemented
• 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 더블 비동기 체결 시나리오 단위테스트로 검증.

CHG-20260604-02

• Date: 2026-06-04
• Author: Justin Ko

Change Summary

• Status Proposed → Approved (confirm-req).

Intent

• 승인 게이트(필수 필드·구체 AC·blocker 없음) 충족, source dcy-003(confirmed, handoff 승인)와 모순 없음 확인.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/srs/index.md (Register 상태 Approved)
• Modules:
  • 없음
• Tests:
  • 없음

Delivery Trace Delta

• Batches:
  • none (batch 편성 전)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs / draft-batch 로 delivery batch 편성

Validation Plan

• 승인 후 batch planning 에서 본 REQ 의 Acceptance Criteria 를 검증 기준으로 사용.

CHG-20260604-03

• Date: 2026-06-04
• Author: Justin Ko

Change Summary

• Status Approved → Implemented (confirm-req-implemented, 근거 batch BAT-004 release-candidate).

Intent

• BAT-004 verification.md 의 acceptance mapping + evidence(pytest 92 pass / 도메인 순수성 / 데몬 E2E / KIS VTS 모의투자 round-trip)로 AC 충족 → 구현 완료 동기화.

Acceptance Criteria Delta

• Added:
  • 없음
• Updated:
  • 없음
• Removed:
  • 없음

Impacted Area Delta

• Docs:
  • docs/srs/index.md (Register Implemented)
• Modules:
  • 없음
• Tests:
  • 없음

Delivery Trace Delta

• Batches:
  • BAT-004 (release-candidate)
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: draft-release 로 release 편성(BAT-001~004)

Validation Plan

• BAT-004 verification evidence 재참조로 충분.