trex-core/docs/srs/Integration/req-069_order-timeout-execution.md

req-069: 주문 timeout 집행 — timeout 초과 시 cancel_order 송신·롤백·부분 보존

• Status: Implemented
• Type: Integration
• Priority: High
• Owner: project maintainers

Intent

• 집행 루프가 dispatched-pending 슬롯의 timeout_sec 를 추적해 초과 시 broker.cancel_order 를 송신(best-effort)하고, 취소 확인 후 롤백하며 이미 체결된 부분 수량을 보존한다. 취소-체결 race 는 기존 poll 경로로 자연 수렴한다. (dcy-022 FR-2, FR-4)

Requirement

• _poll 루프에서 dispatched-pending 슬롯이 timeout_sec 를 가지고 경과 시간이 초과하면 broker.cancel_order(broker_order_id, ...) 를 best-effort 로 송신한다(송신 실패는 WARNING 로그, 슬롯 상태 불변). 취소 요청 송신 직후 슬롯을 즉시 전이하지 않는다 — 다음 poll 틱에서 is_terminal_reject(전량 취소)·is_partial_cancel(부분 체결 후 취소) 경로로 수렴한다(기존 롤백/부분 보존 경로 재사용, REQ-013 CHG-03). timeout_sec 없는 슬롯은 기존 stale-alert 만(_check_stale_pending) 실행(Alert-only, REQ-014 회귀 없음).

Acceptance Criteria

1. Given dispatched-pending 슬롯에 timeout_sec=10 설정, When 경과 시간 10초 초과, Then 집행 루프가 broker.cancel_order 를 송신하고 timeout_cancelled 카운터가 증가한다.
2. Given cancel_order 응답 True(브로커 수락), When 다음 poll, Then 슬롯은 is_terminal_reject 경로로 rollback 된다(pending_buy→inactive 또는 pending_sell→holding).
3. Given timeout 취소 전 일부 체결(is_partial_cancel), When 다음 poll, Then 기존 _on_partial_cancel 경로 — 체결분 원장 기록·잔량 holding 복귀(부분 보존, dcy-013 선례).
4. Given cancel_order 가 False 반환(이미 체결 — 취소-체결 race), When 다음 poll, Then is_filled 경로로 정상 체결 처리(임의 롤백 없음). (FR-4 race 안전)
5. Given timeout_sec 없는 dispatched-pending 슬롯, When 경과 시간 초과, Then cancel_order 미송신 — 기존 stale_pending WARN 만(Alert-only, REQ-014 회귀 없음).
6. Given cancel_order 송신 실패(예외), When 처리, Then WARNING 로그 + timeout_cancelled 미증가, 슬롯 상태 불변(비차단, NFR-2).

Impacted Area

• Docs: docs/runtime-flows.md(timeout 취소 흐름 추가)
• Modules: trex_core/application/execution.py(_poll timeout cancel, ExecutionResult +timeout_cancelled)
• Tests: tests/application/test_execution.py(timeout→cancel), test_execution_cancel.py(timeout 부분 보존)

Notes

• updated_at 를 dispatch 시각 proxy 로 사용(mark_dispatched 가 updated_at 갱신 — _check_stale_pending 과 동일 방법).
• best-effort 원칙: 송신 실패 시 다음 틱 재시도(threshold 넘으면 재송신). 중복 cancel_order 는 브로커가 멱등 처리(기존 KIS/paper 어댑터 계약).
• 출처: dcy-022 FR-2, FR-4, NFR-2.

Change Log

CHG-20260610-01

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

Change Summary

• dcy-022 FR-2/FR-4 로부터 최초 생성(Proposed). timeout 취소·race 처리·부분 보존.

Intent

• dispatched-pending 주문 timeout 집행 + 취소-체결 race 안전 처리를 backlog 로 정규화.

Acceptance Criteria Delta

• Added: AC-1~6 (timeout cancel, 전량/부분 취소 수렴, race 안전, 하위호환, 비차단 6개 기준)
• Updated: 없음
• Removed: 없음

Impacted Area Delta

• Modules: execution.py(_poll), ExecutionResult
• Tests: test_execution, test_execution_cancel

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 후 BAT-032.

Validation Plan

• timeout → cancel_order 송신 + 롤백 수렴 단위. race(cancel→filled 수렴) 단위.

CHG-20260610-02

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

Change Summary

• Status Proposed → Approved (confirm-req).

Intent

• delivery input 으로 승격.

Acceptance Criteria Delta

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

Impacted Area Delta

• Docs: docs/srs/index.md (Register Approved)

Delivery Trace Delta

• Batches: none

Revalidation Impact

• Reverification Needed: no / Existing Implementation Invalidated: no / Status Recommendation: keep-current / Follow-up Action: BAT-032.

Validation Plan

• 승인 후 batch planning 에서 AC 검증 기준으로 사용.

CHG-20260611-IMPL

• Date: 2026-06-11
• Author: Justin Ko
• Type: status
• Summary: Approved → Implemented (confirm-req-implemented). 근거: BAT-032(release-candidate) verification — 실행 정책(timeout_sec·slippage_pct) 계약·집행·운영자 cancel 백스톱 전 AC acceptance mapping 존재(신규 71 tests), 단위 425 passed 회귀 없음, baseline 2문서 수동 확인(M5). Blocking Issues 없음.