trex-core/docs/srs/Interface/req-127_shared-account-capital-allocation-policy.md

req-127: 공통 계좌 자본배분 순수 정책

• Status: Approved
• Type: Interface
• Priority: High
• Owner: trex-core-dev

Intent

• 메가 스윙과 탑50 스윙이 같은 계좌 현금 배분 규칙을 사용하도록, 외부 입출력과 분리된 결정적 정책을 Core 도메인에 제공한다.
• 고가 종목을 무조건 균등액으로 자르지 않고 제한된 한 주 가격 여유를 허용하되, 실제로 동시에 열릴 수 있는 최악 슬롯 조합도 가용 현금을 넘지 않게 한다.
• KIS 어댑터는 현금·호가 조회와 결과 매핑만 맡고, Portfolio Hub 원장과 기존 주문수량 계약은 변경하지 않는다.

Requirement

1. Core는 available_cash, 양의 slot_count, 고유한 portfolio_id·symbol과 양의 protected_share_cost를 가진 후보 목록, 0 이상의 flex_share_count를 입력받는 순수 자본배분 정책을 제공해야 한다.
2. 보호된 한 주 가격은 양의 price와 0 이상의 slippage_pct를 받아 price × (1 + slippage_pct/100)을 원 단위 올림해 계산해야 한다.
3. 초기 후보 적격 상한은 available_cash // slot_count + cheapest_protected_share_cost × flex_share_count여야 하며, 이를 넘는 후보는 protected_share_above_flex_limit으로 제외해야 한다.
4. 1차 적격 후보 중 가장 비싼 min(slot_count, eligible_count)개 한 주 가격 합이 가용 현금을 넘으면, 후보 가격과 입력 순서를 안정적인 동률 기준으로 가장 비싼 후보부터 제외하고 worst_case_cash_overcommit을 반환해야 한다.
5. 남은 후보에는 각 후보의 보호 한 주 가격 이상이면서, 가장 큰 min(slot_count, eligible_count)개 배정액 합이 가용 현금 이하인 최대 공통 배정액을 적용해야 한다.
6. 현금이 0이면 모든 후보의 배정액을 0으로 하고 no_available_cash를 반환해야 한다. 음수 현금, 0 이하 슬롯 수, 빈 후보, 음수 유동 여유, 중복 식별자, 0 이하 한 주 가격은 명시적으로 거부해야 한다.
7. 결과는 입력 후보 순서를 보존한 후보별 portfolio_id, symbol, 배정액, 사유와 계좌 수준 available_cash, slot_count를 제공해야 하며, 단순 portfolio_id → 배정액 호환 표면도 제공해야 한다.
8. 정책 모듈은 네트워크, 파일, 환경변수, 데이터베이스, 브로커 및 전략 모듈에 의존하지 않아야 한다. 현금·호가 조회, 후보·슬롯 선택, 설정 저장, 실제 주문수량 산출과 주문 제출은 호출 계층 책임으로 유지해야 한다.
9. 기존 BuyIntent의 정수 수량·가격 계약, Core 주문 실행, 슬롯 상태머신, Portfolio Hub 원장 계약을 변경하지 않아야 한다.
10. docs/project-structure.md와 배치 검증 문서는 공통 정책의 책임, 호출 계층 책임, 비운영 범위, 회귀 증거를 구현과 일치하게 기록해야 한다.

Acceptance Criteria

1. Given 메가 스윙 후보가 삼성전자 보호가격 220,000원과 SK하이닉스 보호가격 1,400,000원이고 현금 2,000,000원·2슬롯인 경우, When 정책을 실행하면, Then 삼성전자 2,000,000원·SK하이닉스 0원을 반환하고 SK하이닉스 제외 사유가 protected_share_above_flex_limit이다.
2. Given 같은 후보에서 현금 3,000,000원이고 SK하이닉스 보호가격이 1,510,000원인 경우, When 한 주 유동 여유를 적용하면, Then 삼성전자 1,490,000원·SK하이닉스 1,510,000원을 반환한다.
3. Given 현금 2,000,000원·3슬롯과 보호가격 100,000/200,000/500,000/700,000/1,050,000원인 탑50 후보 5개, When 정책을 실행하면, Then 마지막 후보를 제외하고 650,000/650,000/650,000/700,000/0원을 반환한다.
4. Given 현금 0원, When 정책을 실행하면, Then 모든 배정액은 0이고 사유는 no_available_cash이다.
5. Given 잘못된 가격·현금·슬롯·후보·중복 식별자 입력, When 정책을 실행하면, Then 조용한 보정 없이 ValueError로 거부한다.
6. Given 고정 시드 무작위 입력 10,000개, When 모든 결과의 가장 큰 양수 배정액을 슬롯 수만큼 합하면, Then 모든 경우 가용 현금 이하이고 양수 배정액은 해당 후보의 한 주 가격 이상이다.
7. Given 기존 로컬 어댑터 공식과 고정 시드 무작위 입력 50,000개, When 양쪽 결과를 비교하면, Then portfolio_id → 배정액 결과가 모든 경우 완전히 일치한다.
8. Given Core 전체 테스트와 로컬 어댑터 전체 테스트, When Core 정책 연결 상태로 실행하면, Then 기존 회귀와 신규 정책 테스트가 모두 통과한다.
9. Given 탑50 3슬롯 한 달 가상거래 입력, When 기존 공식과 Core 정책 연결 결과를 비교하면, Then 요약 지표와 거래원장·배분결정 원장이 동일하다.
10. Given 이 브랜치가 검토 중인 경우, When 운영 상태를 확인하면, Then 실전 런타임·주문 게이트·계좌 설정·Portfolio Hub 데이터에는 변경이 없다.

