docs(release): REL-003 통합 confirmed — BAT-010~013 (safety-sell + kill-switch + multi-instance)

REL-003/004/005를 단일 app-service 릴리즈로 통합(사용자 결정). REL-003에 BAT-010·011(dcy-007 safety-sell) + BAT-012(dcy-008 kill-switch) + BAT-013(dcy-009 multi-instance)를 묶고 rename, REL-004/005 draft 폐기. - 파일 rename: rel-003 core-autonomous-safety-sell → safety-killswitch-multi-instance - Scope/Rollout/Rollback/Verification 통합 (⚠️ --config 필수화 파괴적 기동 변경 + 제어 큐 pause.req→control.req + 마이그레이션 004/005 + LIVE safety-sell/kill_switch 안전 주의) - confirm-release: draft → confirmed (단위 271 + 인프라 게이트 301 passed + 전 e2e PASS) - releases/index: REL-003 통합 행, REL-004/005 제거 배포 핸드오프 가능 상태(confirmed). 운영자는 commit SHA + REL-003 Rollout Plan으로 배포. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
2026-06-07 15:45:01 +09:00
parent 9f83c64a40
commit cb288c24c2
3 changed files with 112 additions and 107 deletions
@@ -10,4 +10,4 @@
 | --- | --- | --- | --- | --- | --- |
 | REL-001 | app-service | feedback-captured | BAT-001~008 | Discovery: orb-v1 전략 모듈, 부분 매도(#5) / Change-req: REQ-030 옵션 D, 전략 필드 실데이터, 이벤트 publisher idle 견고성, paper execution_id Redis(#4) | [rel-001](rel-001_20260606_trex-core-slot-core-baseline.md) |
 | REL-002 | tooling | released | BAT-009 | Change-req: paper execution_id Redis(#4) | [rel-002](rel-002_20260606_paper-broker-env-tuning.md) |
-| REL-003 | app-service | confirmed | BAT-010, BAT-011 | dcy-007 (core 자율 안전 매도: watchdog·stop-loss·take-profit·forced_close·장 마감·update_thresholds RPC) | [rel-003](rel-003_20260607_core-autonomous-safety-sell.md) |
+| REL-003 | app-service | confirmed | BAT-010, BAT-011, BAT-012, BAT-013 | dcy-007 (자율 안전 매도) + dcy-008 (kill-switch) + dcy-009 (다중 인스턴스 토폴로지) — 통합 릴리즈 | [rel-003](rel-003_20260607_safety-killswitch-multi-instance.md) |
@@ -1,106 +0,0 @@
-# REL-003: core 자율 안전 매도 (watchdog + 가격 임계값 + forced_close / stop-loss·take-profit / 장 마감 청산 + update_thresholds RPC)
-
- Status: confirmed
- Profile: app-service
- Included Batch: BAT-010, BAT-011
-
-## Scope
- Included:
-  - BAT-010 (REQ-034, REQ-035, REQ-036, REQ-041): safety-sell 기반 인프라 — per-slot 워치독 store(snapshot RPC 가 holding 슬롯 `last_seen_at` 갱신), 슬롯 `stop_loss_price`/`take_profit_price` 도메인 필드 + `004_add_price_thresholds.sql` additive 마이그레이션, `SlotService.sell()` 자율 매도 내부 경로(idempotent), safety-sell env 5종 파싱.
-  - BAT-011 (REQ-037, REQ-038, REQ-039, REQ-040, REQ-042): safety-sell 트리거 레이어 — `trex-safety-sell` worker(7번째 스레드), forced_close_at 만기 자동 매도(REQ-037), stop-loss·take-profit KIS 현재가 polling(`TTTC8397R`/`VTTC8397R`, `stck_prpr`) + 트리거(REQ-038), 장 마감 강제 청산(`TREX_MARKET_CLOSE_LIQUIDATION_TIME`, REQ-039), `update_thresholds` intent RPC 액션(REQ-040), baseline 3문서 정합(REQ-042).
- Excluded:
-  - **REQ-030 AC-2/AC-3 (옵션 D)**: portfolio-hub#8 배포 대기로 status Approved 유지 — 본 release 범위 밖(REL-001 Excluded 와 동일 이월).
-  - 가격 임계값 논리 유효성 검증(take_profit > stop_loss 등): dcy-007/REQ-035 범위 밖.
-  - KIS 쿼터 초과 시 polling 간격 **동적 조정**: 본 release 는 상한 산정 + 경고 로그까지(REQ-038 AC-8). 동적 조정은 후속 후보.
-  - 전략 모듈(orb-v1) 자체: 별도 Discovery/배포.
-
-## Rollout Plan
-1. 사전 점검: PostgreSQL / RabbitMQ 도달성 확인. `.env` 의 broker 설정(`TREX_BROKER`, kis 시 `TREX_KIS_*` + `TREX_KIS_ALLOW_LIVE`) 확인. safety-sell env(아래)는 모두 optional — 미설정 시 기본값.
-2. DB 마이그레이션 적용: `004_add_price_thresholds.sql`(additive, `ADD COLUMN IF NOT EXISTS`). 데몬 boot `apply_migrations` 가 자동 적용하나 사전 적용 권장.
-3. 배포 대상 commit SHA(a30efa8 이상) 설치 후 데몬 재기동 → **7 워커 스레드**(execution / ledger / intent-rpc / snapshot-rpc / pause-rpc / snapshot-scheduler / **trex-safety-sell**) 기동 확인.
-4. safety-sell 튜닝 env(전부 optional):
-   - `TREX_WATCHDOG_TIMEOUT`(기본 120s), `TREX_WATCHDOG_GRACE_PERIOD`(기본 60s) — 워치독 만료/부팅 grace.
-   - `TREX_FORCED_CLOSE_CHECK_INTERVAL`(기본 60s), `TREX_STOP_LOSS_POLL_INTERVAL`(기본 30s) — worker 캐던스.
-   - `TREX_MARKET_CLOSE_LIQUIDATION_TIME`(HH:MM KST, **기본 미설정 = 장 마감 청산 OFF**).
-5. **운영 안전 주의(중요)**: `broker=kis` LIVE 에서 safety-sell worker 는 **실제 매도 주문**을 낸다.
-   - forced_close / stop-loss·take-profit 는 **워치독 만료(전략 모듈이 snapshot RPC 폴링을 멈춘) 슬롯에만** 작동한다 → `TREX_WATCHDOG_TIMEOUT` 을 전략 모듈의 정상 snapshot 폴링 주기보다 충분히 크게 설정해 정상 운용 슬롯 오발동을 방지할 것.
-   - 장 마감 청산은 설정 시 **워치독 무관 전체 holding** 을 매도하므로 의도적으로만 설정.
-   - stop-loss·take-profit·forced_close 는 해당 슬롯에 임계값/만기가 설정된 경우에만 작동(매수 intent 또는 `update_thresholds` 로 주입). 미설정 슬롯에는 무영향.
-
-## Rollback Plan
- 코드 롤백: BAT-010+011 단일 커밋(a30efa8) revert → safety-sell worker 제거(데몬 6 스레드로 회귀). 타 batch 비의존.
- 데이터: `004_add_price_thresholds.sql` 는 additive(컬럼 추가)라 데이터 파괴 없음. 롤백 시 컬럼 보존(드롭 불필요).
- 즉시 무력화(코드 롤백 없이): safety-sell 은 임계값/만기/장 마감 env 가 **설정된 경우에만** 매도한다. 임계값을 주입하지 않고 `TREX_MARKET_CLOSE_LIQUIDATION_TIME` 을 비우면 worker 는 사실상 inert. 긴급 시 데몬 정지.
- 트리거 조건 예: 정상 운용 슬롯 오발동(워치독 timeout 과소 설정), KIS 현재가 polling 쿼터 초과, 예기치 않은 청산.
-
-## Verification Checklist
- 배포 전:
-  - 단위 `pytest -q --deselect ...::test_sandbox_token_and_submit` → 236 passed / 23 skipped.
-  - 인프라 게이트(PG+RabbitMQ) `TREX_RABBITMQ_TEST_URL=... TREX_POSTGRESQL_TEST_DSN=... pytest -q` → 259 passed(마이그레이션 001~004 적용 + PG repo round-trip 포함; BAT-010 R-2 해소).
-  - `ruff check trex_core tests` → All checks passed.
-  - 실데몬 e2e(paper): RabbitMQ 매수(forced_close_at = 매수+60s) → 워치독 만료 → `holding→pending_sell(forced_close_at/trex-safety-sell)→closed` 관찰(PASS).
-  - **실 KIS LIVE 시세 검증(읽기 전용)**: `get_current_price('005930')=Decimal('329000')`(rt_cd=0, tr `FHKST01010100`). 배포 전 진단에서 REQ-038 구 tr_id(`TTTC8397R`) 결함 발견 → change-req REQ-038 CHG-04/05 로 정정·재검증 완료(REL-003 re-confirm 근거).
- 배포 후:
-  - 데몬 기동 + **7 워커 스레드**(trex-safety-sell 포함) + 큐/exchange/DLQ 선언 확인.
-  - 마이그레이션 004 적용 확인(`daily_slot` 에 `stop_loss_price`/`take_profit_price` 컬럼 존재).
-  - `update_thresholds` intent RPC: holding 슬롯 임계값 갱신 + 워치독 리셋 + non-holding `ignored` 응답.
-  - **차기 거래일 실 KIS 관찰**: stop-loss·take-profit·forced_close·장 마감 트리거 중 최소 1건 실 체결까지 확인(휴장/시장 상황 의존).
-
-## Release Execution Evidence
- Release Status Transition Target: released
-
-### Deployment Facts
- Executed At:
-  - <배포 시작 시각>
- Completed At:
-  - <배포 완료 시각>
- Environment:
-  - <배포 대상 환경>
- Operator:
-  - <배포 수행자>
- Revision or Artifact:
-  - <커밋 SHA 또는 배포 artifact 식별자 (≥ a30efa8)>
- Commands or Procedure:
-  - <실행 명령 또는 배포 절차 요약>
-
-### Profile-Specific Checks
- app-service:
-  - Health Endpoint:
-    - <HTTP health 없음(RabbitMQ transport) → 큐 declare readiness + 7 스레드 기동 확인>
-  - Startup Log Fields:
-    - <app/event/command/run_id + trex-safety-sell 스레드 기동 로그>
-  - Request Log Fields:
-    - <update_thresholds RPC correlation_id 확인>
-  - Smoke or Manual Verification:
-    - <마이그레이션 004 적용 + update_thresholds RPC + (차기 거래일) 실 KIS 트리거 관찰>
-
-### Rollback Outcome
- Rollback Required:
-  - <yes 또는 no>
- Rollback Trigger:
-  - <발생 시 원인, 없으면 none>
- Rollback Action:
-  - <수행한 조치, 없으면 none>
-
-### Release Decision Evidence
- Released Decision:
-  - <released 전환 여부>
- Rationale:
-  - <released 전환 판단 근거>
- Recorded By:
-  - <기록자>
- Recorded At:
-  - <기록 시각>
-
-## Feedback Handoff
- Observation Summary:
-  - (배포 전, 2026-06-07) 실데몬 paper e2e — RabbitMQ 매수(forced_close_at +60s) → 워치독 자연 만료 → `trex-safety-sell` 가 `holding→pending_sell(forced_close_at)` 트리거 → 집행 루프 `pending_sell→closed`. 단위 236 + 인프라 게이트 259 passed, ruff clean.
-  - (배포 전, 2026-06-07) 실 KIS LIVE 시세 검증에서 **REQ-038 tr_id 결함 포착** — 구 `TTTC8397R` 가 "없는 서비스 코드"(rt_cd=1)로 LIVE 손절/익절 silent 미발동. `FHKST01010100` 로 정정 후 `get_current_price=329000` 정상. mock/샌드박스로는 못 잡는 결함을 배포 전 LIVE 검증으로 포착(테스트 가치 입증).
- Discovery Input:
-  - <후속 discovery 후보>
- REQ Input:
-  - <후속 req 후보>
- Change Request Input:
-  - KIS 현재가 polling 쿼터 동적 조정(REQ-038 후속) — 워치독 만료 슬롯 급증 시 polling 간격 자동 확대.
-  - 가격 임계값 논리 유효성 검증(take_profit > stop_loss 등) — 신규 후보.
-  - **safety-sell 영속 거부 시 재시도 백오프/쿨다운(신규, 우선순위 ↑)**: 2026-06-07 실 KIS LIVE SL/TP e2e 에서 매도가 영속적으로 거부될 때(`장운영일자가 주문일과 상이합니다`, 휴장) safety-sell worker 가 **poll interval(5s)마다 거부 주문을 무한 재제출**함(slot 이 holding 으로 롤백 → 다음 tick 재트리거). 휴장/잔고부족/규제 등 지속 거부 상황에서 실 KIS 주문 spam + 쿼터 소모 위험. 대응 후보: 슬롯별 재시도 백오프, 거부 사유별 쿨다운, 또는 동일 사유 N회 후 일시 중단 + 경고.
@@ -0,0 +1,111 @@
+# REL-003: trex-core 통합 app-service 릴리즈 — 자율 안전 매도 + kill-switch + 다중 인스턴스 토폴로지
+
+- Status: confirmed
+- Profile: app-service
+- Included Batch: BAT-010, BAT-011, BAT-012, BAT-013
+
+> 통합 릴리즈: dcy-007(자율 안전 매도) + dcy-008(kill-switch, 구 REL-004) + dcy-009(다중 인스턴스 토폴로지, 구 REL-005)를 단일 app-service 릴리즈로 묶는다. 세 기능 모두 동일 데몬·동일 배포 대상이며 함께 배포한다. 구 REL-004/REL-005 draft 는 본 릴리즈로 통합·폐기됨. 포함 batch 가 확장됐으므로 confirm-release 재수행 필요(draft 로 되돌림).
+
+## Scope
+- Included:
+  - **BAT-010 (REQ-034/035/036/041)**: safety-sell 기반 — per-slot WatchdogStore(snapshot RPC last_seen_at 갱신), `stop_loss_price`/`take_profit_price` 도메인 필드 + `004_add_price_thresholds.sql`, `SlotService.sell()`(idempotent), safety-sell env 5종.
+  - **BAT-011 (REQ-037/038/039/040/042)**: safety-sell 트리거 — `trex-safety-sell` worker(forced_close 만기 / stop-loss·take-profit KIS 현재가 polling `FHKST01010100` / 장 마감 청산) + `update_thresholds` intent RPC + baseline 정합.
+  - **BAT-012 (REQ-043~047)**: 비상 정지/kill-switch — `trex.pause.req`→`trex.control.req` 제어 채널 + action dispatch, day-scoped `killswitch_exclusion`(`005_*.sql`) + store, 범위별 holding 즉시 청산 + 이력, 당일 제외 masking + 자동복귀 + `resume_kill_switch`, baseline 정합.
+  - **BAT-013 (REQ-048~051)**: 다중 인스턴스 토폴로지 — per-instance TOML 로더 + `--config` 필수, `instance_key` 동적 큐명(default 리터럴 하위호환), `trex.direct`(topic)/`trex.broadcast`(fanout) exchange + 바인딩, baseline 정합.
+- Excluded:
+  - REQ-030 AC-2/3(옵션 D) — portfolio-hub#8 대기(REL-001 이월).
+  - pending_buy 슬롯 롤백(dcy-008 OQ-3 Deferred), 부분 수량 청산(#5), strategy 모듈(orb-v1) publish 변경(계약만 정의), WatchdogStore Redis 외부화, 전체 env TOML 일원화.
+
+## Rollout Plan
+1. 사전 점검: PostgreSQL / RabbitMQ 도달성. 인스턴스별 TOML 준비(`instance_key`, `portfolio_hub_token`).
+2. DB 마이그레이션: `004_add_price_thresholds.sql` + `005_create_killswitch_exclusion.sql`(둘 다 additive, `IF NOT EXISTS`). 데몬 boot `apply_migrations` 자동 적용(사전 적용 권장).
+3. **⚠️ 파괴적 기동 변경(BAT-013/REQ-048)**: 데몬 기동에 `--config <path>.toml` 가 **필수**. 기존 인자 없는 배포 스크립트는 반드시 `--config` 추가(누락 시 즉시 오류 종료, fallback 없음). `portfolio_hub_token` 을 `.env`→TOML 이관 후 `.env` 에서 제거. 단일 인스턴스 유지 시 `instance_key="default"`(기존 리터럴 큐명 무회귀).
+4. **제어 큐 전환(BAT-012/REQ-043)**: `trex.pause.req`→`trex.control.req`. CLI 무영향, RPC pause 클라이언트는 `trex.control.req` 로 이전. old 큐 자연 소멸 허용(admin console 수동 삭제).
+5. 배포 대상 commit SHA(≥ 9f83c64; BAT-010~013 포함) 설치 → 데몬 재기동 → 7 워커 스레드(execution/ledger/intent-rpc/snapshot-rpc/control-rpc/snapshot-scheduler/safety-sell) + `trex.direct`/`trex.broadcast` exchange + 인스턴스 큐 선언 확인.
+6. **운영 안전 주의(중요)**:
+   - safety-sell(BAT-011): LIVE 에서 워치독 만료 슬롯에 자동 매도. `TREX_WATCHDOG_TIMEOUT` 을 전략 snapshot 폴링 주기보다 크게. 영속 거부 시 재시도 반복(후속 백오프 후보).
+   - kill_switch(BAT-012): LIVE 에서 운영자 명령 시 범위 holding 실매도. 전역 발동 의도적으로만. resume 은 매매 차단만 해제(청산 비가역).
+
+## Rollback Plan
+- 코드 롤백: 통합 단위. BAT-010~013 커밋(a30efa8/7e23648/9f83c64) revert. 단 의존 순서(010→011→012→013) 역순. **`--config` 의존이 추가됐으므로 BAT-013 롤백 시 기동 인자를 env-only 로 되돌려야 함.**
+- 데이터: `004`/`005` additive — 데이터 파괴 없음, 롤백 시 컬럼/테이블 보존.
+- exchanges/binding(trex.direct/broadcast)은 additive — 잔류 무해. default 큐명 불변.
+- 즉시 무력화: safety-sell 은 임계값/만기 미설정 슬롯엔 무영향, kill_switch 는 운영자 명령 시에만 동작. 긴급 시 데몬 정지.
+- 트리거: 정상 운용 슬롯 오발동, 의도치 않은 청산, `--config` 누락 기동 실패, 라우팅 오배달, 제어 큐 호환 문제.
+
+## Verification Checklist
+- 배포 전:
+  - 단위 `pytest -q --deselect ...::test_sandbox_token_and_submit` → **271 passed / 30 skipped**(BAT-013 시점, 누적).
+  - 인프라 게이트(PG+RabbitMQ) → **301 passed**(마이그레이션 001~005 round-trip + killswitch PG + directed 라우팅 격리 S-2 + broadcast dual S-3 + default 무회귀 S-4).
+  - `ruff check trex_core tests` → All passed.
+  - 실 KIS LIVE(읽기 전용): stop-loss/take-profit 시세 `get_current_price('005930')=329000`(tr `FHKST01010100`, BAT-011 CHG-04 정정 검증).
+  - 실데몬 e2e(paper): forced_close 청산 / 장 마감 청산 / update_thresholds RPC / kill_switch global→청산→masking→resume — 전부 PASS.
+  - 실 KIS LIVE SL/TP e2e: 시세→stop_loss 트리거→실 KIS 매도 제출→휴장 거부→롤백 PASS.
+- 배포 후:
+  - 데몬 `--config` 기동 + 7 워커 + 인스턴스 큐(`trex.*.req[.{instance_key}]`) + `trex.direct`/`trex.broadcast`/control 큐 선언.
+  - 마이그레이션 004/005 적용 확인.
+  - control RPC(pause/resume/list/kill_switch/resume_kill_switch) + update_thresholds RPC 동작.
+  - `instance_key="default"` 무회귀 + `portfolio_hub_token` TOML 주입(S-5).
+  - **차기 거래일 실 KIS**: safety-sell 트리거(SL/TP·forced_close·장 마감) + kill_switch 실매도 → 상황별 에러/체결 관찰. (다중 인스턴스 운영 시) directed 격리 + broadcast manual 확인.
+
+## Release Execution Evidence
+- Release Status Transition Target: released
+
+### Deployment Facts
+- Executed At:
+  - <배포 시작 시각>
+- Completed At:
+  - <배포 완료 시각>
+- Environment:
+  - <배포 대상 환경>
+- Operator:
+  - <배포 수행자>
+- Revision or Artifact:
+  - <커밋 SHA (≥ 9f83c64; BAT-010~013 포함)>
+- Commands or Procedure:
+  - <마이그레이션 004/005 + `trex-core-daemon --config <path>.toml` + token 이관 절차>
+
+### Profile-Specific Checks
+- app-service:
+  - Health Endpoint:
+    - <큐 declare readiness + 7 스레드 + exchange 바인딩 확인>
+  - Startup Log Fields:
+    - <app/event/command/run_id + instance_key + 7 워커(control-rpc/safety-sell 포함)>
+  - Request Log Fields:
+    - <control/intent RPC correlation_id>
+  - Smoke or Manual Verification:
+    - <마이그레이션 004/005 + control/update_thresholds RPC + (차기 거래일) 실 KIS safety-sell/kill_switch + (다중 시) 라우팅>
+
+### Rollback Outcome
+- Rollback Required:
+  - <yes 또는 no>
+- Rollback Trigger:
+  - <발생 시 원인, 없으면 none>
+- Rollback Action:
+  - <수행한 조치, 없으면 none>
+
+### Release Decision Evidence
+- Released Decision:
+  - <released 전환 여부>
+- Rationale:
+  - <판단 근거>
+- Recorded By:
+  - <기록자>
+- Recorded At:
+  - <기록 시각>
+
+## Feedback Handoff
+- Observation Summary:
+  - (배포 전, 2026-06-07) 단위 271 + 인프라 게이트 301 passed, ruff clean.
+  - safety-sell: 실데몬 paper e2e(forced_close/장 마감/update_thresholds) PASS, 실 KIS LIVE SL/TP e2e(시세→트리거→실매도→휴장 거부→롤백) PASS. tr_id 결함 LIVE 검증으로 포착·정정(CHG-04/05).
+  - kill-switch: paper control RPC e2e(kill_switch global→2 청산→masking→resume) PASS.
+  - multi-instance: 인프라 게이트 directed 격리(S-2)/broadcast dual(S-3)/default 무회귀(S-4) 실 RabbitMQ 확인.
+- Discovery Input:
+  - strategy 모듈(orb-v1) routing key 갱신(`{instance_key}.{channel_type}`) — 별도 모듈 범위.
+- REQ Input:
+  - pending_buy 슬롯 롤백(dcy-008 OQ-3 Deferred).
+- Change Request Input:
+  - safety-sell 영속 거부 재시도 백오프/쿨다운(BAT-011 LIVE e2e 발견, 우선순위↑).
+  - 제어 큐 `trex.pause.req` alias 유지 기간/제거 시점 정책.
+  - `--config` 필수화에 따른 배포 스크립트/문서 갱신.
+  - 전체 설정 TOML 일원화(KIS/DSN/RABBITMQ_URL) 후속 검토.