trex-core/docs/srs/Integration/req-037_forced-close-at-safety-sell-loop.md

req-037: forced_close_at 만기 자동 매도 루프

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

Intent

슬롯에 설정된 forced_close_at 만기 시각이 도달했을 때 데몬이 자율적으로 매도를 제출하는 백그라운드 루프를 추가한다. 워치독이 만료된 슬롯에 한해 동작하므로 전략 모듈이 정상 활성 중인 슬롯에는 개입하지 않는다(dcy-007 FR-1, NFR-1).

Requirement

• 데몬은 TREX_FORCED_CLOSE_CHECK_INTERVAL(초) 주기로 holding 상태이며 워치독이 만료된 슬롯 중 forced_close_at <= now(KST)인 슬롯을 감지해야 한다.
• 조건에 해당하는 슬롯에 대해 SlotService.sell()(REQ-036)을 통해 내부 매도를 제출해야 한다.
• 이 루프는 daemon.py의 safety-sell worker 스레드에서 실행된다. 기존 6개 스레드에 safety-sell worker(trex-safety-sell)를 추가한다.
• forced_close_at이 None인 슬롯은 이 루프의 대상이 아니다.
• 워치독 활성(만료되지 않은) 슬롯은 이 루프의 대상이 아니다.

Acceptance Criteria

1. Given holding 상태이고 워치독 만료이며 forced_close_at = now() − 1s인 슬롯 S가 있을 때, When checker 1회가 수행되면, Then S에 대해 SlotService.sell()이 호출된다.
2. Given holding 상태이고 워치독 만료이며 forced_close_at = now() + 1hour인 슬롯 S가 있을 때, When checker 1회가 수행되면, Then S에 대해 sell()이 호출되지 않는다.
3. Given holding 상태이고 워치독 활성이며 forced_close_at = now() − 1s인 슬롯 S가 있을 때, When checker 1회가 수행되면, Then S에 대해 sell()이 호출되지 않는다(워치독 보호).
4. Given forced_close_at = None인 슬롯 S가 있을 때, When checker 1회가 수행되면, Then S는 만기 체크 대상에서 제외된다.
5. Given 대상 슬롯이 이미 pending_sell일 때, When checker 1회가 수행되면, Then 중복 sell() 호출이 발생하지 않는다(REQ-036 idempotency 적용).
6. Given TREX_FORCED_CLOSE_CHECK_INTERVAL=60일 때, When daemon이 정상 실행 중이면, Then checker는 60±허용오차 초 주기로 반복 실행된다(NFR-1: 감지 지연 ≤ 60초).

Impacted Area

• Docs:
  • docs/runtime-flows.md — forced_close_at 만기 감지 루프 흐름 추가 (REQ-042 참조)
  • docs/project-structure.md — trex-safety-sell 스레드 추가 반영 (REQ-042 참조)
• Modules:
  • trex_core/runtime/daemon.py — trex-safety-sell worker 스레드 추가, _safety_sell_loop() 메서드 구현
  • trex_core/domain/slot/service.py — forced_close_at 조건 평가 메서드(또는 checker 내 인라인)
• Tests:
  • forced_close_at checker 단위 테스트 — 만기 슬롯 감지 + sell() 호출 확인
  • 워치독 활성 슬롯 통과 확인
  • idempotency 확인 (pending_sell 슬롯 중복 처리 없음)

Notes

• safety-sell worker(trex-safety-sell)는 forced_close_at checker(REQ-037), stop-loss·take-profit checker(REQ-038), 장 마감 청산(REQ-039)을 하나의 통합 루프로 묶어 처리할 수 있다. 구체적인 스레드 분리/통합 방식은 batch planning에서 결정한다.
• 체크 로직은 DB 조회(forced_close_at 필드)와 in-memory 워치독 store 비교만 수행하므로 KIS API 호출이 없다. 낮은 연산 비용.
• TREX_FORCED_CLOSE_CHECK_INTERVAL env var는 REQ-041 참조.
• SlotService.sell() 구현은 REQ-036 참조.

Change Log

CHG-20260607-01

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

Change Summary

• dcy-007 confirmed → REQ-037 초안 생성

Intent

• forced_close_at 만기 자동 매도 루프(FR-1)를 독립 Integration REQ로 정규화

Acceptance Criteria Delta

• Added: AC-1~6 전체

Impacted Area Delta

• Docs: runtime-flows.md, project-structure.md (REQ-042에서 처리)
• Modules: daemon.py (스레드 추가), service.py (forced_close 조건 평가)
• Tests: checker 단위 테스트 3종

Delivery Trace Delta

• Batches: none (미할당)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs 후 batch 배정

CHG-20260607-02

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

Change Summary

• Proposed → Approved (confirm-req)

Intent

• 승인 게이트 통과: 필수 필드·AC·Impacted Area·Change Log 완비 확인. dcy-007(confirmed) 범위 및 결정 사항과 모순 없음.

Acceptance Criteria Delta

• (변경 없음)

Impacted Area Delta

• (변경 없음)

Delivery Trace Delta

• Batches: none (미할당)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs 후 batch 배정

CHG-20260607-03

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

Change Summary

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

Intent

• BAT-011 verification.md 의 AC↔evidence(SafetySellService forced_close checker — 만기/미만기/워치독 보호/None 제외/idempotency/캐던스)로 AC-1~6 충족 → 구현 완료 동기화.

Acceptance Criteria Delta

• (변경 없음)

Impacted Area Delta

• (변경 없음)

Delivery Trace Delta

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

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current (Implemented)
• Follow-up Action: draft-release 로 BAT-011 배포 편성.

CHG-20260608-01

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

Change Summary

• (change-req, dcy-017/issue #12) safety-sell 가시화: 워치독 소유 진입(전략 이탈)=WARN/이탈(복귀)=INFO(_update_ownership, run_once 매 tick), forced_close 발동=WARN(_log_fire) + in-process 카운터(SafetySellService.counters). 구조화 필드(slot_id/portfolio_id/reason/phase/instance_key). best-effort(가시화 실패가 청산을 막지 않음). 트리거 판정 동작 불변. BAT-021 재구현·재검증 완료 → Implemented 유지.

Intent

• 전략 이탈→안전망 소유, forced_close 발동을 무성에서 가시화(OQ-2 차등 매트릭스).

Acceptance Criteria Delta

• Added:
  • 워치독 소유 진입/이탈 + forced_close 발동 로그/카운터. per-tick 스킵은 카운터만.

Impacted Area Delta

• Modules: trex_core/application/safety_sell.py(_update_ownership/_log_fire/counters/instance_key), trex_core/runtime/daemon.py(instance_key 배선)
• Tests: tests/application/test_safety_sell_visibility.py

Delivery Trace Delta

• Batches: BAT-021
• Releases: none

Revalidation Impact

• Reverification Needed: yes (BAT-021 에서 완료)
• Existing Implementation Invalidated: no (관측만 추가, 트리거 불변)
• Status Recommendation: Implemented (change-req → BAT-021 재검증)
• Follow-up Action: confirm-req-implemented(BAT-021).

Validation Plan

• BAT-021: 소유 진입 WARN/이탈 INFO/forced_close WARN + 카운터 단위(caplog).