# REQ-042: 체결 내역/실현 PnL API 테스트 커버리지 (WAC 시나리오 기댓값 대조, 날짜 필터, 422)

- Status: Implemented
- Type: Testing
- Priority: High
- Owner: Justin Ko

## Intent
- REQ-039(체결 내역 조회), REQ-040(실현 PnL 집계), REQ-041(WAC 산출 로직)의 구현 산출물에 대해, WAC 시나리오 기댓값 대조·날짜 필터 경계·422 오류·R-1 경고 필드를 포함한 단위/통합 테스트를 정의한다.
- 테스트는 구현자(delivery)가 아닌 독립 QC 시점에서도 검증 가능해야 하며, AC를 충족하는 최소 evidence를 제공해야 한다(dcy-007 NFR-3, S-1, S-2).
- WAC 기댓값 수기 계산 대조(시나리오별 fixture 사용)와 날짜 필터 경계 테스트를 의무 포함한다.

## Requirement
- 아래 테스트 파일을 신규 작성해야 한다:
  - `tests/test_wac_calculation.py` — WAC 산출 로직 순수 단위 테스트(DB 불필요).
  - `tests/test_v1_portfolios_trades.py` — 체결 내역 엔드포인트 통합 테스트(TestClient).
  - `tests/test_v1_portfolios_pnl.py` — 실현 PnL 엔드포인트 통합 테스트(TestClient).
- 각 테스트 파일은 pytest 단독 실행 가능해야 한다(`pytest tests/test_wac_calculation.py` 등).
- 테스트 픽스처는 portfolio_ledger INSERT로 알려진 buy/sell 데이터를 설정하고, 수기 계산 기댓값과 API 응답을 대조해야 한다.

## Acceptance Criteria
1. Given `tests/test_wac_calculation.py` 실행, When `pytest tests/test_wac_calculation.py`, Then 다음 시나리오 모두 통과:
   - 단순 buy → sell WAC 수기 기댓값 일치(dcy-007 S-2 기준)
   - 다중 buy → 부분 sell WAC(AC-1 of REQ-041 기댓값: 199,300)
   - 빈 입력 → total_pnl=0, cost_basis_from=None
   - sell 수량 초과(running_qty=0) → data_completeness_warning 비어 있지 않음
2. Given `tests/test_v1_portfolios_trades.py` 실행, When `pytest tests/test_v1_portfolios_trades.py`, Then 다음 시나리오 모두 통과:
   - `date=YYYY-MM-DD` 단일 날짜 필터 — 해당일 건수 일치
   - `from`/`to` 범위 필터 — 경계 날짜 포함 건수 일치
   - 날짜 파라미터 누락 → HTTP 422
   - 날짜 형식 오류 → HTTP 422
   - 해당 기간 0건 → HTTP 200 + empty items
   - 비소유자 token → HTTP 403
   - 존재하지 않는 portfolio_id → HTTP 404
3. Given `tests/test_v1_portfolios_pnl.py` 실행, When `pytest tests/test_v1_portfolios_pnl.py`, Then 다음 시나리오 모두 통과:
   - buy 2회 + sell 1회 픽스처, `total_realized_pnl` 수기 기댓값 일치(REQ-040 AC-1 기댓값: 199,300)
   - `from`/`to` 파라미터 누락 → HTTP 422
   - 기간 내 매도 0건 → HTTP 200 + total_realized_pnl=0 + items=[]
   - data_completeness_warning 필드: 이력 완전 시 null, 불완전 시 비어 있지 않음(R-1 경고 반영)
   - symbol 필터 적용 — 해당 symbol 매도만 집계
   - 비소유자 token → HTTP 403
4. Given 3개 테스트 파일 전체 실행, When `pytest tests/test_wac_calculation.py tests/test_v1_portfolios_trades.py tests/test_v1_portfolios_pnl.py -v`, Then 전체 PASSED(0 failed) + 각 파일 실행 결과 출력 존재.
5. Given `tests/test_wac_calculation.py`, When DB 컨테이너 없이 실행(`PORTFOLIOHUB_DB_ENABLED` 미설정 환경), Then WAC 단위 테스트가 통과(DB 격리 확인, REQ-041 AC-8 연동).
6. Given REQ-039~041 구현 후 기존 테스트 스위트(`pytest` 전체) 실행, When 실행, Then 기존 통과 테스트가 모두 계속 통과(회귀 없음).

## Impacted Area
- Docs:
  - 없음 (테스트 파일만 추가)
- Modules:
  - 없음 (기존 소스 파일 수정 없음 — 테스트 전용 REQ)
- Tests:
  - `tests/test_wac_calculation.py` 신규
  - `tests/test_v1_portfolios_trades.py` 신규
  - `tests/test_v1_portfolios_pnl.py` 신규

## Notes
- 이 REQ는 REQ-039/040/041의 검증 근거를 명시적으로 확보하기 위한 Testing REQ다. 구현 코드를 직접 생산하지 않으므로 별도 REQ로 분리.
- 통합 테스트(TestClient 기반)는 DB-enabled 환경(`PORTFOLIOHUB_DB_ENABLED=true`)에서 실행하거나 모킹 전략을 사용할 수 있다. 모킹 전략과 실 DB 사용 여부는 구현 단계에서 결정.
- AC-1의 수기 기댓값(199,300)은 REQ-041 AC-1과 동일한 픽스처를 사용해야 한다.
- dcy-007 S-1/S-2 성공 기준의 측정 근거는 이 REQ의 테스트 실행 결과가 된다.
- Source: dcy-007 NFR-3, S-1, S-2, R-1.

## Change Log

### CHG-20260618-01
- Date: 2026-06-18
- Author: Justin Ko

#### Change Summary
- 최초 생성 — dcy-007 confirm-discovery 후 draft-req 실행. 체결 내역/PnL API 테스트 커버리지 산출물.

#### Intent
- dcy-007 NFR-3(PnL 로직 단위 테스트), S-1/S-2(기댓값 대조 통합 테스트)를 Testing REQ로 정규화. WAC 시나리오 기댓값과 R-1 경고 필드 검증을 의무 포함.

#### Acceptance Criteria Delta
- Added:
  - AC-1~6 최초 작성

#### Impacted Area Delta
- Tests: tests/test_wac_calculation.py, tests/test_v1_portfolios_trades.py, tests/test_v1_portfolios_pnl.py — 최초 지정

#### Delivery Trace Delta
- Batches: none (미정)
- Releases: none (미정)

#### Revalidation Impact
- Reverification Needed: no
- Existing Implementation Invalidated: no
- Status Recommendation: keep-current
- Follow-up Action: confirm-req 후 REQ-039/040/041과 동일 batch 편입(검증 REQ로서 구현 REQ와 동행)

#### Validation Plan
- pytest 실행으로 AC-1~6 직접 검증; 전체 스위트 회귀(AC-6)는 기존 pytest baseline과 비교

### CHG-20260618-02
- Date: 2026-06-18
- Author: 팀장 (Claude)

#### Change Summary
- confirm-req: `Proposed` → `Approved`. WAC 시나리오 기댓값·날짜필터·422·R-1 경고 검증 AC가 REQ-039~041과 정합, blocker 없음. 구현 REQ와 동일 batch. M1 fast-track.

### CHG-20260618-03
- Date: 2026-06-18
- Author: 팀장 (Claude)

#### Change Summary
- confirm-req-implemented: `Approved` → `Implemented`. Evidence: 3개 테스트 파일 50 passed(20+12+18) 독립 QC 재현, 전체 427 passed 회귀 없음. AC-1~6 충족.