portfolio-hub/docs/releases/rel-002_20260619_trade-history-and-pnl-api.md

# REL-002: 일일 거래내역 + 실현 PnL 조회 API (dcy-007 M1)

- Status: feedback-captured
- Profile: app-service
- Included Batch: BAT-017

## Scope

- Included:
  - BAT-017 (REQ-039, REQ-040, REQ-041, REQ-042): dcy-007 M1 fast-track — 일일 거래내역 + 실현 PnL 조회 API 신설
    - REQ-039: GET /v1/portfolios/{id}/trades (date 단일/from+to 범위 필터, read_token 이상 인증, 403/404/422)
    - REQ-040: GET /v1/portfolios/{id}/pnl/realized (from+to 필수, symbol 선택 필터, WAC 기반 실현 PnL, data_completeness_warning, cost_basis_from)
    - REQ-041: WAC cost_basis 산출 로직 — app/domain/pnl.py (순수 Python, DB 무의존, R-1 완화 경고 로직)
    - REQ-042: 테스트 커버리지 — test_wac_calculation.py(20건), test_v1_portfolios_trades.py(12건), test_v1_portfolios_pnl.py(18건)
  - Freeze 커밋: `bd34450` (main HEAD, 2026-06-18)
- Excluded:
  - 미실현 PnL (현재가 연동) — dcy-007 OQ-2 Out of Scope
  - 전체 portfolio 집계 PnL 뷰 — dcy-007 OQ-2 Out of Scope
  - DB 마이그레이션 없음 (기존 portfolio_ledger 스키마로 조회 가능)
  - 페이지네이션 — 이번 범위 외 이연
  - 성능 테스트 (p95 500ms) — TimescaleDB 통합/성능 환경에서 별도 검증 필요
  - BAT-001~016 (REL-001 포함 완료)

## Rollout Plan

1. **사전 확인**: 코드 freeze 커밋 `bd34450` main HEAD 일치 확인
2. **DB 마이그레이션 없음**: REL-002는 기존 `portfolio_ledger` 스키마(alembic head = `20260605_0025`, REL-001 적용 완료)를 그대로 사용. 추가 마이그레이션 불필요.
3. **portfolio-hub 서비스 배포**: 신규 이미지(freeze 커밋 `bd34450`) rolling restart
   - 신규 엔드포인트: `GET /v1/portfolios/{id}/trades` (REQ-039)
   - 신규 엔드포인트: `GET /v1/portfolios/{id}/pnl/realized` (REQ-040)
   - WAC domain 로직: `app/domain/pnl.py` 신규 (REQ-041)
   - 기존 엔드포인트 영향 없음 (additive 변경)
4. **배포 후 smoke 검증**: 하기 Verification Checklist 배포 직후 항목 실행

## Rollback Plan

- **트리거 조건**: portfolio-hub 배포 후 `GET /health` 실패, 신규 API 500 대규모 발생, 기존 API 회귀 발생
- **절차**:
  1. portfolio-hub → 이전 이미지(REL-001 freeze `6b812b6`) rolling restart
  2. DB 마이그레이션 없으므로 DB 롤백 불필요
  3. 기존 API (`/v1/portfolios`, `/v1/assets`, `/v1/tags`, `/v1/portfolios/{id}/ledger/trades` 등) 정상 동작 확인
- **롤백 영향**: 신규 엔드포인트 2개(`/trades`, `/pnl/realized`)만 제거됨. 기존 운영 기능 영향 없음. additive 변경이라 롤백 리스크 낮음.

## Verification Checklist

- **배포 전**:
  - [ ] freeze 커밋 `bd34450`이 배포 대상 이미지에 포함됨 확인
  - [ ] pytest 전체 (BAT-017 포함) 427 passed 확인: 50 (BAT-017 신규) + 377 (기존 회귀 0) — 2026-06-18 기준
  - [ ] DB 마이그레이션 불필요 확인 (alembic head `20260605_0025` 그대로)
  - [ ] REL-001 운영 인스턴스 health 정상 확인 (배포 베이스라인)
