# BAT-035 Planning

- Status: done
- Batch: BAT-035
- Profile: standard

## Included REQ
- REQ-073: trex.slots.req RPC 계약 (Interface/High) — 큐 교체, filter/spy, 응답 slots+health only
- REQ-074: 슬롯 단일 행 스키마 (Data/High) — asset_quantity+qty+warned, cash_balance+cash_estimated, watchdog nested, paused
- REQ-075: baseline 문서 정합 (Documentation/Medium) — interface-contract/runtime-flows
- REQ-021 CHG-20260611-01: 토폴로지 큐명 snapshot→slots 교체
- REQ-034 CHG-20260611-01: watchdog 트리거=slots.req 기본/spy=무터치, 행 흡수
- REQ-063 CHG-20260611-01: CLI slots.req+spy=true, --status→filter 매핑

## Delivery Plan

### M1: 토폴로지 + 인프라 계약 교체
- `trex_core/adapters/messaging/topology.py`: SNAPSHOT_REQ_QUEUE → SLOTS_REQ_QUEUE (`"trex.slots.req"`), `snapshot_queue()` → `slots_queue()`
- `docs/interface-contract.md`: trex.snapshot.req 섹션 제거, trex.slots.req 계약(요청 {filter, spy}, 응답 {slots[], degraded/reason/message}, 필드별 정본 출처 표) 추가
- `docs/runtime-flows.md`: read 흐름 snapshot→slots 교체

### M2: messaging_handlers — slots 핸들러 신설 + snapshot 핸들러 제거
- `make_snapshot_rpc_handler` 전체 제거
- `make_slots_rpc_handler` 신설: filter(str) / spy(bool) 파싱, filter 분기 슬롯 조회, spy=false → holding watchdog 터치, 응답 {slots, degraded, reason, message} only
- `_attach_watchdog` top-level 함수 제거 (watchdog 처리가 핸들러 내부로 흡수)

### M3: portfolio — slot_to_dict 확장 + View 폐기 + snapshot envelope 제거
- `portfolio.py`: `View` enum 제거, `build_snapshot_envelope` 제거
- `slot_to_dict(s, snapshot_store=None, watchdog_store=None, pause_store=None)` 확장:
  - 슬롯/코어 정본 필드(기존 유지)
  - `asset_quantity` (snapshot_store → hub 정본) + `qty` (슬롯 미러 s.qty) + `warned` (qty≠asset_quantity)
  - `cash_balance` + `cash_estimated` (snapshot_store)
  - `watchdog: {expired: bool, last_seen: str|null}` nested (watchdog_store)
  - `paused: bool` (pause_store)

### M4: CLI — slots.req 사용 + spy=true + filter 매핑
- `trex_core/interfaces/cli.py` (또는 해당 모듈): 슬롯 조회 시 slots.req + spy=true, `--status` 인자→filter 매핑 (all/inactive/pending/holding/error, 기존 "buyable" → "inactive")

### M5: 테스트 + 회귀
- tests/adapters/messaging/: topology 단언 (SLOTS_REQ_QUEUE 존재, SNAPSHOT_REQ_QUEUE 부재)
- tests/application/: slots 핸들러 filter·spy·응답 키 집합, watchdog 터치/무터치, degraded 신호, portfolio slot_to_dict 확장 필드 + divergence + warned + cash_estimated + paused holding 직교, strategy 필드 부재
- 전체 suite green

## Dependencies
- Internal: REQ-062(hub 정본 + 슬롯 미러 정합 — 이번 배치가 그 계약을 표면에 구현), PauseStore, WatchdogStore 기존 API 재사용
- External: trex-orb-v1 lockstep 대응(배포 전 확인)

## Design Gate
- Design Required Before Implementation: **yes**
- Reason: topology.py 큐 선언 변경(REQ-021), messaging_handlers.py 핸들러 신설/제거(REQ-073), portfolio.py slot_to_dict 서명 변경 + View 폐기(REQ-074)가 상호 연결된 인터페이스 변경. 제거 지점 전수와 새 핸들러 설계 계약을 design.md에 먼저 고정해 구현 drift를 방지.

## 위험 요소
- R-1 (lockstep): trex-orb-v1 이 snapshot.req 를 아직 쓰고 있으면 배포 즉시 read 실패 → 배포 전 trex-orb-v1 의 slots.req 대응 완료 여부 확인 필수
- R-2 (slot_to_dict 서명 변경): 호출 지점이 다수(messaging_handlers + CLI + 테스트) → grep 으로 호출 지점 전수 확인 후 한 번에 교체
- R-3 (build_snapshot_envelope 제거): snapshot_store wiring path 삭제 시 CLI / daemon wiring 코드에서 잔존 참조 compile 오류 → M5 회귀로 검출

## 검증 계획 (요약)
- topology: SLOTS_REQ_QUEUE 존재, SNAPSHOT_REQ_QUEUE 부재 assert
- slots 핸들러: filter 분기(all/inactive/pending/holding/error), spy 터치/무터치, 응답 키 집합 {slots/degraded/reason/message} only, strategy 필드 부재
- slot_to_dict: asset_quantity(hub) + qty(mirror) + warned(divergence) + cash_balance + cash_estimated + watchdog:{expired,last_seen} + paused 포함
- 회귀: 전체 suite green