feat(safety-sell): dcy-010 BAT-014 — 영속 거부 재시도 쿨다운 (REQ-052~054)

dcy-010(safety-sell 영속 거부 재시도 백오프) 전체 SDLC: draft-req → confirm-req → draft-batch(BAT-014 batch-lite) → run-batch-delivery → confirm-req-implemented. 2026-06-07 실 KIS LIVE SL/TP e2e에서 발견한 KIS 주문 spam 위험(영속 거부 시 매도 무한 재제출) 차단. - REQ-052 (Integration): SafetySellService per-slot 인메모리 쿨다운 (_in_cooldown/_attempt_sell/_prune_cooldown) — forced_close·stop-loss·take-profit 트리거에 min_retry_interval_sec(600s) 이내 재시도 skip(가격 poll 포함) + max_retry_warn_count(3) 도달 시 WARNING + holding 이탈 정리. market_close 제외. - REQ-053 (Configuration): SafetySellConfig min_retry_interval_sec/max_retry_warn_count + TREX_SAFETY_SELL_MIN_RETRY_INTERVAL/MAX_RETRY_WARN_COUNT env (additive) - REQ-054 (Documentation): runtime-flows 쿨다운 flow + 가격체크 tr_id(FHKST01010100) 정정 인메모리 only(DB/스레드/인터페이스 변경 없음), default 미설정 시 기존 동작 불변. 검증: 신규 8 단위(쿨다운 6 + config 2), 전체 278 passed, ruff clean. REQ-052~054 Implemented, BAT-014 release-candidate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-08 00:35:11 +09:00
parent 5eebe9c4e8
commit 565af6792c
15 changed files with 739 additions and 11 deletions
@@ -0,0 +1,30 @@
+# BAT-014 Implementation
+
+- Status: completed
+- Batch: BAT-014
+
+## Plan Summary
+- REQ-053(config 2종) → REQ-052(쿨다운 로직) → REQ-054(runtime-flows). 인메모리만, DB/스레드/인터페이스 변경 없음.
+
+## Changed Files
+- 수정:
+  - `trex_core/runtime/config.py` — `SafetySellConfig.min_retry_interval_sec`(기본 600)·`max_retry_warn_count`(기본 3) + `from_env` 파싱(`TREX_SAFETY_SELL_MIN_RETRY_INTERVAL`/`TREX_SAFETY_SELL_MAX_RETRY_WARN_COUNT`) (REQ-053)
+  - `trex_core/application/safety_sell.py` — `_last_attempt`/`_attempt_count` dict, `_in_cooldown`/`_attempt_sell`/`_prune_cooldown`, `check_forced_close`·`check_prices` 쿨다운 gate(skip→KIS poll skip 포함)·경고, `run_once` 시작 시 prune. market_close 는 미적용 (REQ-052)
+  - `docs/runtime-flows.md` — safety-sell 재시도 쿨다운 flow + 가격체크 tr_id(FHKST01010100) 정정 (REQ-054)
+  - `tests/runtime/test_safety_sell_config.py` — 쿨다운 env 기본값/파싱 2종
+  - `tests/application/test_safety_sell_worker.py` — TestRetryCooldown 6종(skip/만료 재시도/경고/prune/market_close 제외/트리거 해소)
+
+## Execution Log
+1. REQ-053 config 2종 + from_env → `test_safety_sell_config.py` green.
+2. REQ-052 쿨다운(`_in_cooldown`/`_attempt_sell`/`_prune_cooldown` + forced_close/prices gate) → TestRetryCooldown 6 green (non-transitioning sell stub 으로 영속 거부 시뮬).
+3. REQ-054 runtime-flows 쿨다운 flow 추가.
+4. 전체 회귀: 단위 278 passed / 30 skipped, ruff clean.
+
+## Validation
+- `pytest tests/application/test_safety_sell_worker.py tests/runtime/test_safety_sell_config.py` → 34 passed.
+- 전체 `pytest -q --deselect ...::test_sandbox_token_and_submit` → 278 passed / 30 skipped.
+- `ruff check trex_core tests` → All passed.
+
+## Remaining Risks
+- R-2(재시작 시 쿨다운 초기화 → 1회 즉시 재시도): 허용(문서 명시).
+- 실 운영 거부 시나리오(휴장/잔고)에서의 쿨다운 동작은 차기 거래일 실 관찰로 보강(단위는 stub 로 시뮬). 인메모리·additive 변경이라 release 위험 낮음.
@@ -0,0 +1,27 @@
+# BAT-014: safety-sell 영속 거부 재시도 쿨다운 (per-slot cooldown + 경고 + env)
+
+- Status: release-candidate
+- Profile: batch-lite
+- Source Discovery: dcy-010
+- Included REQ: REQ-052, REQ-053, REQ-054
+
+## Summary
+- dcy-010(safety-sell 영속 거부 재시도 백오프)를 batch-lite 로 delivery 한다. `SafetySellService`에 per-slot 인메모리 쿨다운(마지막 시도 시각·시도 횟수)을 추가해 영속 거부(휴장/잔고/규제) 시 `min_retry_interval_sec`(기본 600s) 이내 재시도를 건너뛰고, `max_retry_warn_count`(기본 3) 도달 시 운영자 WARNING 을 발행한다. `SafetySellConfig` env 2종 + runtime-flows 정합. **DB/스레드/인터페이스 변경 없음**(인메모리만).
+
+## Scope
+- In Scope:
+  - `SafetySellService` per-slot 쿨다운 추적(`_last_attempt`/`_attempt_count`) + skip/만료 재시도 + 경고 로그 + holding 이탈 정리, market_close 제외 (REQ-052)
+  - `SafetySellConfig` `min_retry_interval_sec`/`max_retry_warn_count` env 2종 (REQ-053)
+  - `docs/runtime-flows.md` safety-sell tick 쿨다운 단계 반영 (REQ-054)
+- Out of Scope:
+  - ExecutionService→SafetySellService 거부 사유 피드백 채널, 거부 원인별 차등 쿨다운, 쿨다운 DB 영속, 수동 해제 API, market_close 별도 쿨다운.
+
+## Documents
+- Planning: [planning.md](./planning.md)
+- Implementation: [implementation.md](./implementation.md)
+- Verification: [verification.md](./verification.md)
+
+## Notes
+- Profile **batch-lite**: 소규모(단일 service + config 2종 + 문서), 인메모리만, 구조/인터페이스/DB 변경 없음, 설계가 dcy-010 §4 에 완비 → **Design Gate: no**(design.md 불요). implementation/verification 은 해당 stage 진입 시 생성.
+- OQ-1(600s)/OQ-2(3, 경고만)/OQ-3(단일 per-slot) Answered. NFR-1(인메모리)/NFR-2(무락)/NFR-4(paper reject 시뮬 테스트) 는 REQ-052 AC 로 흡수.
+- 발견 근거: REL-003 Feedback / 2026-06-07 실 KIS LIVE SL/TP e2e.
@@ -0,0 +1,38 @@
+# BAT-014 Planning
+
+- Status: confirmed
+- Batch: BAT-014
+- Profile: batch-lite
+
+## Included REQ
+- REQ-052 (Integration): `SafetySellService` per-slot 쿨다운(`_last_attempt`/`_attempt_count`) + `_safe_sell` 전 skip / 만료 재시도 + 경고 로그 + holding 이탈 정리. market_close 제외.
+- REQ-053 (Configuration): `SafetySellConfig.min_retry_interval_sec`(env `TREX_SAFETY_SELL_MIN_RETRY_INTERVAL`, 기본 600) + `max_retry_warn_count`(env `TREX_SAFETY_SELL_MAX_RETRY_WARN_COUNT`, 기본 3).
+- REQ-054 (Documentation): `docs/runtime-flows.md` safety-sell tick 쿨다운 단계.
+
+## Delivery Plan
+1. REQ-053: `SafetySellConfig` 필드 2종 + `from_env` 파싱 → `test_safety_sell_config.py` 기본값/파싱.
+2. REQ-052: `SafetySellService.__init__` dict 2종 + `check_forced_close`/`check_prices` 쿨다운 gate(skip/update) + `attempt_count` 경고 + `run_once` holding 이탈 정리. SafetySellService 가 config 의 두 값을 사용. paper `reject_symbols` 시뮬 단위 테스트(skip/만료 재시도/경고/정리/market_close 제외/트리거 해소).
+3. REQ-054: runtime-flows 갱신.
+4. 전체 회귀 + ruff.
+
+## Dependencies
+- Internal: dcy-007/BAT-011 `SafetySellService`(변경 대상) + `SafetySellConfig`(REQ-041). paper `reject_symbols`(REQ-011/BAT-009) — 거부 시뮬.
+- External: 없음.
+
+## Design Gate
+- Design Required Before Implementation: **no**
+- Reason: 변경이 단일 service 인메모리 dict 추가 + config 2 필드 + 문서로 국소적이고, 구조/인터페이스/DB/스레드 영향이 없다(추가 스레드·스키마 없음, 단일 스레드 호출이라 무락). 쿨다운 알고리즘·기본값·트리거 적용 범위가 dcy-010 §4/§6(OQ-1/2/3 Answered)에 완비되어 설계 모호성이 없다 → batch-lite, design.md 생략.
+
+## Milestones
+1. M1 — REQ-053 config 2종 + 단위 green
+2. M2 — REQ-052 쿨다운 로직 + paper reject 시뮬 단위 green
+3. M3 — REQ-054 runtime-flows
+4. M4 — 전체 회귀 + ruff
+
+## Risks
+- R-1 (Low): 쿨다운 중 트리거 해소 시 불필요 경고 — holding 이탈 정리(FR-4) + 조건 해소 시 `_safe_sell` 미호출로 완화.
+- R-2 (Low): 재시작 시 쿨다운 초기화 → 1회 즉시 재시도 — 허용(문서 주의).
+- R-3 (Low): paper 기본은 거부 안 함 → `reject_symbols` 시뮬로 테스트 커버.
+
+## Notes
+- batch-lite: design 생략(Design Gate no). implementation.md/verification.md 는 구현/검증 stage 진입 시 생성.
@@ -0,0 +1,39 @@
+# BAT-014 Verification
+
+- Status: verified
+- Batch: BAT-014
+
+## Acceptance Mapping
+
+### REQ-052 (per-slot 쿨다운 + 경고)
+| AC | Evidence |
+|----|---------|
+| AC-1: 쿨다운 이내 재시도 skip (S-1) | `test_safety_sell_worker.py::TestRetryCooldown::test_skips_retry_within_interval` (1회만) |
+| AC-2: 쿨다운 만료 후 재시도 (S-2) | `test_retries_after_cooldown_expiry` (+601s → 2회) |
+| AC-3: max_retry_warn_count 경고 (S-3) | `test_warning_after_max_count` (caplog WARNING + slot_id) |
+| AC-4: holding 이탈 시 정리 (S-4) | `test_prune_on_non_holding` (`_last_attempt`/`_attempt_count` 제거) |
+| AC-5: market_close 미적용 | `test_market_close_not_gated_by_cooldown` (쿨다운 중에도 청산) |
+| AC-6: 트리거 해소 시 미증가 (R-1) | `test_trigger_resolved_no_increment` (sell 없음, count 없음) |
+
+### REQ-053 (쿨다운 env 2종)
+| AC | Evidence |
+|----|---------|
+| AC-1: 기본값 600/3 | `test_safety_sell_config.py::test_safety_sell_config_defaults` |
+| AC-2: env 파싱(300/5) | `test_retry_cooldown_env_tuning` |
+| AC-3: 미설정 회귀 없음 | 전체 278 passed (기존 safety-sell 동작 불변) |
+
+### REQ-054 (runtime-flows 정합)
+| AC | Evidence |
+|----|---------|
+| AC-1: 쿨다운 flow(skip/재시도/경고/정리) | `docs/runtime-flows.md` "safety-sell 재시도 쿨다운" flow |
+| AC-2: market_close 제외 명시 | 동일 flow 첫 문단 + 장 마감 flow |
+
+## Evidence
+- Test: 신규 8종(쿨다운 6 + config 2) green. 전체 단위 **278 passed / 30 skipped**, `ruff` All passed.
+- Manual: 없음(인메모리 로직 단위 커버; 영속 거부는 non-transitioning sell stub 로 시뮬 — dcy-010 NFR-4 의도).
+- Logs: `34 passed`(대상 파일) / `278 passed`(전체).
+
+## Result
+- Ready for Release: true
+- Blocking Issues:
+  - 없음. 인메모리·additive(DB/스레드/인터페이스 변경 없음), default 미설정 시 기존 동작 불변. 실 운영 거부 시나리오 관찰은 차기 거래일 보강(비차단).
@@ -21,3 +21,4 @@
 | BAT-011 | standard | release-candidate | REQ-037, REQ-038, REQ-039, REQ-040, REQ-042 | dcy-007 | [bat-011](./bat-011_20260607_safety-sell-triggers/) |
 | BAT-012 | standard | release-candidate | REQ-043, REQ-044, REQ-045, REQ-046, REQ-047 | dcy-008 | [bat-012](./bat-012_20260607_kill-switch-control/) |
 | BAT-013 | standard | release-candidate | REQ-048, REQ-049, REQ-050, REQ-051 | dcy-009 | [bat-013](./bat-013_20260607_multi-instance-topology/) |
+| BAT-014 | batch-lite | release-candidate | REQ-052, REQ-053, REQ-054 | dcy-010 | [bat-014](./bat-014_20260608_safety-sell-cooldown/) |