trex-core/docs/batches/bat-017_20260608_external-cancel-detection-stale-watchdog/design.md

BAT-017 Design

• Status: confirmed
• Batch: BAT-017

설계 목표

• KIS 외부 취소를 종료 상태로 정확히 매핑해 pending_sell 영구 갇힘(issue #9)을 자동 복구한다.
• 부분 체결 후 취소를 정확 회계(과매도·이중기록 방지)하고, 미지 원인 갇힘을 Alert-only 워치독으로 가시화한다.

1. FillStatus 계약 확장 (REQ-012)

• FillStatus.cancelled: bool = False 추가. is_partial_cancel 프로퍼티 = cancelled and filled_qty > 0.
• 매핑 규칙:
  • 체결 0 + 외부 취소 → state="cancelled"(기존 is_terminal_reject True).
  • 부분 체결(0<ccld<ord) + 외부 취소 → state="partially_filled" + cancelled=True(is_terminal_reject False, is_partial_cancel True) + execution_id/fee/avg_price 운반.
  • 전량 체결 → state="filled"(취소 플래그 무시).

2. KIS poll_fill (REQ-012)

• inquire-daily-ccld row 의 cncl_yn 을 파싱: str(cncl_yn).strip().upper() == "Y". 미지/부재 → 비취소(보수적, R-1; stale 워치독이 backstop).
• ccld_qty<=0: cancelled 면 cancelled 반환, 아니면 기존 accepted.
• 0<ccld<ord: cancelled 면 execution_id(kis-daily-ccld:{ord_dt}:{ord_gno_brno}:{odno}:{ccld_qty})+fee 합성 후 partial+cancelled 반환, 아니면 기존 partially_filled.
• 전량 체결: 기존 filled 경로 불변.

3. 집행 처리 (REQ-013/018, OQ-1 A안)

• _poll 분기 순서: is_filled → is_partial_cancel → is_terminal_reject → else(대기+stale 체크).
• 전량 취소(cancelled, ccld 0): 기존 _rollback 재사용 — 매도 pending_sell→holding+clear_dispatch, 매수 pending_buy→idle. holding 진입 시 limit_price clear(dcy-012) → 재매도 시장가(A-1).
• 부분 체결 후 취소 _on_partial_cancel:
  • 매도(PENDING_SELL): remaining = slot.qty - filled; transit_slot(PENDING_SELL→HOLDING, qty=remaining)(avg_price=None → cost basis 유지). 체결분(filled, 체결가) 원장 1회(_record_ledger 재사용).
  • 매수(PENDING_BUY): transit_slot(PENDING_BUY→HOLDING, qty=filled, avg_price=fill). 체결분 원장 1회.
  • 공통: clear_dispatch + event emit. r.filled += 1, _record_ledger 가 r.ledger_enqueued += 1.
• 멱등: SlotStateMismatchError 시 조용히 반환(다음 tick reconcile).

4. pending stale 워치독 (REQ-014, OQ-2 Alert-only)

• ExecutionService stale_pending_threshold_sec(<=0/None=비활성). _check_stale_pending(slot, now, r): age = now - slot.updated_at; age >= threshold 면 r.stale_pending += 1 + WARN. 상태 불변.
• slot.updated_at 출처: mark_dispatched/transit 가 갱신 → "마지막 쓰기 이후 경과"가 곧 "pending 체류 시간" 근사.
• config: DaemonConfig.pending_stale_threshold_sec(env TREX_PENDING_STALE_THRESHOLD, default 0). daemon 이 ExecutionService 에 주입.

5. 포지션 정합 연계 (REQ-031)

• _on_partial_cancel 이 slot.qty 를 잔여 held 와 일치시켜 reconcile_positions 의 입력 정합을 유지. reconcile 코드 자체 변경 없음(연계 change-req).

6. baseline 문서 (REQ-015)

• interface-contract: FillStatus.cancelled/is_partial_cancel + state별 집행 처리 + KIS cncl_yn 매핑.
• runtime-flows: poll 단계 외부 취소(전량→롤백 / 부분→회계) + Alert-only stale 워치독 + limit_price clear 재매도.

자동 복구 성립 근거 (A-2)

• is_terminal_reject 가 이미 cancelled 포함 + _rollback 이 pending_sell→holding 수행 → KIS 어댑터가 cancelled 만 정확히 반환하면 application 경로 재사용으로 복구(전량 취소 케이스는 코드 추가 없이 성립).

테스트 설계

• tests/adapters/broker/test_kis_cancel.py(httpx stub): full cancel→cancelled, zero-fill non-cancel→accepted, partial+cancel→is_partial_cancel(execution_id 확인), full fill 회귀.
• tests/application/test_execution_cancel.py(programmable broker): 전량 취소→holding 복귀+clear, 부분 취소→원장 1건+qty 차감+cost basis 유지, stale 워치독 WARN(상태 불변), 비활성 default.