# BAT-017: 일일 거래내역 + 실현 PnL 조회 API (dcy-007 M1 fast-track)

- Status: in-delivery
- Profile: standard
- Source Discovery: dcy-007
- Included REQ: REQ-039, REQ-040, REQ-041, REQ-042
- Excluded REQ: 없음

## Summary
- dcy-007(일일 거래내역 + 실현 PnL 조회 API) 산출물 4건을 단일 batch로 묶는다.
- GET /v1/portfolios/{id}/trades (날짜/범위 필터) 엔드포인트를 신설하고(REQ-039),
  GET /v1/portfolios/{id}/pnl/realized (WAC 기반 실현 PnL 집계) 엔드포인트를 신설한다(REQ-040).
- WAC(weighted average cost) cost_basis 산출 로직을 service/domain 계층에 순수 Python으로 격리 구현해 단위 테스트가 DB 없이 가능하도록 한다(REQ-041).
- AC 기댓값 수기 대조·날짜 필터·422·R-1 경고 필드 테스트 커버리지를 확보한다(REQ-042).

## Scope
- In Scope:
  - REQ-039 (Interface): GET /v1/portfolios/{id}/trades (date 단일/from+to 범위 필터, read_token 이상 인증, 소유권 403, 404, 날짜누락 422)
  - REQ-040 (Interface): GET /v1/portfolios/{id}/pnl/realized (from+to 필수, symbol 선택, WAC 기반 실현 PnL, data_completeness_warning, cost_basis_from)
  - REQ-041 (Integration): WAC cost_basis 산출 로직 — app/domain/pnl.py 신규(순수 Python, DB 무의존, R-1 완화 경고 로직 포함)
  - REQ-042 (Testing): tests/test_wac_calculation.py, tests/test_v1_portfolios_trades.py, tests/test_v1_portfolios_pnl.py 신규
  - app/repositories/postgres.py: list_trades_by_date, get_all_trades_for_pnl 메서드 추가
  - app/repositories/portfolio_repository.py: abstract method 추가
  - app/schemas/v1.py: TradeHistoryItem, TradeHistoryResponse, RealizedPnlItem, RealizedPnlResponse 스키마 추가
- Out of Scope:
  - 미실현 PnL(현재가 연동) — dcy-007 OQ-2 Out of Scope
  - 전체 portfolio 집계 PnL 뷰 — dcy-007 OQ-2 Out of Scope
  - DB 마이그레이션 — 기존 portfolio_ledger 스키마로 조회 가능
  - 페이지네이션 — 이번 범위 외 이연
  - 성능 테스트(p95 500ms) — 통합/성능 테스트 환경에서 별도 검증

## Documents
- Planning: [planning.md](./planning.md)
- Design: [design.md](./design.md)
- Implementation: [implementation.md](./implementation.md)
- Verification: [verification.md](./verification.md)

## Notes
- 6/22 적용 M1 fast-track — 단일 batch, 단일 구현 주기.
- DB 마이그레이션 불필요(기존 portfolio_ledger 스키마).
- 구현 순서: REQ-041(WAC 도메인 로직) → REQ-039/040(API 계층) → REQ-042(테스트).
- WAC 기댓값 199,300 검증: buy 100주@10,000 + buy 100주@12,000 → sell 50주@15,000 fee=500 tax=200.