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

# Portfolio ledger source-independent return aggregates

## Objective

Portfolio return aggregate가 producer source와 무관하게 유효한 accounting event를 반영하도록 교정하면서 gross 투자원금, 회수원금, 순투자원금과 수익 인출을 분리하고, source-independent reversal·목록/단건 일치·기존 권한 경계를 보존한다.

## Scope

- 모든 source의 유효한 `INVEST`, `WITHDRAW`, `PROFIT` row를 side별로 집계한다.
- `total_invested = Σ valid INVEST`, `total_withdrawn = Σ valid WITHDRAW`, `net_contributed_capital = total_invested - total_withdrawn`, `cumulative_profit_withdrawn = Σ valid PROFIT` 의미를 사용한다.
- `PROFIT`을 원금에서 제외하고 별도 수익 인출 합계로 유지한다.
- 동일 portfolio의 matching `REVERSAL.target_ledger_entry_id`가 존재하면 original과 reversal의 source와 무관하게 original `INVEST`·`WITHDRAW`·`PROFIT`을 제외한다.
- `buffer_out` 등 다른 side를 원금·수익 aggregate에 포함하거나 `INVEST`로 재해석하지 않는다.
- 목록은 반환 대상 ID만 하나의 grouped query로 집계하고 단건 summary는 같은 repository aggregate에 위임한다.
- Existing API field 이름과 owner/admin/service authorization 및 filter 경계를 유지한다.
- API schema, data model, runtime flow와 external interface contract를 source-independent 의미로 동기화한다.

## Constraints

- Existing ledger row mutation, migration 또는 backfill 없이 SELECT query semantic만 교정한다.
- 별도 aggregate projection/table 또는 schema migration을 추가하지 않는다.
- Credential, token, password 또는 connection string을 문서와 evidence에 기록하지 않는다.
- Production 확인은 승인된 read-only query/API pre/post check로 제한하며 별도 배포 절차가 소유한다.

### Current Implementation Assessment

- 승인 범위는 local `main` commit `5eb8c042668b1c383ac59ca9be00aa1a5dfcb37a`에 구현됐다.
- Focused repository/API/docs contract tests `39 passed`, disposable PostgreSQL 16 semantic integration `1 passed`, clean candidate full suite `661 passed, 16 skipped`, 변경 test Ruff와 `git diff --check`가 통과했다.
- 최초 독립 QC의 stale manual-only interface contract Major를 보완한 후 독립 재QC는 PASS(Blocker 0 / Major 0 / Minor 0)했다.
- exact GitHub 진행·완료 comment는 `line-0005/evidence/implementation-progress.md`와 `implementation-completion.md`에 보존한다.
- 현재 평가는 local 구현·검증·commit 완료이며 push, PR, 원격 main 반영, release, production deployment/restart와 read-only production pre/post check 완료를 주장하지 않는다.

## Non-Goals

- `buffer_out` 재분류 또는 zero-amount broker event producer 교정
- Historical ledger mutation/backfill
- API field rename 또는 breaking response change
- 별도 projection/table, migration 또는 성능 redesign
- Push, PR, 원격 main 반영, release, production deployment/restart
- Production ledger mutation 또는 배포 lifecycle closure