- **배포 직후 (portfolio-hub)**:
  - [x] `GET /health` → HTTP 200 + `db_enabled: true` 확인 ✅ (2026-06-19 17:27 KST, trex-op)
  - [x] `GET /v1/portfolios/{id}/trades?date=YYYY-MM-DD` (read_token 이상) → HTTP 200 + 항목 필드(`trade_id`, `side`, `quantity`, `price`, `executed_at`, `fee_amount`, `tax_amount`) 확인 (REQ-039 AC-1) ✅ (체결 2건 확인)
  - [x] `GET /v1/portfolios/{id}/trades` (날짜 파라미터 누락) → HTTP 422 확인 (REQ-039 AC-3) ✅
  - [x] `GET /v1/portfolios/{id}/pnl/realized?from=YYYY-MM-DD&to=YYYY-MM-DD` (read_token 이상) → HTTP 200 + `total_realized_pnl`, `cost_basis_from`, `items`, `data_completeness_warning` 필드 확인 (REQ-040 AC-1) ✅ (`total_realized_pnl=-9306.585` 확인)
  - [x] `GET /v1/portfolios/{id}/pnl/realized` (from/to 누락) → HTTP 422 확인 (REQ-040 AC-3) ✅
  - [x] 비소유자 토큰으로 `/trades` 또는 `/pnl/realized` 호출 → HTTP 403 확인 (REQ-039 AC-6, REQ-040 AC-7) ✅
  - [x] 존재하지 않는 portfolio_id로 호출 → HTTP 404 확인 (REQ-039 AC-7, REQ-040 AC-8) ✅
  - [ ] OpenAPI `/docs` 에서 신규 엔드포인트 2개 노출 확인 (REQ-039 AC-8, REQ-040 AC-9) — [비차단] 수동 확인 미완, 운영 관찰 중
  - [x] 기존 `GET /v1/portfolios`, `POST /v1/portfolios/{id}/ledger/trades`, `GET /health` 정상 동작 회귀 없음 확인 ✅

## Known Issues (QC PASS-WITH-NOTES 비차단 잔여)

1. **symbol 필터 edge 테스트 공백**: `GET /v1/portfolios/{id}/pnl/realized?symbol=X` 호출 시 `symbol_param != portfolio_symbol` 케이스(다른 symbol 필터 요청)에 대한 자동 테스트가 불완전. AC-2는 충족이나 완전 커버 아님. 별도 cleanup batch에서 처리 권장.
2. **HTTP_422_UNPROCESSABLE_ENTITY deprecated**: FastAPI 최신 버전에서 `HTTP_422_UNPROCESSABLE_ENTITY` → `HTTP_422_UNPROCESSABLE_CONTENT` 경고. 기존 코드 패턴 유지(breaking change 없음). 별도 cleanup batch에서 처리 권장.
3. **성능 AC-9/AC-10 미검증**: `GET /v1/portfolios/{id}/trades` 및 `/pnl/realized` p95 500ms — TimescaleDB 인덱스 환경에서 별도 실행 필요. 환경 제약으로 이번 릴리즈 검증 범위 외(코드 결함 아님).
4. **symbol 컬럼 부재**: `portfolio_ledger`에 symbol 컬럼 없음. 현재 portfolio 단위(1 portfolio = 1 symbol) 가정으로 동작. 멀티 symbol portfolio 지원 시 별도 설계 필요.

## Release Execution Evidence

- Release Status Transition Target: released

### Deployment Facts

- Executed At:
  - 2026-06-19 17:27 KST
- Completed At:
  - 2026-06-19 17:27 KST
- Environment:
  - portfolio-hub 운영 인스턴스 (port 8002)
- Operator:
  - trex-op (운영팀)
- Revision or Artifact:
  - 배포 커밋: `d89f137` (main HEAD, push 완료)
  - 이전 커밋: `50beba3` → 배포 커밋: `d89f137`
  - 비고: Freeze pin `bd34450`과 배포 커밋 `d89f137`의 차이는 REL 문서(docs-only) 변경으로 런타임 동일
