portfolio-hub/.proofline/lines/line-0001/req-0001.md

id, status, discovery, criteria

id	status	discovery	criteria
req-0001	approved	dcy-0001	create update retire satisfy ac-0001 ac-0002 ac-0003 ac-0004 ac-0005

포트폴리오 목록 응답에 ledger 기반 투자금 집계 추가

Objective

GET /v1/portfolios가 소비자 측 N+1 단건 조회나 ledger 재해석 없이 포트폴리오별 순투자현금과 누적 수익 인출액을 제공하도록 하고, 그 값이 기존 단건 returns summary와 동일한 유효 manual ledger 의미를 유지하게 한다.

Scope

• PortfolioItem에 net_contributed_capital과 cumulative_profit_withdrawn을 additive 필드로 제공한다.
• manual INVEST, WITHDRAW, PROFIT과 이를 취소하는 REVERSAL을 기준으로 현재 유효한 원거래만 집계한다.
• 여러 portfolio ID를 하나의 grouped aggregate 경로에서 처리하고 목록의 가시성·필터가 확정한 반환 대상에만 결과를 결합한다.
• 기존 단건 returns/summary와 목록이 동일한 repository 집계 의미를 사용한다.
• API/interface 문서와 회귀 테스트가 필드 의미, 기본값, 격리, 성능 경계 및 기존 동작 보존을 표현한다.

Constraints

• net_contributed_capital은 유효 INVEST - WITHDRAW, cumulative_profit_withdrawn은 유효 PROFIT이며 두 의미를 합치지 않는다.
• REVERSAL이 참조한 원거래는 제외하고 REVERSAL 자체는 금액 action으로 합산하지 않는다.
• ledger가 없거나 집계 결과가 없는 portfolio의 신규 필드는 0.0이다.
• 기존 필드·권한·필터·이중 reversal 거부 계약은 유지한다.
• portfolio-hub가 ledger 권위 값을 제공하며 소비자는 이를 재계산하지 않는다.
• 이 승인된 사양은 이미 main에 존재하는 #23 구현 의미를 정확히 기술하지만, 사후 문서화 자체가 정식 ProofLine 구현 시퀀스 또는 delivery closure를 소급 생성하지 않는다.

Non-Goals

• trex-web 저장소의 UI 구현을 변경하지 않는다.
• 배포, 운영 반영, 릴리스 승인 또는 실제 운영 데이터 변경을 승인하지 않는다.
• PROFIT을 매매상 실현손익 전체로 재정의하지 않는다.
• 단순 역사 누계를 기존 두 필드의 의미로 대체하지 않는다.
• ProofLine 정식 시퀀스로 구현됐다는 소급 주장을 만들지 않는다.