# BAT-062 Design

- Status: confirmed
- Batch: BAT-062

## Architecture Summary

- `trex_core.domain.capital_allocation`은 외부 상태를 읽지 않는 순수 정책이다.
- 호출 계층이 계좌 가용 현금과 후보별 보호 한 주 가격을 준비하고, 정책은 후보별 배정액과 제외 사유를 반환한다.
- 전략 조립 계층은 이 배정액으로 최종 정수 주문수량을 계산하며, 기존 Core 주문 실행과 Portfolio Hub 원장은 그대로 유지한다.

## Changed Areas

- Docs: `docs/project-structure.md`, Discovery·REQ·BAT 문서
- Modules: `trex_core/domain/capital_allocation.py`, 로컬 KIS 어댑터 연결부
- Interfaces: `CapitalCandidate`, `CapitalAllocation`, `CapitalAllocationPlan`, `protected_share_cost`, `plan_liquid_capital`, `allocate_liquid_slots`

## Key Decisions

1. 공통 계산은 Core가 소유하지만 브로커 현금·호가 조회와 실제 주문수량 산출은 소유하지 않는다.
2. 한 주 유동 여유는 가장 싼 보호 한 주 가격 단위로 제한한다.
3. 최악 활성 슬롯 조합을 먼저 만족시킨 뒤 최대 공통 배정액을 이분 탐색한다.
4. 제외와 현금 없음은 0원만 반환하지 않고 안정적인 사유를 함께 반환한다.
5. 기존 어댑터 호출부는 `portfolio_id → 배정액` 호환 표면으로 단계적으로 전환한다.

## Edge Cases

- 현금 0: 전 후보 `no_available_cash`.
- 빈 후보·음수 현금·0 이하 슬롯·중복 식별자·0 이하 보호가격: 명시적 예외.
- 적격 후보가 슬롯보다 적음: 실제 적격 수만 활성 조합에 포함.
- 동가 최고 후보 제외: 입력 순서의 뒤 후보를 먼저 제외해 기존 공식과 결정성을 보존.
- 후보가 모두 제외됨: 사유를 보존한 0원 계획.

## Architecture Impact

- project-structure

## Reference Doc Update Plan

- project-structure.md: 새 순수 도메인 모듈, 책임, 의존 방향, 테스트 경로를 추가한다.
- runtime-flows.md: 런타임·주문 흐름 변경이 없어 갱신하지 않는다.

## 비설계 대상

- `BrokerPort` 현금 조회 확장
- `BuyIntent` 또는 메시지 계약 변경
- Portfolio Hub API·원장 변경
- 실전 배포·주문 활성화