trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
91fee4808d4fccfc2fafc593356d7d39d5dd330d
trex-core/docs/srs/Documentation/req-015_broker-execution-baseline-alignment.md
T
genichinandClaude Opus 4.8 4746f74aae fix(broker): dcy-013 KIS 외부 취소 감지 + 부분 체결 회계 + stale 워치독 (BAT-017) 
KIS 계좌에서 직접 매도 주문을 취소하면 poll_fill 이 cncl_yn 을 파싱하지 않아
슬롯이 pending_sell 에 영구히 갇히고 죽은 주문을 무한 폴링하던 버그(issue #9)
정정.

거버넌스: 전부 change-req (신규 REQ 없음, dcy-013 OQ-3).
- REQ-012: KIS poll_fill cncl_yn 파싱 → 외부 취소 감지. FillStatus.cancelled
  /is_partial_cancel 추가. 체결 0 취소→cancelled, 부분 체결 후 취소→partial+cancelled
- REQ-013: 집행 _on_partial_cancel — 체결분 원장 1회 + qty 차감(매도 잔여/매수 체결분)
  + holding 복귀 (OQ-1 A안). 전량 취소는 기존 롤백 경로 재사용
- REQ-018: 부분 체결분 원장 1회 기록 (_record_ledger 재사용)
- REQ-031: 잔여 포지션 정합 연계 (slot.qty ↔ 실 잔고, 과매도 방지)
- REQ-014: pending stale 워치독 Alert-only (TREX_PENDING_STALE_THRESHOLD,
  WARN+카운터, 상태 미변경) — 취소 감지 누락 backstop
- REQ-015: interface-contract/runtime-flows 정합

전량 취소는 holding 자동 복구(limit_price clear→재매도 시장가, dcy-012 연계).
KIS cncl_yn 실 규약은 운영 검증(미지 값 보수 처리 + 워치독 backstop).

검증: 단위 294 passed/32 skipped, 인프라 게이트(PG+RabbitMQ) 326 passed, ruff clean.
신규 test_kis_cancel(httpx stub) + test_execution_cancel(programmable broker).
BAT-017 release-candidate.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-08 14:11:49 +09:00

6.5 KiB
Raw Blame History

req-015: 브로커/집행 baseline 문서 정합

  • Status: Implemented
  • 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 문서와 실제 구현(레이어/흐름/계약) 대조로 검증.

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 재참조로 충분.

CHG-20260608-01

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

Change Summary

  • (change-req, dcy-012) baseline 문서를 새 매도 가격 정책·limit_price 생애주기·컬럼 rename 에 맞춰 정합: docs/runtime-flows.md(dispatch 가격 결정 = slot.limit_price 단일 필드 + 생애주기 set/clear), docs/interface-contract.md(sell payload optional limit_price + ORD_DVSN 매핑), docs/data-model.md(슬롯 limit_price 컬럼). BAT-016 정합 완료 → Implemented 유지.

Intent

  • 코드(execution/intents/slot/persistence) 변경과 baseline 문서를 일치(S-4)시켜 운영자/전략 개발자 참조 정합 유지.

Acceptance Criteria Delta

  • Updated:
    • runtime-flows/interface-contract/data-model 의 매도 가격·limit_price 기술 정합.

Impacted Area Delta

  • Docs: docs/runtime-flows.md, docs/interface-contract.md, docs/data-model.md

Delivery Trace Delta

  • Batches: BAT-016
  • Releases: none

Revalidation Impact

  • Reverification Needed: no (문서 정합)
  • Existing Implementation Invalidated: no
  • Status Recommendation: Implemented (change-req → BAT-016 정합)
  • Follow-up Action: confirm-req-implemented(BAT-016).

Validation Plan

  • BAT-016: 코드-문서 diff 대조(S-4).

CHG-20260608-02

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

Change Summary

  • (change-req, dcy-013) baseline 문서를 외부 취소 감지·부분 체결 회계·pending stale 워치독에 맞춰 정합: docs/interface-contract.md(FillStatus.cancelled/is_partial_cancel + state별 집행 처리 + KIS cncl_yn 매핑), docs/runtime-flows.md(poll 단계 외부 취소 → 롤백/부분 회계 + Alert-only stale 워치독). BAT-017 정합 완료 → Implemented 유지.

Intent

  • 코드(kis/broker_port/execution/config) 변경과 baseline 문서를 일치(S 기준)시켜 운영자 참조 정합 유지.

Acceptance Criteria Delta

  • Updated:
    • interface-contract/runtime-flows 의 취소 감지·부분 회계·stale 워치독 기술 정합.

Impacted Area Delta

  • Docs: docs/interface-contract.md, docs/runtime-flows.md

Delivery Trace Delta

  • Batches: BAT-017
  • Releases: none

Revalidation Impact

  • Reverification Needed: no (문서 정합)
  • Existing Implementation Invalidated: no
  • Status Recommendation: Implemented (change-req → BAT-017 정합)
  • Follow-up Action: confirm-req-implemented(BAT-017).

Validation Plan

  • BAT-017: 코드-문서 diff 대조.
Reference in New Issue View Git Blame Copy Permalink