docs(proofline): record issue 23 specification

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

@@ -0,0 +1,46 @@
+---
+id: "req-0001"
+status: approved
+discovery: "dcy-0001"
+criteria:
+  create:
+    - "ac-0001"
+    - "ac-0002"
+    - "ac-0003"
+    - "ac-0004"
+    - "ac-0005"
+  update: []
+  retire: []
+  satisfy: []
+---
+
+# 포트폴리오 목록 응답에 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 정식 시퀀스로 구현됐다는 소급 주장을 만들지 않는다.