trex-core/docs/discovery/dcy-042_20260729_shared-account-capital-allocation-policy.md

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로 넘기기 전 확인 체크

• 범위와 책임 경계를 사용자 승인 및 기존 Core 계약으로 확정했다.
• 성공 기준의 측정 방식과 데이터 출처를 지정했다.
• High 리스크는 순수 도메인 경계와 완전 일치 회귀로 해소한다.
• Open 상태의 질문이 없다.
• 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. 요구사항 목록 > 범위 경계
• 리스크/오픈 질문: # 6. 리스크/가정 목록
• 성공 기준: # 7. 초기 성공 기준
• 인계 전 확인: # 8. REQ로 넘기기 전 확인 체크
• 사용자 결정 필요: # 10. 사용자 결정 필요 항목 요약

Freeze 플래그

• Handoff Decision: 승인
• Handoff Rationale: 기존 주문수량 계약과 새 순수 정책의 책임 경계를 코드·문서로 재확인했고, 사용자 승인 범위와 충돌하는 오픈 질문이 없다.
• Ready for REQ Drafting: true
• Confirmed By: 형님
• Confirmed At (KST): 2026-07-29 19:45:57 KST