trex/trex-core
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6da552bedb5b4192e9cee21b5466c02c470467e4
trex-core/docs/srs/Exception/req-014_order-handoff-durability-reconciliation.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-014: 주문 핸드오프 durability + reconciliation

  • Status: Implemented
  • 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 테스트로 검증.

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-013/issue #9, OQ-2 Alert-only) pending 주문 stale 워치독 추가: dispatched-pending 슬롯이 TREX_PENDING_STALE_THRESHOLD(초, 0=비활성) 초과로 머물면 WARN 로그 + ExecutionResult.stale_pending 카운터로 가시화한다. 슬롯/주문 상태는 변경하지 않는다(auto-remediation 후속). 취소 감지 누락(R-1) 등 미지 원인 무한 갇힘이 silent 로 남지 않게 하는 reconciliation 안전망. BAT-017 재구현·재검증 완료 → Implemented 유지.

Intent

  • 자동 취소 감지(REQ-012)가 놓치는 케이스까지 포함해, 비정상적으로 오래 pending 인 주문을 운영자에게 노출하는 durability 안전망 제공.

Acceptance Criteria Delta

  • Added:
    • pending stale 임계 초과 시 WARN+카운터 가시화(상태 미변경, Alert-only). 임계 env TREX_PENDING_STALE_THRESHOLD(0=비활성).

Impacted Area Delta

  • Modules: trex_core/application/execution.py(_check_stale_pending, ExecutionService threshold), trex_core/runtime/config.py(pending_stale_threshold_sec/env), trex_core/runtime/daemon.py(배선)
  • Tests: tests/application/test_execution_cancel.py(stale WARN + 비활성)

Delivery Trace Delta

  • Batches: BAT-017
  • Releases: none

Revalidation Impact

  • Reverification Needed: yes (BAT-017 에서 완료)
  • Existing Implementation Invalidated: no (관측만 추가, 기존 reconcile/poll 동작 불변)
  • Status Recommendation: Implemented (change-req → BAT-017 재검증)
  • Follow-up Action: confirm-req-implemented(BAT-017).

Validation Plan

  • BAT-017: 임계 초과 pending 주입 → WARN+카운터, 상태 미변경 / 비활성(default) → 무경고 단위.
Reference in New Issue View Git Blame Copy Permalink