docs(proofline): record issue 23 specification

2026-08-13 14:47:14 +09:00
parent 8dcdbdc9e0
commit 92df8e0c5a
11 changed files with 362 additions and 2 deletions
@@ -0,0 +1,44 @@
+# 구현 완료 — 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를 검토할 수 있습니다.
+
+> 현재 상태는 **로컬 구현·검증 완료**입니다. 커밋·푸시·배포·릴리스 완료를 의미하지 않습니다.