feat: add kill-switch control flow

2026-06-07 14:00:20 +09:00
parent c912c08071
commit 7e23648489
30 changed files with 1424 additions and 51 deletions
@@ -4,7 +4,7 @@
 - Baseline Seed: .stage-pilot/bootstrap/baseline.yaml
 - Status: draft
 - Owner: project maintainers
- Last Updated (KST): 2026-06-07 (BAT-011)
+- Last Updated (KST): 2026-06-07 (BAT-012)
 - Source Discovery / Batch: bootstrap-baseline (pre-Discovery); HTTP API = dcy-002 / BAT-002
 - Primary Runtime: daemon (HTTP API) + library (slot 도메인)

@@ -28,7 +28,7 @@
 - RabbitMQ `trex.snapshot.req` :: 전략 모듈의 스냅샷 RPC (request-reply, BAT-007/BAT-008 envelope)
 - RabbitMQ `trex.intent.req` :: 전략 모듈의 매수/매도 admission RPC (request-reply, BAT-007)
 - RabbitMQ `trex.events` :: 체결/슬롯 상태 이벤트 topic exchange (pub/sub, BAT-007)
- RabbitMQ `trex.pause.req` :: pause/resume 제어 RPC (request-reply, BAT-008)
+- RabbitMQ `trex.control.req` :: 운영자 제어 RPC — pause/resume/list + kill_switch/resume_kill_switch (request-reply, BAT-012; 구 `trex.pause.req` 확장)
 - `trex-core` CLI :: pause/resume/paused 운영 명령 (BAT-008)
 - SlotService :: 슬롯 생명주기 도메인 서비스(전이/사전할당/가용성/재진입 카운트)
 - SlotRepository (Protocol) :: 도메인 ↔ 저장소 경계 계약
@@ -159,26 +159,35 @@ sell payload 는 `{"intent_type":"sell", "intent_id":..., "slot_id":..., "reason

 - 워치독 신호 (REQ-034): `trex.snapshot.req` 처리는 read-only 응답 산출에 더해, 응답에 포함된 모든 `holding` 슬롯의 워치독 `last_seen_at` 을 갱신한다. 즉 전략 모듈이 스냅샷을 폴링하는 것 자체가 해당 슬롯의 생존 신호이며, 폴링이 끊긴(워치독 만료) 슬롯만 safety-sell 트리거 대상이 된다.

-### `trex.pause.req` control RPC (BAT-008 / REQ-032)
+### `trex.control.req` 제어 RPC (BAT-012 / REQ-043, REQ-032)

-요청:
-```
-{ "action": "pause" | "resume" | "list",
-  "portfolio_id": str,                 # required for pause/resume
-  "actor":        str                  # optional, default "operator"
-}
-```
+운영자 제어 채널. `action` discriminator 로 분기한다(REQ-043). 기존 `trex.pause.req`(REQ-032)의 개념 확장이며, 단일 제어 큐 + action 패턴으로 기능마다 큐/consumer 를 늘리지 않는다.

-응답:
+action 목록: `pause` | `resume` | `list` (REQ-032) · `kill_switch` (REQ-045) · `resume_kill_switch` (REQ-046). 알 수 없는 action 은 `{status:"error", reason:"unknown_action:<a>"}`.
+
+pause/resume/list 요청·응답:
 ```
-{ "status": "ok" | "error",
-  "paused": [str, ...],                # current paused portfolio_ids (sorted)
-  "action": echo,
-  "reason": str                        # only when status="error"
-}
+{ "action": "pause" | "resume" | "list", "portfolio_id": str, "actor": str? }
+→ { "status": "ok"|"error", "paused": [str,...], "action": echo, "reason"?: str }
 ```
- pause 는 `snapshot_pause` Postgres 테이블에 upsert(actor 갱신)되어 daemon 재시작·일일 refresh 후에도 유지된다(REQ-032 AC-2).
- CLI `trex-core pause/resume/paused` 가 동일한 store 를 가리키므로 CLI ↔ RPC 가 같은 상태를 본다(REQ-032 AC-4).
+- pause 는 `snapshot_pause`(portfolio_id PK, **영구**) upsert — daemon 재시작·일일 refresh 후 유지(REQ-032 AC-2). CLI `trex-core pause/resume/paused` 가 같은 store 를 본다.
+
+kill_switch 요청·응답 (REQ-045):
+```
+{ "action": "kill_switch", "scope": "portfolio"|"global", "portfolio_id": str?, "actor": str? }
+→ { "status": "ok", "scope": echo, "portfolio_id"?: str, "liquidated": int }
+```
+- scope 범위의 모든 `holding` 슬롯을 `SlotService.sell(reason="emergency_stop")` 로 즉시 청산하고, 해당 범위를 **당일 제외**(`killswitch_exclusion`)로 표시한다. scope=portfolio 인데 portfolio_id 누락 시 `{status:error, reason:portfolio_id_required}`.
+
+resume_kill_switch 요청·응답 (REQ-046):
+```
+{ "action": "resume_kill_switch", "scope": "portfolio"|"global", "portfolio_id": str? }
+→ { "status": "ok", "scope": echo, "portfolio_id"?: str }
+```
+- 해당 범위의 **당일 제외만 해제**(`killswitch_exclusion` row 삭제)해 정상 매매로 복귀. 이미 청산(매도)된 슬롯은 되돌리지 않는다(매도 비가역).
+
+- snapshot masking 소스(REQ-046): `mask = pending | warning | pause | killswitch_today`. kill-switch 당일 제외는 `(portfolio_id, trading_date)` day-scoped — 다음 거래일 자동 복귀. `portfolio_id="*"` sentinel 은 전역(전체 universe) 마스킹.
+- 하위호환: `trex.pause.req` 는 legacy alias. 운영 배포 시 제어 클라이언트는 `trex.control.req` 로 이전한다(rollout 결정, REQ-043 Notes).

 ## Interface: `PortfolioHubReadPort` (Protocol, BAT-008)