feat: add shared account capital allocation policy

2026-07-29 19:59:55 +09:00
parent 91e8803424
commit 91fee4808d
14 changed files with 1041 additions and 8 deletions
@@ -0,0 +1,48 @@
+# 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·원장 변경
+- 실전 배포·주문 활성화
@@ -0,0 +1,40 @@
+# BAT-062 Implementation
+
+- Status: completed
+- Batch: BAT-062
+
+## Plan Summary
+
+- 로컬 KIS 어댑터의 검증된 배분 공식을 Core 순수 도메인으로 옮기고, 어댑터는 외부 입력과 결과 매핑만 담당하도록 정리한다.
+
+## Changed Files
+
+- `trex_core/domain/capital_allocation.py`
+- `tests/domain/test_capital_allocation.py`
+- `docs/project-structure.md`
+- `docs/discovery/dcy-042_20260729_shared-account-capital-allocation-policy.md`
+- `docs/srs/Interface/req-127_shared-account-capital-allocation-policy.md`
+- `docs/batches/bat-062_20260729_shared-account-capital-allocation/*`
+- 별도 docker-local 작업트리의 `live_tools/account_capital_allocator.py`
+
+## Execution Log
+
+1. 보호 한 주 가격, 후보·배정·계좌 계획 불변 데이터 모델을 추가했다.
+2. 균등 기준, 한 주 유동 여유, 최악 활성 슬롯 제거, 최대 공통 배정액 계산을 구현했다.
+3. 입력 검증과 계획 내부 현금 불변식 검사를 추가했다.
+4. 메가·탑50 대표값, 오류 입력, 10,000건 무작위 불변식 테스트를 추가했다.
+5. 로컬 KIS 어댑터의 중복 계산을 Core 정책 호출로 대체했다.
+
+## Validation
+
+- Core 신규 테스트: 16 passed.
+- Core 전체 회귀: 849 passed, 47 skipped.
+- 기존 어댑터 공식 50,000건 완전 일치: PASS.
+- Core 연결 로컬 어댑터 전체 회귀: 161 passed, 4 skipped.
+- 탑50 월간 가상거래 요약·거래원장·배분결정 원장 완전 일치: PASS.
+- 최종 재실행 결과는 `verification.md`에 고정한다.
+
+## Remaining Risks
+
+- 이 브랜치는 실전 이미지에 반영되지 않았다. Core 병합 후 어댑터 이미지에서 모듈 가용성과 공용 가상 인증을 다시 확인해야 한다.
+- 주문수량·주문 게이트·계좌 설정 변경은 이 배치에 포함되지 않는다.
@@ -0,0 +1,29 @@
+# BAT-062: 공통 계좌 자본배분 정책
+
+- Status: release-candidate
+- Profile: standard
+- Source Discovery: dcy-042_20260729_shared-account-capital-allocation-policy
+- Source REQ: REQ-127
+- Included REQ: REQ-127
+- Excluded REQ: 없음
+
+## Scope
+
+### In Scope
+
+- Core 순수 도메인 자본배분 정책과 입력 검증
+- 메가·탑50 대표 경계값 및 무작위 불변식 테스트
+- 로컬 KIS 어댑터를 Core 호출 연결부로 축소
+- 기존 공식 완전 일치, 전체 회귀, 탑50 월간 가상 원장 비교
+- 프로젝트 구조 문서 동기화
+
+### Out of Scope
+
+- 브로커·Portfolio Hub API 또는 데이터 변경
+- 주문 의도, 슬롯 상태머신, 실전 런타임·주문 게이트 변경
+- 계좌 입금·전략 선택·주문 실행
+
+## Notes
+
+- 병렬 Core 브랜치의 BAT-059~061과 충돌하지 않도록 BAT-062를 사용한다.
+- 실전 적용은 Core 병합·이미지 검증과 별도 운영 승인 뒤에만 수행한다.
@@ -0,0 +1,47 @@
+# BAT-062 Planning
+
+- Status: confirmed
+- Batch: BAT-062
+- Profile: standard
+
+## Included REQ
+
+- REQ-127 (Approved): 공통 계좌 자본배분 순수 정책
+
+## Delivery Plan
+
+1. 기존 로컬 어댑터 공식과 Core 책임 경계를 고정한다.
+2. Core에 데이터 모델·보호가격·배분 계획·호환 결과 함수를 구현한다.
+3. 로컬 KIS 어댑터는 현금·호가 입력과 Core 결과 매핑만 남긴다.
+4. 단위·속성·완전 일치·전체 회귀·월간 가상거래를 순서대로 검증한다.
+5. 문서와 검증 증거를 동기화한 뒤 Draft PR로 제출한다.
+
+## Dependencies
+
+- Internal:
+  - Python 표준 `dataclasses`, `decimal`
+  - 기존 `dcy-021`/`REQ-061` 주문수량 계약
+- External:
+  - 검증 시 로컬 KIS 어댑터와 탑50 가상거래 도구
+  - 실전 브로커·Portfolio Hub 연결은 필요하지 않음
+
+## Design Gate
+
+- Design Required Before Implementation: yes
+- Reason: 새 공개 도메인 모듈과 프로젝트 구조 기준선이 추가되며 Core·어댑터·전략·원장 책임 경계를 구현 전에 고정해야 한다.
+
+## Milestones
+
+1. 순수 정책과 Core 단위·속성 테스트
+2. 어댑터 얇은 연결부와 기존 공식 완전 일치
+3. 전체 회귀와 메가·탑50 가상 검증
+4. 문서·품질 게이트와 Draft PR
+
+## Risks
+
+- 기존 공식과 반올림 또는 동률 제외 순서가 달라질 수 있다.
+  - 대응: 고정 시드 50,000건 결과 완전 일치.
+- Core가 외부 현금·호가 조회 책임까지 흡수할 수 있다.
+  - 대응: 새 모듈의 외부 의존을 금지하고 어댑터 연결부를 별도 검토.
+- 실제 현금보다 큰 동시 슬롯 배정이 생길 수 있다.
+  - 대응: 최악 활성 슬롯 합 불변식을 구현 내부와 10,000건 속성 테스트에서 이중 검증.
@@ -0,0 +1,62 @@
+# BAT-062 Verification
+
+- Status: confirmed
+- Batch: BAT-062
+- Verified By: delivery-runner
+
+## Acceptance Mapping
+
+| AC | 결과 | 근거 |
+| --- | --- | --- |
+| REQ-127 AC-1 | PASS | `test_mega_two_million_excludes_hynix_and_uses_samsung_lane` |
+| REQ-127 AC-2 | PASS | `test_mega_three_million_flexes_one_share_into_hynix_lane` |
+| REQ-127 AC-3 | PASS | `test_top50_three_slots_exclude_unaffordable_high_price_candidate` |
+| REQ-127 AC-4 | PASS | `test_zero_cash_fails_closed_with_explicit_reason` |
+| REQ-127 AC-5 | PASS | 잘못된 보호가격·현금·슬롯·후보·중복·유동 여유 입력 단위 테스트 |
+| REQ-127 AC-6 | PASS | 고정 시드 10,000건 최악 활성 슬롯 현금 불변식 |
+| REQ-127 AC-7 | PASS | 이전 어댑터 커밋 `46f5936`과 고정 시드 50,000건 결과 완전 일치 |
+| REQ-127 AC-8 | PASS | Core 849 passed/47 skipped, Core 연결 어댑터 161 passed/4 skipped |
+| REQ-127 AC-9 | PASS | 탑50 월간 요약 동일, `trade_ledger.csv`·`allocation_decisions.csv` 바이트 동일 |
+| REQ-127 AC-10 | PASS | Core·docker-local 격리 작업트리만 변경, 실전 런타임·주문 게이트·계좌·Hub 변경 없음 |
+
+## Evidence
+
+- Test:
+  - Core 정책: 16 passed.
+  - Core 전체: 849 passed, 47 skipped.
+  - Core 대상 Ruff: PASS.
+  - 로컬 어댑터 연결부: 11 passed.
+  - 로컬 어댑터 전체: 161 passed, 4 skipped.
+  - 기존 공식 완전 일치: 50,000 cases PASS, seed `20260729`.
+  - 탑50 월간 가상계좌: PASS, 111 signals, 71 completed trades,
+    max active 3, minimum cash 40,500원, open orders 0, positions 0,
+    duplicate orders/fills 0, restart equivalent true.
+  - 공용 가상 인증: logic→regression→virtual contract→virtual end-to-end
+    →fault injection→restart recovery→ledger reconcile 1~7단계 PASS.
+- Manual:
+  - Core는 순수 계산, 어댑터는 현금·호가, 전략은 후보·슬롯·최종 수량,
+    Portfolio Hub는 원장 정본으로 책임 경계를 대조했다.
+- Logs:
+  - 탑50 월간 최종 재실행: `/tmp/top50-core-policy-final.AhUjsm`
+  - 공용 인증:
+    `/Volumes/J_HDD/virtual_exchange/artifacts/validation/trex-top50-swing-v1/top50-core-allocation-20260729-1953-kst/run.json`
+
+## Architecture Verification
+
+- Architecture Impact: `project-structure`.
+- `docs/project-structure.md`에 새 모듈·책임·의존 규칙과 테스트 경로를 동기화했다.
+- `runtime-flows.md`는 런타임 흐름 변경이 없어 갱신 대상이 아니다.
+
+## Result
+
+- Ready for Release: true
+- Blocking Issues:
+  - 없음.
+
+## Safety Classification
+
+- `research_only=true`
+- `official_comparable=false`
+- `real_order_allowed=false`
+- `order_adapter=virtual_locked_replay`
+- 이 확인은 실전 배포·실주문·주문 게이트 활성화를 승인하지 않는다.
@@ -65,3 +65,4 @@
 | BAT-057 | standard | release-candidate | REQ-119, REQ-120, REQ-121, REQ-122 | dcy-037 | [bat-057](./bat-057_20260714_operator-broker-truth-hotfix/) |
 | BAT-058 | standard | release-candidate | REQ-123 | dcy-038 | [bat-058](./bat-058_20260716_cost-basis-safe-sync-seed/) |
 | BAT-059 | standard | release-candidate | REQ-124 | dcy-039 | [bat-059](./bat-059_20260727_intent-venue-fanin/) |
+| BAT-062 | standard | release-candidate | REQ-127 | dcy-042 | [bat-062](./bat-062_20260729_shared-account-capital-allocation/) |