# 구현 완료 — GitHub Issue #23 비정식 증적

> 이 문서는 ProofLine canonical artifact가 아니다. #23 구현 당시 GitHub 댓글을 출처와 함께 원문 보존한 비정식 증적이다.
> Source: https://github.com/fourblocks2020/portfolio-hub/issues/23#issuecomment-5275868771
> Author: `genichin`
> Created: `2026-08-13T04:13:06Z`
> Updated: `2026-08-13T04:13:06Z`

---

## 구현 완료

`feat/23-ledger-investment-aggregates` 브랜치에서 #23 구현과 로컬 검증을 완료했습니다.

### 구현 내용

- `PortfolioItem`에 다음 additive 필드를 추가했습니다.
  - `net_contributed_capital`: 유효 manual `INVEST` 합계 - 유효 manual `WITHDRAW` 합계
  - `cumulative_profit_withdrawn`: 유효 manual `PROFIT` 합계
- 목록에 반환되는 portfolio ID만 한 번에 처리하는 grouped ledger aggregate를 구현했습니다.
- manual `REVERSAL.target_ledger_entry_id`가 참조한 `INVEST`·`WITHDRAW`·`PROFIT` 원거래를 집계에서 제외했습니다.
- `REVERSAL` 자체는 금액 action으로 합산하지 않습니다.
- 기존 단건 `GET /v1/portfolios/{portfolio_id}/returns/summary`도 같은 집계 구현을 사용하도록 통일했습니다.
- 유효 ledger가 없는 portfolio는 두 신규 필드를 `0.0`으로 반환합니다.
- interface contract와 runtime flow 문서를 갱신했습니다.

### 검증 결과

HEAD 기반 clean detached worktree에 #23 변경만 적용하여 검증했습니다.

- Focused tests: **38 passed**
- 전체 회귀 테스트: **598 passed, 6 skipped**
- Python `compileall`: **통과**
- `git diff --check`: **통과**
- Ruff fatal 규칙 (`E9`, `F63`, `F7`, `F82`): **통과**
- 독립 read-only 코드 리뷰: **PASS**
  - Blocking / High / Medium finding: **없음**

### 비차단 후속 권고

- 실제 PostgreSQL integration fixture에서 `ANY(%s)` 배열 바인딩, `NUMERIC` aggregate, 실제 REVERSAL row 제외 결과를 추가 검증할 수 있습니다.
- 운영 규모 ledger를 대상으로 anti-join 실행계획을 관찰하고, 필요하면 reversal partial index를 검토할 수 있습니다.

> 현재 상태는 **로컬 구현·검증 완료**입니다. 커밋·푸시·배포·릴리스 완료를 의미하지 않습니다.