Impacted Area

• Docs:
  • docs/discovery/dcy-042_20260729_shared-account-capital-allocation-policy.md
  • docs/project-structure.md
  • 신규 배치의 계획·설계·구현·검증 문서
• Modules:
  • trex_core/domain/capital_allocation.py
  • 로컬 KIS 어댑터의 자본배분 호환 연결부
• Tests:
  • tests/domain/test_capital_allocation.py
  • 로컬 어댑터 회귀
  • 메가 대표 경계값과 탑50 월간 가상거래 비교

Notes

• Source Discovery: docs/discovery/dcy-042_20260729_shared-account-capital-allocation-policy.md.
• 기존 dcy-021과 REQ-061의 주문수량 책임은 유지한다. Core는 이 반복에서 계좌 배분의 순수 계산만 소유하며, 실제 주문 의도의 수량을 자동 수정하지 않는다.
• Portfolio Hub는 현금·보유·손익 원장의 정본으로 유지한다. 이 요구사항은 Hub API·스키마·데이터를 변경하지 않는다.
• REQ-124REQ-126과 dcy-039dcy-041, BAT-059~BAT-061은 병렬 Core 브랜치 작업에 예약되어 있어 충돌 방지를 위해 다음 미사용 번호를 선택했다.
• 구현·가상 검증·Draft PR은 허용되지만 실전 배포와 주문 활성화는 별도 승인 대상이다.

Change Log

CHG-20260729-01

• Date: 2026-07-29
• Author: delivery-runner

Change Summary

• 확정된 dcy-042의 공통 계좌 자본배분을 단일 Core 도메인 인터페이스 요구사항으로 작성했다.

Intent

• 공통 계산의 중복을 제거하면서 브로커·원장·전략 책임 경계를 유지한다.

Acceptance Criteria Delta

• Added:
  • 메가 대표 2건, 탑50 대표 1건, 입력 거부, 10,000건 불변식, 50,000건 기존 공식 완전 일치, 전체 회귀, 월간 원장 비교, 비운영 확인.
• Updated:
  • 없음.
• Removed:
  • 없음.

Impacted Area Delta

• Docs:
  • Discovery, 프로젝트 구조, 신규 배치 문서.
• Modules:
  • Core 순수 도메인 정책과 로컬 어댑터 연결부.
• Tests:
  • Core 단위·속성 회귀, 어댑터 전체 회귀, 탑50 월간 가상 비교.

Delivery Trace Delta

• Batches:
  • none.
• Releases:
  • none.

Revalidation Impact

• Reverification Needed: yes
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: 요구사항 승인 후 단일 배치에서 구현·문서·교차 검증을 완료한다.

Validation Plan

• Core 단위·전체 회귀, 기존 공식 50,000건 완전 일치, 로컬 어댑터 전체 회귀, 메가 경계값, 탑50 월간 가상 원장 비교와 공용 7단계 가상 인증을 수행한다.

CHG-20260729-02

• Date: 2026-07-29
• Author: trex-dev-lead

Change Summary

• 사용자 승인 범위, 필수 문서 필드, 측정 가능한 수락 기준과 비운영 경계를 재검토해 REQ-127을 Approved로 전환했다.

Intent

• 단일 배치의 구현·검증 기준으로 사용할 수 있도록 요구사항을 동결한다.

Acceptance Criteria Delta

• Added:
  • 없음.
• Updated:
  • 없음.
• Removed:
  • 없음.

Impacted Area Delta

• Docs:
  • SRS 상태와 인덱스 상태 동기화.
• Modules:
  • 없음.
• Tests:
  • 없음.

Delivery Trace Delta

• Batches:
  • 다음 단계에서 BAT-062 생성.
• Releases:
  • none.

Revalidation Impact

• Reverification Needed: yes
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: BAT-062에서 구현·검증 증거를 수락 기준별로 연결한다.

Validation Plan

• REQ-127 수락 기준 1~10을 배치 검증 문서와 자동화된 테스트·가상거래 증거로 대조한다.