trex-core/docs/batches/bat-062_20260729_shared-account-capital-allocation/design.md

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·원장 변경
• 실전 배포·주문 활성화