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
@@ -5,9 +5,9 @@
 - 문서 ID: dcy-021_20260610_position-sizing-target-intent
 - 이슈명: 포지션 사이징 — 활성 자산 슬롯 보유 수량 변경(HOLDING→HOLDING)·부분 매도·선언형 target intent (issue #1, dcy-020 OQ-4 후속)
 - 작성 시각(KST): 2026-06-10 17:06 KST
- 마지막 갱신 시각(KST): 2026-06-10 17:46 KST (draft-req: REQ-066·067 생성 + change-req REQ-057/061/062 예정)
+- 마지막 갱신 시각(KST): 2026-07-29 19:43:47 KST (후속 자본배분 정책 Discovery 참조 연결)
 - 대체됨: 없음
- 후속 Discovery 참조: 없음
+- 후속 Discovery 참조: `docs/discovery/dcy-042_20260729_shared-account-capital-allocation-policy.md`
 - 생성된 REQ 참조: REQ-066, REQ-067 (+ change-req REQ-057/061/062)

 # 1. 계획 상태 요약
@@ -0,0 +1,172 @@
+# 0. 문서 상태
+
+- 상태: confirmed
+- 문서 ID: dcy-042_20260729_shared-account-capital-allocation-policy
+- 이슈명: 메가 스윙과 탑50 스윙 공통 계좌 자본배분 정책
+- 작성 시각(KST): 2026-07-29 19:43:47 KST
+- 마지막 갱신 시각(KST): 2026-07-29 19:47:39 KST (REQ-127 생성·승인)
+- 대체됨: 없음
+- 선행 Discovery: dcy-021_20260610_position-sizing-target-intent
+- 후속 Discovery 참조: 없음
+- 생성된 REQ 참조: `docs/srs/Interface/req-127_shared-account-capital-allocation-policy.md`
+
+# 1. 계획 상태 요약
+
+- 연계 문서 현황:
+  - `dcy-021`은 전략이 최종 정수 주문수량과 가격을 계산하고 Core는 실행하는 계약을 확정했다.
+  - 로컬 KIS 어댑터에는 메가 스윙과 탑50 스윙이 공통으로 쓸 수 있는 계좌 현금 배분 계산이 존재한다.
+- 해석:
+  - 종목 가격 때문에 균등 슬롯 금액으로 한 주도 살 수 없는 후보는 제외하고, 살 수 있는 후보끼리 실제 현금을 넘지 않게 유동 배분해야 한다.
+  - 이 결정적 계산은 Core 도메인이 소유하고, KIS 어댑터는 현금·호가 조회와 설정 반영만 담당하는 편이 재사용과 검증에 적합하다.
+
+# 2. 요구사항 판정 결과
+
+- 판정: 새 Discovery 생성
+- 근거:
+  - `dcy-021`은 주문수량 계약과 실행 책임을 다루며, 계좌 후보군 전체의 현금 배분 정책은 명시적으로 범위 밖이었다.
+  - 이번 변경은 메가 스윙과 탑50 스윙의 공통 정책 소유권을 Core로 옮기는 독립 후속 반복이다.
+
+# 3. 문제점의 요약
+
+## 현재 상태
+
+- Core에는 주문·체결·슬롯 상태는 있으나, 후보 가격과 슬롯 수를 받아 계좌 현금을 안전하게 나누는 순수 도메인 정책이 없다.
+- 동일한 배분 공식이 로컬 KIS 어댑터에만 있어 다른 전략이 재사용하려면 어댑터 구현에 의존하거나 공식을 복제해야 한다.
+- Portfolio Hub는 현금·보유·손익 원장의 정본이며, 기존 `BuyIntent`는 전략이 계산한 정수 수량과 가격을 그대로 전달한다.
+
+## 기대 상태
+
+- Core가 네트워크·브로커·전략에 의존하지 않는 결정적 자본배분 정책을 제공한다.
+- 전략은 후보군과 슬롯 수를 정하고, 어댑터는 계좌 현금과 보호 호가를 입력한 뒤 Core 결과를 기존 주문수량 계산에 사용한다.
+- Portfolio Hub 원장과 기존 주문 의도 계약은 변경하지 않는다.
+
+## 이해관계자 및 제약
+
+- 운영자: 메가 스윙과 탑50 스윙을 같은 계좌 배분 원칙으로 운영한다.
+- Core 개발자: 공통 순수 정책과 불변식의 유지보수 주체다.
+- 전략·KIS 어댑터 개발자: 외부 입출력과 전략별 후보·슬롯 연결을 유지한다.
+- 실전 런타임·주문 게이트·계좌 상태는 본 반복에서 변경하지 않는다.
+- 토큰·키·계좌번호·원본 브로커 응답은 코드·문서·검증 산출물에 남기지 않는다.
+
+## 주요 사용자 시나리오
+
+1. 메가 스윙 계좌의 절반으로 고가 종목 한 주를 살 수 없으면 해당 종목을 제외하고 저가 종목에 가용 현금을 배정한다.
+2. 입금으로 고가 종목 한 주를 포함할 여력이 생기면 한 주 가격만큼 유동적으로 양보해 두 종목을 함께 운영한다.
+3. 탑50 스윙 3슬롯에서 5개 후보 중 한 주도 살 수 없는 고가 후보를 제외하고, 가능한 후보의 최악 3종 조합도 현금을 넘지 않게 배정한다.
+
+# 4. 이번에 정의할 변경
+
+1. Core에 보호된 한 주 가격과 슬롯 수를 입력받는 순수 자본배분 정책을 추가한다.
+2. 적격·제외 사유와 종목별 최대 배정액을 결정적으로 반환하고, 어떤 활성 슬롯 조합도 실제 현금을 넘지 않는 불변식을 둔다.
+3. KIS 어댑터의 중복 공식을 제거하고 현금·호가 입력과 Core 결과 매핑만 남긴다.
+
+## 영향 범위
+
+- 코드 영향:
+  - `trex_core/domain/capital_allocation.py`
+  - `tests/domain/test_capital_allocation.py`
+  - 로컬 KIS 어댑터의 호환 연결부
+- 문서 영향:
+  - `docs/project-structure.md`
+  - 신규 요구사항·배치·검증 문서
+- 운영 영향:
+  - 이번 브랜치에서는 실전 배포와 주문 활성화가 없다.
+
+# 5. 요구사항 목록
+
+## 기능 요구사항
+
+- FR-1: 보호된 한 주 가격은 현재가와 실행 여유율을 반영해 원 단위 올림으로 계산한다.
+- FR-2: 기본 슬롯 균등액보다 비싼 후보도 가장 싼 후보 한 주 가격 범위의 유동 여유 안이면 적격으로 유지한다.
+- FR-3: 적격 후보 중 최악의 활성 슬롯 조합이 현금을 넘으면 가장 비싼 후보부터 결정적으로 제외한다.
+- FR-4: 남은 후보에는 한 주 이상 살 수 있으면서 최악의 활성 슬롯 조합 합계가 가용 현금을 넘지 않는 최대 공통 배정액을 준다.
+- FR-5: 결과는 후보별 배정액과 `eligible`, `no_available_cash`, `protected_share_above_flex_limit`, `worst_case_cash_overcommit` 사유를 제공한다.
+
+## 비기능 요구사항
+
+- NFR-1: 정책은 네트워크, 환경변수, 저장소, 브로커 및 전략 코드에 의존하지 않는 순수 함수여야 한다.
+- NFR-2: 입력 순서가 같은 경우 결과가 항상 같고, 중복 식별자·음수 현금·잘못된 가격은 명시적으로 거부해야 한다.
+- NFR-3: 기존 로컬 공식과 대량 무작위 입력에서 완전 일치하고, 메가·탑50 가상 검증 결과가 바뀌지 않아야 한다.
+
+## 범위 경계
+
+- In Scope:
+  - 공통 배분 계산과 입력 검증, 제외 사유, 불변식 검증
+  - 로컬 어댑터의 얇은 연결부와 메가·탑50 가상 회귀
+- Out of Scope:
+  - Core가 브로커 현금을 직접 조회하거나 전략 후보를 선택하는 기능
+  - `BuyIntent` 수량·가격 계약, Portfolio Hub 원장, 슬롯 상태머신 변경
+  - 자동 주문수량 재조정 스케줄러, 실전 배포, 주문 게이트 변경
+
+# 6. 리스크/가정 목록
+
+## 리스크
+
+- R-1 (High): Core가 현금·호가 조회까지 소유하면 브로커와 Portfolio Hub 경계가 섞인다.
+  - 완화: Core에는 순수 계산만 두고 외부 조회는 어댑터에 남긴다.
+- R-2 (High): 기존 공식과 작은 반올림 차이가 실제 주문 가능 종목을 바꿀 수 있다.
+  - 완화: 기존 공식과 50,000개 무작위 입력 완전 일치 및 대표 경계값 회귀를 통과시킨다.
+- R-3 (Medium): 적격 후보별 배정액의 합만 비교하면 실제로 동시에 열릴 수 있는 최악 조합을 놓칠 수 있다.
+  - 완화: 슬롯 수만큼의 가장 큰 양수 배정액 합이 현금 이하인지 정책 내부와 속성 테스트에서 검증한다.
+
+## 가정
+
+- A-1: 슬롯 수와 후보군은 전략·계정 설정이 제공한다.
+- A-2: 가용 현금과 현재가는 KIS 어댑터 또는 동등한 외부 경계가 최신 값을 제공한다.
+- A-3: 최종 정수 주문수량과 가격을 담은 주문 의도는 기존 `dcy-021` 계약대로 전략 조립 계층이 만든다.
+
+## 오픈 질문
+
+- 없음. 사용자가 공통 배분을 Core에 두고 가상 검증 후 Core 브랜치로 올리는 방향을 승인했다.
+
+# 7. 초기 성공 기준
+
+- S-1: 메가 스윙 200만원·300만원 대표 사례와 탑50 3슬롯 고가종목 제외 사례가 기대 배분을 반환한다.
+- S-2: 10,000개 무작위 입력에서 최악 활성 슬롯 배정 합이 가용 현금을 초과하지 않는다.
+- S-3: 기존 어댑터 공식과 50,000개 무작위 입력의 결과가 완전히 일치한다.
+- S-4: Core 전체 회귀, 어댑터 전체 회귀, 탑50 월간 가상 원장 비교가 모두 통과한다.
+
+## 측정 방식 및 데이터 출처
+
+- S-1/S-2: `tests/domain/test_capital_allocation.py`
+- S-3: 기존 어댑터와 Core 정책의 고정 시드 비교 스크립트 출력
+- S-4: Core·docker-local 테스트 결과와 탑50 월간 가상거래 요약·거래원장·배분결정 파일
+
+# 8. REQ로 넘기기 전 확인 체크
+
+- [x] 범위와 책임 경계를 사용자 승인 및 기존 Core 계약으로 확정했다.
+- [x] 성공 기준의 측정 방식과 데이터 출처를 지정했다.
+- [x] High 리스크는 순수 도메인 경계와 완전 일치 회귀로 해소한다.
+- [x] `Open` 상태의 질문이 없다.
+- [x] Freeze 확정 담당자는 본 방향을 승인한 사용자다.
+
+# 9. 파일 처리 결과
+
+- 처리 결과: 생성
+- 생성 경로: `docs/discovery/dcy-042_20260729_shared-account-capital-allocation-policy.md`
+- 참조 문서:
+  - `docs/discovery/dcy-021_20260610_position-sizing-target-intent.md`
+  - `docs/srs/Interface/req-061_asset-keyed-intent-contract.md`
+  - `docs/project-structure.md`
+
+# 10. 사용자 결정 필요 항목 요약
+
+- 없음. 공통 정책의 Core 소유, 어댑터의 외부 입출력 소유, 가상 검증 후 Core Draft PR 순서를 사용자가 승인했다.
+
+# 11. Discovery Freeze
+
+## 섹션 참조
+
+- 범위: [# 5. 요구사항 목록 > 범위 경계](#5-요구사항-목록)
+- 리스크/오픈 질문: [# 6. 리스크/가정 목록](#6-리스크가정-목록)
+- 성공 기준: [# 7. 초기 성공 기준](#7-초기-성공-기준)
+- 인계 전 확인: [# 8. REQ로 넘기기 전 확인 체크](#8-req로-넘기기-전-확인-체크)
+- 사용자 결정 필요: [# 10. 사용자 결정 필요 항목 요약](#10-사용자-결정-필요-항목-요약)
+
+## Freeze 플래그
+
+- Handoff Decision: 승인
+- Handoff Rationale: 기존 주문수량 계약과 새 순수 정책의 책임 경계를 코드·문서로 재확인했고, 사용자 승인 범위와 충돌하는 오픈 질문이 없다.
+- Ready for REQ Drafting: true
+- Confirmed By: 형님
+- Confirmed At (KST): 2026-07-29 19:45:57 KST
@@ -45,3 +45,4 @@
 | dcy-038_20260716_cost-basis-response-contract-and-safe-sync-seeding | 20260716 | P1 — portfolio-hub cost-basis response contract 정합 및 안전한 sync 평균가 seed | [Discovery](./dcy-038_20260716_cost-basis-response-contract-and-safe-sync-seeding.md) | confirmed |
 | dcy-039_20260727_intent-venue-end-to-end-propagation | 20260727 | 전략 intent venue를 슬롯·주문·취소까지 전달 | [Discovery](./dcy-039_20260727_intent-venue-end-to-end-propagation.md) | confirmed |
 | dcy-041_20260729_broker-uncertainty-and-adapter-retirement | 20260729 | Core 브로커 불확실 상태 구분과 로컬 KIS 어댑터 축소 (#44, #45) | [Discovery](./dcy-041_20260729_broker-uncertainty-and-adapter-retirement.md) | confirmed |
+| dcy-042_20260729_shared-account-capital-allocation-policy | 20260729 | 메가 스윙과 탑50 스윙 공통 계좌 자본배분 정책 | [Discovery](./dcy-042_20260729_shared-account-capital-allocation-policy.md) | confirmed |