- Commands or Procedure:
  - `bash /root/release/scripts/deploy-portfolio-hub.sh`
  - DB 마이그레이션 없음 (alembic head `20260605_0025` 유지, REL-001 시점과 동일)
  - 프로세스: PID 461546 (port 8002), RUNNING (2026-06-19 17:33 KST 확인)

### Profile-Specific Checks

- app-service:
  - Health Endpoint:
    - `GET /health` → HTTP 200, `db_enabled: true` (2026-06-19 배포 후 확인) ✅
  - Startup Log Fields:
    - PID 461546 (port 8002), RUNNING 상태 확인 (2026-06-19 17:33 KST) ✅
  - Request Log Fields:
    - (운영 관찰 계속 중)
  - Smoke or Manual Verification:
    - **배포 전 자동 테스트 evidence (2026-06-18)**:
      - BAT-017 신규 테스트: 50 passed (test_wac_calculation.py 20건 + test_v1_portfolios_trades.py 12건 + test_v1_portfolios_pnl.py 18건) — pytest 실행 출력: `50 passed, 8 warnings in 3.43s`
      - 기존 회귀 테스트: 377 passed, 0 failed — 회귀 없음
      - 합계: 427 passed, 0 failed
      - 독립 QC (`qc-reviewer`, 2026-06-18): **PASS-WITH-NOTES** — 50 passed 독립 재현 + 전체 427 passed 회귀 없음, WAC=11,000/realized=199,300 단위+e2e 검증, R-1 경고필드(buy없음·oversell·완전이력 null) 정상, NFR-3 격리(domain DB import 0) 확인, 스코프·DB 마이그레이션 무, 위생 이상 없음.
      - 운영팀 주간 테스트: 4개 서비스 전수 통과 (2026-06-19 사장님 확인)
    - **배포 후 smoke (2026-06-19 17:27 KST, trex-op)**:
      - `GET /health` → HTTP 200, `db_enabled: true` ✅
      - `GET /v1/portfolios/{id}/trades?date=2026-06-19` (read_token 이상) → HTTP 200, 체결 2건, 필드 전체 확인 (`trade_id`, `side`, `quantity`, `price`, `executed_at`, `fee_amount`, `tax_amount`) ✅ (REQ-039 AC-1)
      - `GET /v1/portfolios/{id}/trades` (날짜 파라미터 누락) → HTTP 422 ✅ (REQ-039 AC-3)
      - `GET /v1/portfolios/{id}/pnl/realized?from=2026-06-01&to=2026-06-19` (read_token 이상) → HTTP 200, `total_realized_pnl=-9306.585`, 필드 전체 확인 (`total_realized_pnl`, `cost_basis_from`, `items`, `data_completeness_warning`) ✅ (REQ-040 AC-1)
      - `GET /v1/portfolios/{id}/pnl/realized` (from/to 누락) → HTTP 422 ✅ (REQ-040 AC-3)
      - 비소유자 토큰으로 신규 엔드포인트 호출 → HTTP 403 ✅ (REQ-039 AC-6, REQ-040 AC-7)
      - 존재하지 않는 portfolio_id로 호출 → HTTP 404 ✅ (REQ-039 AC-7, REQ-040 AC-8)
      - 기존 `GET /v1/portfolios` 회귀 없음 ✅
      - [비차단] OpenAPI `/docs` 신규 엔드포인트 2개 노출 — 수동 확인 미완 (운영 관찰 중, 차단 아님)

### Rollback Outcome

- Rollback Required:
  - No
- Rollback Trigger:
  - none (트리거 조건 발생 없음)
- Rollback Action:
  - none (롤백 수행 없음)

### Release Decision Evidence

- Released Decision:
  - released 전환 승인.
