portfolio-hub/docs/srs/Testing/req-042_trade-pnl-api-test-coverage.md

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

• Status: Approved
• 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.