feat(safety-sell): dcy-007 core 자율 안전 매도 — BAT-010 기반 + BAT-011 트리거

dcy-007(core 자율 안전 매도) 전체 delivery. BAT-010 기반 인프라가 미커밋 상태였고 BAT-011 트리거 레이어와 공유 파일에서 섞여 있어 한 커밋으로 묶음. BAT-010 (REQ-034/035/036/041, release-candidate): - WatchdogStore(application/watchdog.py) + snapshot RPC 워치독 갱신 - Slot stop_loss_price/take_profit_price 필드 + 004_add_price_thresholds.sql - SlotService.sell() 자율 매도 내부 경로 + idempotency - SafetySellConfig env 5종 파싱 BAT-011 (REQ-037/038/039/040/042, release-candidate): - SafetySellService(application/safety_sell.py): forced_close 만기 / stop-loss· take-profit KIS polling / 장 마감 강제 청산 + trex-safety-sell 7번째 스레드 - BrokerPort.get_current_price + KIS inquire-price(TTTC8397R/VTTC8397R, stck_prpr) + paper stub - SlotService.update_thresholds() + intent RPC update_thresholds 액션 (부분 갱신/null 해제, 워치독 last_seen_at 리셋) - baseline 3문서 정합(interface-contract/runtime-flows/project-structure) 거버넌스: REQ-034~042 Implemented 동기화, BAT-010/011 release-candidate, dcy-007 discovery 포함. 검증: 신규 38 테스트 green, 단위 236 passed/23 skipped, 인프라 게이트(PG+RabbitMQ) 259 passed(마이그레이션 001~004 round-trip 포함), ruff clean. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-07 08:32:30 +09:00
parent e4e5228972
commit a30efa8f3b
47 changed files with 3399 additions and 36 deletions
@@ -0,0 +1,150 @@
+# 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 배포 편성.
@@ -0,0 +1,155 @@
+# req-038: stop-loss·take-profit KIS 가격 polling + 트리거
+
+- Status: Implemented
+- Type: Integration
+- Priority: High
+- Owner: project maintainers
+
+## Intent
+
+워치독이 만료된 슬롯에 한해 KIS API(`TTTC8397R` 실전 / `VTTC8397R` 모의)로 현재가를 주기적으로 polling하고, `현재가 <= stop_loss_price`(손절) 또는 `현재가 >= take_profit_price`(익절) 조건 충족 시 자동 매도를 제출한다. 전략 모듈이 정상 활성 중인 슬롯에는 개입하지 않는다(dcy-007 FR-2, NFR-3, A-3).
+
+## Requirement
+
+- 데몬은 `TREX_STOP_LOSS_POLL_INTERVAL(초)` 주기로, `stop_loss_price` 또는 `take_profit_price`가 설정되고 **워치독이 만료된** `holding` 슬롯들의 현재가를 KIS `TTTC8397R`(실전) / `VTTC8397R`(모의) API로 polling해야 한다.
+- 현재가 평가 기준값은 `stck_prpr`(직전 체결가) 필드를 사용한다.
+- `현재가 <= stop_loss_price` 조건 충족 시 손절 매도를 제출해야 한다.
+- `현재가 >= take_profit_price` 조건 충족 시 익절 매도를 제출해야 한다.
+- 두 조건은 동일 polling 루프에서 평가한다.
+- 워치독 활성(만료되지 않은) 슬롯과 임계값 미설정(`None`) 슬롯은 polling 대상이 아니다.
+- KIS API 호출 상한은 `워치독 만료 대상 슬롯 수 × (3600 / TREX_STOP_LOSS_POLL_INTERVAL)`로 산정한다. 이 상한이 KIS 쿼터를 초과할 경우 polling 간격 조정 AC를 이 REQ의 Notes에 명시하고 REQ 단계에서 상한 경고를 구현한다.
+- 자동 매도 제출은 `SlotService.sell()`(REQ-036)을 사용한다.
+
+## Acceptance Criteria
+
+1. Given `holding`, 워치독 만료, `stop_loss_price=Decimal("50000")`, `take_profit_price=None`인 슬롯 S가 있고 KIS polling 결과 `stck_prpr=49000`이면, When 가격 체크가 수행되면, Then S에 대해 `SlotService.sell()`이 호출된다(손절 트리거).
+2. Given `holding`, 워치독 만료, `stop_loss_price=None`, `take_profit_price=Decimal("80000")`인 슬롯 S가 있고 KIS polling 결과 `stck_prpr=81000`이면, When 가격 체크가 수행되면, Then S에 대해 `sell()`이 호출된다(익절 트리거).
+3. Given `holding`, 워치독 만료, `stop_loss_price=Decimal("50000")`, `take_profit_price=Decimal("80000")`인 슬롯 S가 있고 `stck_prpr=65000`이면, When 가격 체크가 수행되면, Then `sell()`이 호출되지 않는다(두 조건 모두 미충족).
+4. Given `holding`, 워치독 **활성**인 슬롯 S가 있을 때, When 가격 polling이 수행되면, Then S에 대한 KIS API 호출이 발생하지 않는다(워치독 보호).
+5. Given `stop_loss_price=None`이고 `take_profit_price=None`인 슬롯 S가 있을 때, When polling이 수행되면, Then S는 polling 대상에서 제외된다.
+6. Given 이미 `pending_sell` 상태인 슬롯 S에 조건이 충족될 때, When 가격 체크가 수행되면, Then 중복 `sell()` 호출이 발생하지 않는다(REQ-036 idempotency).
+7. Given 실전 모드(`broker=kis`)일 때, When 가격 polling을 수행하면, Then `TTTC8397R` endpoint를 사용한다. 모의 모드(`broker=paper`)일 때는 `VTTC8397R`을 사용한다.
+8. Given `TREX_STOP_LOSS_POLL_INTERVAL=30`이고 워치독 만료 대상 슬롯이 N개일 때, When 정상 동작 중이면, Then 1시간당 KIS API 호출 수가 `N × 120`회를 넘지 않는다(NFR-3 쿼터 산정).
+
+## Impacted Area
+
+- Docs:
+  - `docs/runtime-flows.md` — stop-loss·take-profit 가격 체크 흐름 추가 (REQ-042 참조)
+  - `docs/interface-contract.md` — 현재가 polling 어댑터 계약 명시 (REQ-042 참조)
+- Modules:
+  - 신규 `trex_core/adapters/broker/kis_price.py` 또는 `kis.py` 확장 — `TTTC8397R`/`VTTC8397R` 현재가 polling, `stck_prpr` 파싱
+  - `trex_core/runtime/daemon.py` — stop-loss·take-profit 가격 체크를 safety-sell worker에 통합
+  - `trex_core/domain/slot/service.py` — stop-loss·take-profit 조건 평가 메서드(또는 worker 내 인라인)
+- Tests:
+  - KIS 현재가 polling 어댑터 단위 테스트 — `stck_prpr` 파싱 확인, 실전/모의 분기 확인
+  - 가격 체크 단위 테스트(mock polling) — 손절/익절/미충족/워치독 보호 시나리오
+
+## Notes
+
+- KIS 현재가 polling 어댑터는 기존 `trex_core/adapters/broker/kis.py`에 `get_current_price(symbol)` 메서드로 추가하거나, 별도 모듈로 분리한다. batch planning에서 결정한다.
+- paper broker 모의 환경에서는 `VTTC8397R`를 사용하거나, stub 구현으로 현재가를 반환하는 방식을 batch에서 결정한다.
+- KIS 쿼터 초과 방지: 워치독 만료 슬롯 수가 임계값을 넘으면 polling 간격 자동 조정 또는 경고 로그를 구현한다. 구체적인 쿼터 수치는 KIS API 문서 기준으로 batch 설계에서 확정한다.
+- `TREX_STOP_LOSS_POLL_INTERVAL` env var는 REQ-041 참조.
+
+## Change Log
+
+### CHG-20260607-01
+
+- Date: 2026-06-07
+- Author: Justin Ko
+
+#### Change Summary
+
+- dcy-007 confirmed → REQ-038 초안 생성
+
+#### Intent
+
+- stop-loss·take-profit KIS 가격 polling + 트리거(FR-2)를 독립 Integration REQ로 정규화
+
+#### Acceptance Criteria Delta
+
+- Added: AC-1~8 전체
+
+#### Impacted Area Delta
+
+- Docs: runtime-flows.md, interface-contract.md (REQ-042에서 처리)
+- Modules: kis 현재가 polling 어댑터(신규/확장), daemon.py, service.py
+- Tests: polling 어댑터 단위 + 가격 체크 시나리오 단위 (mock)
+
+#### 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(KIS `get_current_price` TTTC8397R/VTTC8397R·`stck_prpr` 파싱 + 손절/익절/미충족/워치독 보호/쿼터 산정/가격 미수신 skip)로 AC-1~8 충족 → 구현 완료 동기화.
+
+#### 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 배포 편성.
@@ -0,0 +1,147 @@
+# req-039: 장 마감 강제 청산 (TREX_MARKET_CLOSE_LIQUIDATION_TIME)
+
+- Status: Implemented
+- Type: Integration
+- Priority: High
+- Owner: project maintainers
+
+## Intent
+
+`TREX_MARKET_CLOSE_LIQUIDATION_TIME`(HH:MM KST)이 설정된 경우, 해당 시각에 전략 모듈 활성 여부와 워치독 만료 여부에 관계없이 모든 `holding` 슬롯에 매도를 제출해 장 마감 전 자동 청산을 보장한다. 미설정 시에는 동작하지 않는다(dcy-007 FR-6).
+
+## Requirement
+
+- `TREX_MARKET_CLOSE_LIQUIDATION_TIME`(HH:MM KST 형식, optional)이 설정된 경우, 데몬은 해당 시각이 도래하면 워치독 만료 여부와 무관하게 모든 `holding` 슬롯에 `SlotService.sell()`(REQ-036)을 통해 매도를 제출해야 한다.
+- `TREX_MARKET_CLOSE_LIQUIDATION_TIME`이 설정되지 않은 경우 이 기능은 동작하지 않는다.
+- 장 마감 청산은 같은 거래일에 한 번만 발동해야 한다(중복 발동 방지).
+- 청산 대상은 발동 시각의 `holding` 슬롯 전체이며 워치독 상태를 조건으로 사용하지 않는다.
+
+## Acceptance Criteria
+
+1. Given `TREX_MARKET_CLOSE_LIQUIDATION_TIME=15:10`이고 `holding` 슬롯이 N개 있을 때, When KST 15:10이 도래하면, Then N개 슬롯 모두에 `SlotService.sell()`이 호출된다.
+2. Given `TREX_MARKET_CLOSE_LIQUIDATION_TIME=15:10`이고 워치독 **활성** 슬롯이 포함되어 있을 때, When KST 15:10이 도래하면, Then 워치독 활성 슬롯도 청산 대상에 포함된다(워치독 무관).
+3. Given `TREX_MARKET_CLOSE_LIQUIDATION_TIME`이 설정되지 않았을 때, When 어느 시각이든, Then 장 마감 청산 루프가 매도를 제출하지 않는다.
+4. Given 장 마감 청산이 같은 거래일 내에 이미 발동된 적이 있을 때, When 같은 거래일 내 청산 로직이 다시 평가되면, Then 중복 발동이 발생하지 않는다.
+5. Given 이미 `pending_sell` 상태인 슬롯 S가 청산 대상에 포함될 때, When 장 마감 청산이 발동되면, Then S에 대한 중복 `sell()` 호출이 발생하지 않는다(REQ-036 idempotency).
+6. Given grace period(REQ-034) 중에 `TREX_MARKET_CLOSE_LIQUIDATION_TIME`이 도래할 때, When 장 마감 청산이 발동되면, Then grace period 여부와 무관하게 청산이 실행된다(FR-6: 워치독 무관).
+
+## Impacted Area
+
+- Docs:
+  - `docs/runtime-flows.md` — 장 마감 강제 청산 흐름 추가 (REQ-042 참조)
+- Modules:
+  - `trex_core/runtime/daemon.py` — safety-sell worker 내 장 마감 청산 로직 추가
+  - `trex_core/runtime/config.py` — `TREX_MARKET_CLOSE_LIQUIDATION_TIME` 파싱 (REQ-041 참조)
+- Tests:
+  - 장 마감 청산 단위 테스트(시각 mock) — 설정/미설정 분기, 전체 holding 청산 확인
+  - 중복 발동 방지 테스트
+  - grace period 무관 동작 테스트
+
+## Notes
+
+- 장 마감 청산 발동은 safety-sell worker 루프(`trex-safety-sell`)에서 KST 시각을 주기적으로 체크하는 방식으로 구현한다. 발동 여부는 in-memory `last_liquidation_date`로 추적한다.
+- 발동 시각 정밀도는 worker 루프 주기에 의존한다. `TREX_FORCED_CLOSE_CHECK_INTERVAL` 또는 별도 설정으로 루프 주기를 결정한다. batch에서 확정한다.
+- `TREX_MARKET_CLOSE_LIQUIDATION_TIME` env var는 REQ-041 참조.
+
+## Change Log
+
+### CHG-20260607-01
+
+- Date: 2026-06-07
+- Author: Justin Ko
+
+#### Change Summary
+
+- dcy-007 confirmed → REQ-039 초안 생성
+
+#### Intent
+
+- 장 마감 강제 청산(FR-6)을 독립 Integration REQ로 정규화
+
+#### Acceptance Criteria Delta
+
+- Added: AC-1~6 전체
+
+#### Impacted Area Delta
+
+- Docs: runtime-flows.md (REQ-042에서 처리)
+- Modules: daemon.py (safety-sell worker 확장), config.py
+- Tests: 단위 테스트 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(시각 도래 전체 holding 청산·워치독 무관·미설정 무동작·거래일 1회 가드·grace 무관·발동 전 무동작)로 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 배포 편성.