portfolio-hub/docs/batches/bat-014_20260524_portfolioitem-symbol-response-contract/implementation.md

BAT-014 Implementation

• Status: completed
• Batch: BAT-014

Plan Summary

• planning.md Delivery Plan에 따라 (1) PortfolioItem schema에 symbol 추가 → (2) _portfolio_to_item() serialization 보강 → (3) CRUD/list 테스트 expectation 갱신 → (4) docs/interface-contract.md 계약 반영 → (5) pytest 검증 순서로 구현 완료.
• 사용자가 명시한 핵심 요구대로 GET /v1/portfolios 는 asset join 결과를 응답해야 하므로, repository shape(_SELECT_PORTFOLIO + _row_to_portfolio)를 유지한 채 응답 schema/문서/테스트를 정합화했다.

Changed Files

• app/schemas/v1.py
  • PortfolioItem 에 symbol: str | None = None 필드 추가
• app/api/v1_portfolios.py
  • _portfolio_to_item() 에 symbol=portfolio.symbol 추가
• tests/test_v1_portfolios_list.py
  • GET /v1/portfolios 응답의 symbol == "005930" 검증 추가
  • 기존 asset_id 검증 케이스에도 symbol assertion 추가
• tests/test_v1_portfolios_crud.py
  • POST/PATCH/DELETE 성공 응답에서 symbol == "005930" 검증 추가
• docs/interface-contract.md
  • POST/PATCH/DELETE/GET /v1/portfolios 응답 설명에 symbol 필드 반영
  • GET /v1/portfolios 가 server-side portfolios JOIN assets 결과를 직렬화한다는 설명 추가

Execution Log

1. BAT-014 planning/index와 REQ-025/026/027/028/032를 읽고 구현 범위를 확정했다.
2. app/schemas/v1.py 에 PortfolioItem.symbol 필드를 추가했다.
3. app/api/v1_portfolios.py _portfolio_to_item() 에 symbol=portfolio.symbol 매핑을 추가했다.
4. tests/test_v1_portfolios_crud.py 의 POST/PATCH/DELETE 성공 케이스에 symbol == "005930" assertion을 추가했다.
5. tests/test_v1_portfolios_list.py 의 service-token list 케이스와 asset_id 검증 케이스에 symbol == "005930" assertion을 추가했다.
6. docs/interface-contract.md 의 POST/PATCH/DELETE/GET /v1/portfolios 명세를 갱신해 symbol 과 join 기반 응답 계약을 명문화했다.
7. app/repositories/postgres.py 를 재검토해 _row_to_portfolio() 가 symbol=row[4] 를 매핑하고, get() / create_portfolio() / update_portfolio() / soft_delete_portfolio() / list_portfolios() 가 모두 _SELECT_PORTFOLIO 기반 join 결과를 사용함을 확인했다.
8. ./.venv/bin/python -m pytest tests/test_v1_portfolios_crud.py tests/test_v1_portfolios_list.py -q 실행 → 32 passed in 2.13s.
9. ./.venv/bin/python -m pytest -q 전체 회귀 실행 → 371 passed in 11.00s.

Validation

• Targeted regression:
  • ./.venv/bin/python -m pytest tests/test_v1_portfolios_crud.py tests/test_v1_portfolios_list.py -q → 32 passed in 2.13s
• Full regression:
  • ./.venv/bin/python -m pytest -q → 371 passed in 11.00s
• Repository join evidence:
  • _row_to_portfolio() 가 symbol=row[4] 를 Portfolio.symbol 로 매핑
  • get() / create_portfolio() / update_portfolio() / soft_delete_portfolio() / list_portfolios() 가 _SELECT_PORTFOLIO join 결과를 재사용

Remaining Risks

• R1 (Low): 이번 batch의 symbol 회귀는 FastAPI/TestClient + fake repo 중심이다. 다만 repository 코드 inspection으로 실제 Postgres 경로도 assets.symbol join 결과를 응답까지 유지함을 확인했다.
• R2 (Negligible): pytest 출력에 기존 HTTP_422_UNPROCESSABLE_ENTITY deprecation warning 2~3건이 남아 있으나 BAT-014 범위와 직접 관련은 없고 기능 실패는 없다.