# BAT-022 Planning

- Status: draft
- Batch: BAT-022
- Profile: standard

## Included REQ
- REQ-028 (Interface, change-req CHG-20260608-01): snapshot envelope 에 read-only per-slot `slots[]` 추가(AC-4). strategy `assets[]` 불변.
- REQ-032 (Interface, change-req CHG-20260608-03): `trex-core slots` 가 universe `assets[]` 대신 envelope `slots[]`(실제 슬롯 상태) 표시. `universe` 는 `assets[]` 유지.

## Delivery Plan
1. REQ-028(서버 envelope): `trex_core/application/portfolio.py` `build_snapshot_envelope` 에 `slots[]` 산출 추가 — `slot_repo.list_slots(day)` 로 per-slot 상태(`slot_id`/`status`/`symbol`/`qty`/`limit_price`/`avg_price`/`portfolio_id`) 매핑. 빈 배열은 `[]`. `assets[]`/meta/degraded 불변. (필요 시 `messaging_handlers.py` 핸들러 배선 확인.)
2. REQ-032(CLI): `trex_core/runtime/cli.py` `_cmd_slots` 가 `resp.get("slots", [])` 를 읽어 슬롯 상태(status 포함) 출력. `--status all|held|holding|buyable` 를 슬롯 status 기준으로 필터. watchdog-owned 표시(기존)를 `slots[]` 항목과 결합(slot 의 portfolio_id ↔ watchdog expired 매칭). `_cmd_universe` 는 `assets[]` 유지.
3. 문서: interface-contract 의 snapshot 응답에 `slots[]` 필드 계약 추가(REQ-028 Impacted). runtime-flows 필요 시 보강.
4. 테스트: envelope `slots[]` 스키마(빈 배열·status enum) + `slots` CLI 가 실제 슬롯 상태 표시(universe 와 구분) + 전체 회귀 + ruff + 인프라 게이트.

## Dependencies
- Internal:
  - dcy-005/BAT-008 snapshot envelope(REQ-028) — 확장 대상.
  - dcy-016/BAT-020 운영자 CLI `slots`(REQ-032) — 정정 대상(현재 universe 표시).
  - dcy-017/BAT-021 envelope `watchdog[]` additive 동봉 — 동일 패턴 선례 + CLI 결합 표시.
  - `SlotRepository.list_slots`/Slot 모델(`status`/`limit_price`/`avg_price`/`portfolio_id`) — slots[] 산출 소스.
- External:
  - 없음.

## Design Gate
- Design Required Before Implementation: yes
- Reason: (a) snapshot envelope 은 strict 계약(REQ-028 AC-1~3: `assets[]` null 금지·가격 제외 등)이라 `slots[]` 를 **additive top-level 필드**로 두어 기존 strategy 계약을 비파괴해야 한다 — 필드 경계·스키마를 설계에서 고정. (b) `slots[]` 항목 스키마(어떤 Slot 필드를 노출/제외할지 — 가격은 `limit_price`/`avg_price` 노출하되 strategy `assets[]` 의 no-price 규칙과 혼동 없게) 확정. (c) `slots[]`(슬롯 단위) ↔ `watchdog[]`(슬롯 단위) ↔ `assets[]`(portfolio 단위)의 키 관계(`portfolio_id`/`slot_id`)와 CLI 결합 표시 규칙 고정. (d) `--status` 필터 의미를 universe view(all/buyable/held)가 아닌 **슬롯 status(idle/holding/pending_*)** 기준으로 재정의. → design.md 동일 턴 scaffold.

## Milestones
1. M1 — REQ-028 envelope `slots[]` 산출 + 스키마 테스트 green
2. M2 — REQ-032 `slots` CLI 가 슬롯 상태 표시(+watchdog 결합), universe 와 구분
3. M3 — interface-contract `slots[]` 계약 정합
4. M4 — 전체 회귀 + ruff + 인프라 게이트

## Risks
- R-1 (Medium): `slots[]` 추가가 strict envelope(REQ-028 AC-1~3)·기존 strategy 소비자를 깨뜨림. 대응: additive top-level 필드로만 추가, `assets[]`/meta 불변, 기존 envelope 테스트 green 유지.
- R-2 (Medium): `--status` 필터 의미 변경(universe view → 슬롯 status)이 기존 `slots` 사용자 기대와 다름. 대응: design 에서 필터 매핑 명시, verification 에서 status별 케이스 검증.
- R-3 (Low): `slots[]` 와 `assets[]` 혼동(둘 다 symbol/portfolio_id 포함). 대응: CLI 출력에 슬롯 status 컬럼을 1급으로 표시, 문서에서 universe vs slots 구분 명시.

## Notes
- 1차 게이트: 전체 회귀 green(snapshot strategy 계약·슬롯 도메인 무회귀 — 노출 필드만 추가).
- `slots[]` 검증은 operator(`touch_watchdog=false`) 요청으로 비침습 확인(조회가 워치독 리셋 안 함, dcy-016).
- 가격 노출: `slots[]` 는 운영자용이라 `limit_price`/`avg_price` 노출 OK(REQ-028 AC-3 의 no-price 는 strategy `assets[]` 한정).