- Rationale:
  - app-service profile released DoD 전항목 충족 판정 근거:
    (1) 배포 완료: 2026-06-19 17:27 KST, trex-op 수행, 커밋 d89f137 (freeze bd34450 대비 docs-only 차이, 런타임 동일) ✅
    (2) 프로세스 기동 확인: PID 461546 (port 8002) RUNNING (17:33 KST 확인) ✅
    (3) health endpoint: `GET /health` → HTTP 200, `db_enabled: true` ✅
    (4) DB 마이그레이션 없음: alembic head `20260605_0025` 유지 (REL-001과 동일) ✅
    (5) 신규 엔드포인트 smoke 전항목 통과: trades 200/422, pnl/realized 200/422, 403/404 정상 ✅
    (6) 기존 API 회귀 없음 ✅
    (7) 롤백 불필요 (트리거 없음) ✅
    (8) 배포 전 QC: BAT-017 50 passed + 전체 427 passed, qc-reviewer PASS-WITH-NOTES (2026-06-18) ✅
  - 비차단 잔여 (released 전환을 막지 않음):
    - OpenAPI `/docs` 신규 엔드포인트 노출 수동 확인 미완 — 기능 결함 아님, 운영 관찰 중
    - Known Issues 4건 (symbol 필터 edge 테스트, HTTP_422 deprecated, 성능 미검증, symbol 컬럼 부재) — QC PASS-WITH-NOTES 비차단으로 이미 기록됨, cleanup/차기 Discovery 후보
- Recorded By:
  - 팀장 (portfolio-hub-dev evidence 기입 + released 전환 판정, 2026-06-19)
- Recorded At:
  - 2026-06-19 KST

## Feedback Handoff

- Observation Summary:
  - 출처: 2026-06-22 운영팀(trex-op) 스모크 레포트 (배포 2026-06-19 17:27 KST, 커밋 `d89f137`, PID 461546, port 8002)
  - 스모크 결과: 9개 항목 중 8개 PASS, 1개 비차단 잔여
    - PASS (8/9):
      - GET /health → 200, db_enabled=true
      - GET /v1/portfolios/{id}/trades?date=2026-06-19 → 200, 체결 2건
      - GET /v1/portfolios/{id}/trades (날짜 누락) → 422
      - GET /v1/portfolios/{id}/pnl/realized?from=..&to=.. → 200, 필드 전체
      - GET /v1/portfolios/{id}/pnl/realized (from/to 누락) → 422
      - 비소유자 토큰 → 403
      - 존재하지 않는 portfolio_id → 404
      - 기존 GET /v1/portfolios 회귀 없음
    - 비차단 잔여 (1/9): OpenAPI /docs 신규 엔드포인트 2개 노출 — 브라우저 수동 확인 미완 (기능 결함 아님)
  - 운영 의의: 이 API(GET /v1/portfolios/{id}/trades, GET /v1/portfolios/{id}/pnl/realized)는 M2 첫 거래일 tsl 매도 확인의 데이터 원(source)으로 사용된다.
  - Captured At: 2026-06-22
- Discovery Input:
  - symbol 필터 edge (다른 symbol 필터 요청 케이스 `symbol_param != portfolio_symbol`) 자동 테스트 보강 — cleanup batch 후보
  - HTTP_422_UNPROCESSABLE_ENTITY deprecated → HTTP_422_UNPROCESSABLE_CONTENT 정리 — cleanup batch 후보
  - 성능 테스트 (p95 500ms, GET /v1/portfolios/{id}/trades 및 /pnl/realized) — TimescaleDB 인덱스 환경 구성 후 별도 검증 Discovery 후보
  - 멀티 symbol portfolio 지원 (portfolio_ledger에 symbol 컬럼 추가) — 별도 Discovery 후보
  - OpenAPI /docs 신규 엔드포인트 2개 브라우저 수동 노출 확인 — 다음 운영 점검 시 완료 권장
- REQ Input:
  - 없음 (기존 REQ 변경 불필요)
- Change Request Input:
  - 없음 (현 릴리즈 범위 내 변경 요청 없음)