# BAT-029 Design

- Status: confirmed (D1=slot_id 계약 / D2=3자 확장 — 2026-06-10, 사용자 결정)
- Batch: BAT-029

> **D1 재정의(2026-06-10)**: 계약 키 = **slot_id**(buy·sell 공통, FR-7 재정의 / REQ-061 CHG-20260610-03). 매도는 이미 slot_id(불변); 매수가 portfolio_id→slot_id 이동(레거시 portfolio_id **dual-accept**, 폐기 BAT-δ). 아래 REQ-061 절은 slot_id 기준으로 읽는다.
> **D2 확정**: REQ-062 = reconcile 3자 확장 + A=error/B·C=warning + 청산 브로커 정본.

## 설계 목표
- intent 를 자산 키로 통일하되 외부 전략 모듈 무중단(dual-accept), 수량 정본을 hub+미러·청산을 브로커로, 코어 holding↔broker/hub 비정상 불일치를 자동 청산 없이 표면화. 운영자 slots 단일 뷰.

## REQ-061 — sell 자산 키 (dual-accept)
- `SellIntent`: `slot_id: Optional[UUID]` 로 완화 + `portfolio_id: Optional[str]` 추가. 둘 중 하나 필수.
- messaging_handlers sell 파싱: `portfolio_id` 있으면 자산 키, 없으면 `slot_id`(레거시). 둘 다 없으면 reject.
- `_admit_sell`: portfolio_id 면 `find_slot_by_portfolio(instance_key, portfolio_id)` → holding 이면 `holding→pending_sell`, 아니면 `not_holding`. slot_id 면 기존 경로(fetch_slot). 멱등(intent_id) 유지.
- CLI `exit`: 인자를 portfolio_id 로 받되 UUID 형태면 slot_id 로 해석(호환).
- **`slot_id` 폐기는 BAT-δ**(전략 모듈 portfolio_id 전환 후).

## REQ-062 — 수량 정본 + 불일치 해소
- 청산 수량 = **브로커 잔고 정본**: safety_sell/execution 의 매도 수량 조회 경로가 broker.get_balance 기반인지 확인하고, 아니면 정합(미러 stale 무관 정확).
- `reconcile_positions`(REQ-031) 확장: 기존 hub↔broker(symbol 합산) 비교에 **코어 슬롯 holding** 추가.
  - A. 코어 holding / broker 0 → 슬롯 `error`(reconcile_mismatch) + WARN. (운영자 resolve)
  - B. 코어 flat / broker 보유 → WARN/alert (운영자 결정; 자동 편입·청산 금지).
  - C. 둘 다 보유, 수량만 → 미러 갱신 + warning(기존 set_warning).
  - D. hub 만 차이 → 기존 write-back(dcy-018) 경로.
- **자동 청산/자동 편입 금지(issue #15)** — 표면화(warning/error)·운영자 게이트만.

## REQ-063 — 운영자 slots 단일 뷰
- snapshot envelope slot dict 에 `universe_detached`(retired_at not null)·`symbol`(이미 있을 수 있음) 노출.
- `trex-core slots`: 자산 포지션(slot=자산) 단일 뷰 — status·holding·universe_detached 표시. (BAT-022 slots[] 확장; 자산 중심 의미.)

## 테스트 설계
- REQ-061: sell by portfolio_id(holding→pending_sell)/not_holding/ dual-accept(slot_id 레거시)/ legacy 회귀.
- REQ-062: reconcile A(error)/B(warning)/C(미러)/D 분기 단위; 청산 수량 브로커 정본.
- REQ-063: slots 뷰 universe_detached 표시.
- 회귀: 기존 sell(slot_id)·reconcile_positions·snapshot 무파손.

## 체크포인트 결정 필요
1. **D1 — sell 계약**: dual-accept(slot_id 레거시 + portfolio_id 신규, 폐기 BAT-δ)(권장) vs hard-switch(즉시 portfolio_id 전용).
2. **D2 — REQ-062 본 배치 범위**: (i) reconcile 3자 확장 + A=error/B·C=warning + 청산 브로커 정본(권장) vs (ii) 탐지+warning 만(error/operator 라우팅은 최소).