# BAT-054: Planning

- Status: confirmed
- Batch: BAT-054
- Profile: standard

## Included REQ

- REQ-113 (Approved, 미충족 AC: AC-2 fetch→KISConfig 재조립, AC-4 break-glass 로그 assert)
- REQ-115 (Approved, 미충족 AC: AC-1 캐시 인증정보로 KIS 주문 지속)

## Scope Summary

BAT-053에서 스캐폴드로 처리된 "양의 경로(positive path)"를 완성한다.
- 그날-시작 체크포인트에서 fetch 성공 시 `BrokerCredentialPayload`로 `KISConfig`의 `app_key/app_secret/account_ref`를 재조립하고 이를 실제 `KISBroker` 인스턴스에 주입한다.
- 재조립 후 `KISBroker`는 그날 캐시된 인증정보로 장중 KIS API 호출(주문·체결 조회·토큰 갱신)을 처리한다.
- portfolio-hub 장중 장애는 이미 재조립된 KISBroker 운행에 영향을 주지 않는다.
- break-glass 로그 내용 assert 테스트를 추가한다(AC-4 보강).

## Task Breakdown

### T1: REQ-113 AC-2 — KISBroker 재조립 callback 설계 + 구현

- `SnapshotScheduler`에 `kis_reinit_callback: Optional[Callable[[BrokerCredentialPayload], None]] = None` 추가
- 그날-시작 성공 시 `_maybe_fetch_credential()`에서 callback 호출 → KISBroker 재초기화
- `daemon.py`의 `_build_broker()`에서 KIS 브로커면 callback을 조립하여 주입

### T2: REQ-115 AC-1 — KISBroker 런타임 교체 메서드

- `KISBroker`(또는 daemon.py)에 `reinitialize(credential: BrokerCredentialPayload)` 같은 메서드 제공
- 재초기화는 `app_key/app_secret/account_ref`만 교체; `base_url/timeout/allow_live`는 env 원본 유지
- KIS access token 캐시(Redis, REQ-016)는 `app_key` 변경 시 무효화 필요

### T3: REQ-113 AC-4 보강 — break-glass 로그 assert 테스트

- `tests/runtime/test_config.py` 또는 `tests/application/test_snapshot_scheduler.py`에 AC-4 로그 content 검증 케이스 추가

## Design Gate

- Design Required Before Implementation: yes
- Reason: KISBroker 재초기화 방법(메서드 추가 vs callback 교체 vs wrapper) + 재초기화 시 access token 캐시 무효화 정책이 구현 전에 명시되어야 한다. 기존 `KISBroker` 코드를 확인 후 결정.

## Dependencies

- Internal:
  - BAT-053 완료(REQ-112 `BrokerCredentialPayload`/`TradingContext` 구현, REQ-114 fail-closed 스캐폴드)
  - `adapters/broker/kis.py` (KISBroker) — reinitialize 진입점
  - `runtime/daemon.py` (`_build_broker`, SnapshotScheduler 조립)
- External:
  - 없음 (portfolio-hub 실 연동은 스텁 기반 테스트로 커버)

## Risks

- R1 (High): KISBroker 재초기화 중 진행 중인 주문 경쟁 조건 — broker 레벨 lock 또는 재초기화 안전 구간 확인 필요
- R2 (Medium): access token 캐시(Redis, REQ-016) 무효화 누락 → 구 account_ref 토큰이 신규 인증정보와 충돌
- R3 (Medium): `daemon.py`에서 callback 조립 시 `DaemonConfig.broker == 'kis'` 여부 확인 — paper broker면 callback 불필요
- R4 (Low): 테스트에서 실제 KIS API를 호출하지 않도록 mock/stub 격리 유지 — KISBroker.reinitialize()는 stub BrokerPort로 테스트