Files
portfolio-hub/docs/batches/bat-014_20260524_portfolioitem-symbol-response-contract/planning.md
T

3.1 KiB

BAT-014 Planning

  • Status: draft
  • Batch: BAT-014
  • Profile: batch-lite

Included REQ

  • REQ-025: POST /v1/portfolios 응답에 PortfolioItem.symbol 포함
  • REQ-026: PATCH /v1/portfolios/{portfolio_id} 응답에 PortfolioItem.symbol 포함
  • REQ-027: DELETE /v1/portfolios/{portfolio_id} (HTTP 200 응답) 에 PortfolioItem.symbol 포함
  • REQ-028: GET /v1/portfolios 응답이 portfolios JOIN assets 결과를 기반으로 symbol 을 직접 반환
  • REQ-032: baseline 문서에 위 계약 반영

Delivery Plan

  1. app/schemas/v1.py 의 PortfolioItem 에 symbol: str | None = None 추가
  2. app/api/v1_portfolios.py 의 _portfolio_to_item() 에 symbol=portfolio.symbol 추가
  3. app/repositories/postgres.py 의 _SELECT_PORTFOLIO / _row_to_portfolio / get() / list_portfolios() 흐름을 재확인해 GET /v1/portfolios 가 asset join 결과를 응답까지 유지하는지 검증
  4. tests/test_v1_portfolios_list.py 에서 GET 응답 item의 symbol 존재 및 기대값(005930) 검증 추가
  5. tests/test_v1_portfolios_crud.py 에서 POST/PATCH/DELETE 응답의 symbol 존재 및 기대값 검증 추가
  6. docs/interface-contract.md 에 POST/PATCH/DELETE/GET /v1/portfolios 응답 설명의 symbol 반영 및 GET의 asset join 기반 응답 설명 추가
  7. 회귀 테스트 실행 및 결과를 후속 verification 단계에 기록

Dependencies

  • Internal:
    • BAT-009 (v1 portfolio CRUD core) — 기존 구현과 테스트 기반
    • BAT-010 (portfolio v1 baseline docs) — interface-contract baseline 업데이트 trace
  • External:
    • 없음

Design Gate

  • Design Required Before Implementation: no
  • Reason:
    • 변경은 기존 CRUD/list 응답 contract에 additive field 하나를 추가하고 문서/테스트를 보강하는 수준이다.
    • app/repositories/postgres.py 는 이미 _SELECT_PORTFOLIO 에서 JOIN assets a ON p.asset_id = a.asset_id 및 a.symbol 선택을 수행하고 있어, 새 쿼리 전략이나 구조 재설계가 필요하지 않다.
    • 사용자가 명시한 핵심 제약(GET /v1/portfolios 는 asset join 결과를 응답해야 함)도 현재 repository shape와 정합한다. 따라서 design 산출물 없이 구현/검증으로 바로 진행 가능하다.

Milestones

  1. Schema/API serialization 반영
  2. CRUD/list 테스트 보강
  3. baseline 문서 갱신
  4. 회귀 테스트 실행
  5. verification 근거 정리 후 REQ 재Implemented 검토

Risks

  • R1 (Low): 테스트 fixture가 in-memory fake repo를 사용하므로 repository-level join 보장을 직접 증명하지 못할 수 있음.
    • 대응: GET contract 문서와 repository 코드 확인 결과를 verification에 함께 기록하고, 필요 시 repo integration test 추가를 검토.
  • R2 (Low): PortfolioItem 에 symbol 추가 시 기존 스냅샷/응답 dict equality 테스트가 깨질 수 있음.
    • 대응: 테스트 expectation을 additive field 기준으로 갱신.
  • R3 (Low): baseline 문서가 POST/PATCH/DELETE/GET 중 일부 응답만 갱신되어 source of truth 불일치가 남을 수 있음.
    • 대응: docs/interface-contract.md 네 경로를 한 턴에 모두 갱신.