docs(discovery): include total value and profit metric

docs/discovery/dcy-012_20260714_manual-ledger-write-api-owner-scoped.md

@@ -109,8 +109,9 @@
 - FR-7a: `PROFIT` action은 순수 수익 실현 성격의 `profit_buffer -> 외부자금` 이동을 기록한다. 효과는 `profit_buffer -= amount`, `cash_balance`/`asset_quantity` 변화 없음으로 `WITHDRAW`와 유사하지만, 수익률 계산의 순입금액(`INVEST - WITHDRAW`)에는 포함하지 않는다.
 - FR-8: `REVERSAL`은 기존 ledger entry를 직접 수정/삭제하지 않고 target entry의 반대 effect를 새 entry로 append한다. target reference 필드/notes 정책은 REQ에서 확정한다.
 - FR-9: `QUANTITY_ADJUSTMENT`는 1차 scope에서 제외한다. split/오입력 수량 보정은 후속 Discovery/REQ 후보로 남긴다.
-- FR-10: manual ledger write 응답은 변경 후 snapshot을 포함해야 한다: 최소 `cash_balance_after`, `asset_quantity_after`, `profit_buffer_after`; `total_value_after` 포함 여부는 REQ에서 확정한다.
-- FR-11: manual ledger history 조회 API는 portfolio별 최근 ledger entries를 반환해야 한다. action, amount/quantity/price/fee/tax, note, recorded_at, after-snapshot을 trex-web이 표시할 수 있어야 한다.
+- FR-10: manual ledger write 응답은 변경 후 snapshot을 포함해야 한다: `cash_balance_after`, `asset_quantity_after`, `profit_buffer_after`, `total_value_after`. `total_value_after`는 ledger entry 기록 시점의 portfolio-hub snapshot 값이며 실시간 mark-to-market 값으로 해석하지 않는다.
+- FR-11: manual ledger history 조회 API는 portfolio별 최근 ledger entries를 반환해야 한다. action, amount/quantity/price/fee/tax, note, recorded_at, after-snapshot(`cash_balance_after`, `asset_quantity_after`, `profit_buffer_after`, `total_value_after`)을 trex-web이 표시할 수 있어야 한다.
+- FR-11a: 수익률 응답/표시를 위해 `cumulative_profit_withdrawn`을 별도 지표로 노출한다. 이 값은 `PROFIT`으로 인출한 순수 수익 실현 누적액이며, 순입금액(`sum(INVEST) - sum(WITHDRAW)`) 계산에는 포함하지 않는다.
 - FR-12: disabled portfolio write는 현행 state rule과 일관되게 거부한다.
 - FR-13: daemon-managed portfolio에 manual ledger write 시 완전 차단하지 않는다. 대신 API-level explicit confirmation을 요구한다. `managed_by_daemon_id IS NOT NULL`이고 confirmation flag가 없으면 HTTP 409 `MANUAL_WRITE_REQUIRES_CONFIRMATION`을 반환한다. trex-web은 강한 경고를 표시한 뒤 사용자 명시 확인 시 confirmation flag를 포함해 재요청한다. 허용된 write는 actor, managed_by_daemon_id, confirmation evidence를 ledger/audit metadata에 남긴다.
 - FR-14: manual endpoint는 1차 범위에서 새 음수 상태를 만드는 write를 거부한다. `BUY`는 `quantity * price + fee + tax > cash_balance`이면 HTTP 409, `SELL`은 `quantity > asset_quantity`이면 HTTP 409, `BUFFER_OUT`/`WITHDRAW`/`PROFIT`는 `amount > profit_buffer`이면 HTTP 409, `BUFFER_IN`은 `amount > cash_balance`이면 HTTP 409로 거부한다. `INVEST`는 `amount > 0`이면 허용한다.
@@ -190,8 +191,11 @@
   - REQ 세부화 항목: confirmation flag 이름, 409 error body, confirmation evidence 저장 위치(metadata JSONB vs note/context)를 확정한다.
   - 종료 조건: 완료
 - OQ-5: history response에 `total_value_after`를 포함할 것인가?
-  - 상태: Open
-  - 종료 조건: trex-web display needs and existing schema 정합성 검토
+  - 상태: Answered
+  - 결정: history response와 manual write after-snapshot에 `total_value_after`를 포함한다. `total_value_after`는 ledger entry 기록 시점의 portfolio-hub snapshot 값이며 실시간 mark-to-market 값으로 해석하지 않는다.
+  - 추가 결정: 수익률 응답/표시에서 `cumulative_profit_withdrawn`을 별도 지표로 노출한다. `cumulative_profit_withdrawn`은 `PROFIT` action 누적액이며 순입금액(`sum(INVEST) - sum(WITHDRAW)`) 계산에는 포함하지 않는다.
+  - 근거: 장부 이력에서 entry 이후 portfolio 상태를 한 번에 이해할 수 있고, `PROFIT`은 수익률 분모와 분리된 실현 수익 지표로 보여야 한다.
+  - 종료 조건: 완료
 - OQ-6: legacy `PROFIT` action은 신규 API에서 노출하지 않고 `BUFFER_IN`/`WITHDRAW`/`INVEST`로 대체할 것인가?
   - 상태: Answered
   - 결정: `PROFIT`은 legacy alias가 아니라 신규 manual API의 필수 user-facing action으로 포함한다. `WITHDRAW`와 `PROFIT`은 둘 다 `profit_buffer -> 외부자금` 방향으로 buffer를 감소시키지만, 의미와 수익률 계산 반영이 다르다.
