feat: add kill-switch control flow

docs/batches/bat-012_20260607_kill-switch-control/planning.md

@@ -0,0 +1,52 @@
+# BAT-012 Planning
+
+- Status: confirmed
+- Batch: BAT-012
+- Profile: standard
+
+## Included REQ
+- REQ-043 (Interface): `trex.pause.req` → `trex.control.req` 제어 채널 + `action` dispatch. pause/resume/list 회귀 보존 + kill_switch/resume_kill_switch 라우팅. unknown action error. 워커 스레드 수 불변(pause→control 교체).
+- REQ-044 (Data): `killswitch_exclusion(portfolio_id, trading_date, actor, created_at)` 테이블 + `005_*.sql` additive 마이그레이션 + `PostgreSQLKillSwitchStore`(exclude/clear/list_excluded(day)). 전역 sentinel.
+- REQ-045 (Interface): kill_switch handler — payload `{action, scope, portfolio_id?}` → 범위별 holding 순차 `SlotService.sell(actor="kill-switch", reason="emergency_stop")` + REQ-036 idempotency + 당일 제외 표시(044) + 발동 이력 로깅 + 응답 `{liquidated:N}`.
+- REQ-046 (Interface): snapshot masking 소스에 `list_excluded(today)` 추가(portfolio/전역) + day-scoped 자동 복귀 + `resume_kill_switch` handler(`clear`) — 청산된 슬롯은 비가역.
+- REQ-047 (Documentation): interface-contract(제어 채널+action+payload), runtime-flows(발동/masking/복귀/resume 흐름), project-structure(control consumer + killswitch_exclusion + store + 005 sql) 정합.
+
+## Delivery Plan
+1. REQ-044: 마이그레이션 `005_create_killswitch_exclusion.sql` + `PostgreSQLKillSwitchStore` + 단위/PG 게이트 테스트(day-scoped/멱등/전역 sentinel).
+2. REQ-043: `topology.CONTROL_REQ_QUEUE` + `make_control_rpc_handler`(action dispatch, pause/resume/list 위임 + kill_switch/resume_kill_switch 라우팅) + `daemon.py` pause consumer→control consumer 교체. dispatch 단위 테스트(회귀 + 라우팅 + unknown).
+3. REQ-045: kill_switch handler + 범위별 holding 조회·순차 sell() 진입점(application service 또는 service 헬퍼) + 044 store exclude 호출 + 이력 로깅. 단위 테스트(전역/portfolio/idempotency/portfolio_id 누락/이력/독립성/지연).
+4. REQ-046: snapshot envelope masking 확장(`killswitch_today`) + resume_kill_switch handler(clear) + day-scoped 자동복귀. 단위 테스트(masking/추가매수거부/자동복귀(날짜 mock)/재시작 영속/resume).
+5. REQ-047: baseline 3문서 정합(구현 완료 상태 반영).
+6. 전체 회귀 + ruff + 인프라 게이트(PG: 005 round-trip, RabbitMQ: control RPC) + e2e(발동→청산→masking→resume).
+
+## Dependencies
+- Internal:
+  - REQ-036/BAT-010 `SlotService.sell()` — kill_switch 청산 경로(재사용).
+  - REQ-032/BAT-008 `PostgreSQLPauseStore` + pause masking 패턴(`portfolio.py`) — masking 합성 참조(분리 유지).
+  - REQ-022/BAT-007 `make_*_rpc_handler` + consume_rpc_forever — control consumer 전환 대상.
+  - BAT-008 snapshot envelope builder — masking 소스 확장 지점.
+- External:
+  - 없음 (kill_switch 청산은 기존 broker 경로 사용; 신규 외부 API 없음).
+
+## Design Gate
+- Design Required Before Implementation: yes
+- Reason: (a) **제어 채널 전환**(`trex.pause.req`→`trex.control.req`) 은 인터페이스·daemon consumer 구조 변경이며 기존 pause 클라이언트 하위호환(별칭 vs 단일화) 결정이 design 에서 필요하다. (b) **day-scoped store 의 전역 sentinel 표현**과 masking 합성 계약(REQ-044↔046) 을 설계에서 고정해야 구현 drift 가 없다. (c) **kill_switch 실행 진입점 배치**(domain service vs application service)와 발동 이력/순차 처리 모델, dcy-007 safety-sell 과의 독립성 보장을 설계에서 명시해야 한다. → `design.md` 동일 턴 scaffold.
+
+## Milestones
+1. M1 — REQ-044 store + 마이그레이션 + 단위/PG 테스트 green
+2. M2 — REQ-043 control 채널 + dispatch + pause/resume/list 회귀 green
+3. M3 — REQ-045 kill_switch 실행 + idempotency + 이력 단위 green
+4. M4 — REQ-046 masking + 자동복귀 + resume 단위 green
+5. M5 — REQ-047 baseline 3문서 정합
+6. M6 — 전체 회귀 + ruff + 인프라 게이트 + e2e(발동→청산→masking→resume)
+
+## Risks
+- R-1 (Medium): 제어 큐 rename(`pause.req`→`control.req`) 하위호환 — 기존 RPC pause 클라이언트 영향. 대응: design 에서 별칭 유지 vs 단일화 결정, release rollout 에 명시. CLI pause/resume 는 store 직접 호출이라 무영향.
+- R-2 (Medium): kill_switch 다수 슬롯 순차 sell() 큐 부하(dcy-008 R-1). 대응: sell()=PENDING_SELL 전이(DB write 1회) 빠름, N<10 가정(NFR-1).
+- R-3 (Low): day-scoped 전역 sentinel 표현 불일치(044 store ↔ 046 masking). 대응: design 에서 계약 고정 + 단위 테스트.
+- R-4 (Low): kill_switch ↔ 자율 안전 매도(dcy-007) 동시 sell() 중복. 대응: REQ-036 idempotency(PENDING_SELL 중복 무시).
+- R-5 (Low): `005_*.sql` 실 PG round-trip(BAT-010 R-2 선례). 대응: verification 인프라 게이트에서 확인.
+
+## Notes
+- pending_buy 슬롯 처리(OQ-3)는 본 batch 범위 밖(HOLDING 한정). 필요 시 후속 REQ/change-req.
+- 제어 큐 호환 최종 결정은 release(REL) 단계 rollout 에서 확정(REQ-043 Notes).