@@ -209,7 +213,8 @@
 - S-6: Given disabled portfolio, When manual write, Then 409 또는 현행 state rule과 일관된 거부.
 - S-7: Given daemon-managed portfolio, When manual write without/with required confirmation policy, Then REQ에서 정한 경고/확인 contract가 검증된다.
 - S-8: Given existing daemon/service-token ledger trade write tests, When full test suite, Then regression 없음.
-- S-9: Given ledger history request, When entries exist, Then trex-web 표시 필드(action, amount/quantity/price/fee/tax, note, recorded_at, after-snapshot)가 반환된다.
+- S-9: Given ledger history request, When entries exist, Then trex-web 표시 필드(action, amount/quantity/price/fee/tax, note, recorded_at, after-snapshot including `total_value_after`)가 반환된다.
+- S-10: Given return/summary response, When `PROFIT` entries exist, Then `cumulative_profit_withdrawn`이 별도 지표로 반환되고 순입금액(`INVEST - WITHDRAW`) 계산에는 포함되지 않는다.
 
 ## 측정 방식 및 데이터 출처
 - portfolio-hub API tests: owner/non-owner/disabled/daemon-managed/action effect/history
@@ -223,7 +228,7 @@
 - [x] REVERSAL target/reference policy 확정(OQ-2) — `target_ledger_entry_id` 필수
 - [x] 부족 잔고/수량 validation policy 확정(OQ-3) — manual write가 새 음수 상태를 만드는 것은 1차 거부
 - [x] daemon-managed confirmation contract 확정(OQ-4) — API-level explicit confirmation 강제
-- [ ] history response fields 확정(OQ-5)
+- [x] history response fields 확정(OQ-5) — `total_value_after` 포함, `cumulative_profit_withdrawn` 별도 지표
 - [x] legacy `PROFIT` mapping policy 확정(OQ-6) — `PROFIT`은 신규 manual API 필수 action
 - [ ] Scope owner: `portfolio-hub-dev` primary, `trex-web/service-dev` consumer, `qc-reviewer` verification
 - [ ] Freeze 확정 담당자(CONFIRMED_BY) 지정
@@ -246,7 +251,7 @@
 - ~~REVERSAL target ledger id/reference 필수 여부~~ → `target_ledger_entry_id` 필수
 - ~~부족 cash/quantity 시 validation 거부 vs 결과 음수 허용~~ → manual write는 부족 cash/quantity/buffer 409 거부, read/display 음수 표시는 허용
 - ~~daemon-managed portfolio warning/confirmation을 API-level로 강제할지 UI-level로 둘지~~ → API-level explicit confirmation 강제
-- history response에 `total_value_after` 포함 여부
+- ~~history response에 `total_value_after` 포함 여부~~ → 포함. `cumulative_profit_withdrawn`도 별도 지표로 노출
 - ~~legacy `PROFIT` action 노출/매핑 정책~~ → `PROFIT`은 신규 manual API 필수 action, 순입금액(`INVEST - WITHDRAW`) 계산에는 미포함
 
 ## CONFIRM
@@ -260,7 +265,7 @@
 
 # 11. Discovery Freeze
 - Handoff Decision: 보류(draft)
-- Handoff Rationale: trex-web dcy-011의 backend-first 후속 Discovery로 생성했다. 현행 portfolio-hub 구조와 action/effect는 확인했고, 기존 `/ledger/trades` 유지 + 신규 `/ledger/manual` 추가 방향은 확정했다. 남은 결정은 history fields이다.
-- Ready for REQ Drafting: false
+- Handoff Rationale: trex-web dcy-011의 backend-first 후속 Discovery로 생성했다. 현행 portfolio-hub 구조와 action/effect는 확인했고, 기존 `/ledger/trades` 유지 + 신규 `/ledger/manual` 추가 방향은 확정했다. 주요 Open Question은 모두 해소되었고, 남은 것은 scope owner/freeze 승인이다.
+- Ready for REQ Drafting: false — 주요 OQ는 해소되었으나 confirm-discovery 승인 전
 - Confirmed By: 미정
 - Confirmed At (KST): 미정