portfolio-hub/docs/srs/Interface/req-006_v1-assets-endpoint.md

req-006: GET /v1/assets 엔드포인트 구현

• Status: Implemented
• Type: Interface
• Priority: High
• Owner: repository-maintainers

Intent

• trex-basic 데몬이 관리 자산 목록과 전략 파라미터를 조회할 수 있도록 portfolio 데이터를 asset 뷰로 변환해 제공한다.
• asset_id는 기존 portfolio_id를 그대로 사용하며 별도 식별자 체계를 만들지 않는다(A-3).

Requirement

• GET /v1/assets는 service-token bearer 인증으로 토큰 소유자의 portfolio 목록을 asset_id, symbol, market, status, cash, quantity, broker_type, strategy_id, strategy_type, strategy_params, updated_at 필드로 반환해야 한다.
• status=active 쿼리 파라미터로 필터링이 가능해야 한다.
• strategy_params는 해당 portfolio의 active_strategy_id로 조회한 StrategySet.config에서 파생한다. strategy_id는 허용값 검증 없이 그대로 반환한다(OQ-1 Answered).
• strategy_type은 해당 portfolio의 active_strategy_id로 조회한 StrategySet.name을 반환한다. active_strategy_id가 없거나 StrategySet 조회 실패 시 null을 반환한다.

Acceptance Criteria

1. Given 유효한 service-token bearer 인증으로 GET /v1/assets 요청 시, When 토큰이 유효하면, Then HTTP 200과 해당 사용자 소유 portfolio 목록이 반환되어야 한다.
2. Given GET /v1/assets?status=active 요청 시, Then status가 active인 항목만 반환되어야 한다.
3. Given 응답의 각 항목을 확인하면, Then asset_id, symbol, market, status, cash, quantity, broker_type, strategy_id, strategy_type, strategy_params, updated_at 필드가 모두 포함되어야 한다.
4. Given portfolio에 연결된 StrategySet이 있을 때, When strategy_params를 확인하면, Then StrategySet.config 값에서 파생된 JSON 객체여야 한다.
5. Given StrategySet config가 없거나 파싱 실패 시, Then strategy_params는 빈 객체({})를 반환하고 에러가 전파되지 않아야 한다.
6. Given portfolios.market이 NULL인 경우, Then 응답의 market 필드도 null로 반환되어야 한다(DECIDE_MARKET_DEFAULT Answered).
7. Given 인증 없이 GET /v1/assets 요청 시, Then HTTP 401이 반환되어야 한다.
8. Given portfolio에 active_strategy_id로 연결된 StrategySet이 있을 때, Then strategy_type은 해당 StrategySet.name 값을 반환해야 한다.
9. Given portfolio에 active_strategy_id가 없거나 StrategySet 조회 실패 시, Then strategy_type은 null을 반환해야 한다.

Impacted Area

• Docs: docs/interface-contract.md (REQ-011에서 갱신 예정), docs/project-structure.md (신규 라우터 파일 반영 필요)
• Modules: app/api/v1_assets.py (신규), app/services/ (assets 조회 서비스 메서드 추가), app/schemas/ (v1 assets 응답 스키마 추가), app/repositories/postgres.py (portfolio + strategy_set JOIN 쿼리 추가), app/main.py (/v1 라우터 등록)
• Tests: tests/test_v1_assets.py (신규)

Notes

• broker_type은 portfolios.broker 컬럼을 그대로 매핑한다(m-2 finding 반영).
• strategy_id는 portfolios.active_strategy_id를 그대로 반환한다.
• GET /v1/assets의 소유권 스코프는 service-token 소유자(owner_user_id)를 기준으로 한다.
• Source Discovery: dcy-002 (FR-3, A-3, OQ-1)

Change Log

CHG-20260511-01

• Date: 2026-05-11
• Author: repository-maintainers

Change Summary

• Implemented 전환 — BAT-001 re-verified verification passed, confirm-req-implemented 게이트 통과

Intent

• BAT-001 verification.md (re-verified, 2026-05-03, CHG-20260503-01 strategy_type 재검증 포함) AC-1~9 모두 PASS. Blocking Issues 없음.

Acceptance Criteria Delta

• none

Impacted Area Delta

• none

Delivery Trace Delta

• Batches: BAT-001 (release-candidate)
• Releases: none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: implemented
• Follow-up Action: draft-release (BAT-001)

Validation Plan

• BAT-001 verification.md (re-verified) AC-1~9 evidence 연결 확인 완료 (strategy_type 필드 재검증 포함)

CHG-20260503-01

• Date: 2026-05-03
• Author: repository-maintainers

Change Summary

• GET /v1/assets 응답 필드에 strategy_type 추가 — StrategySet.name 값을 반환

Intent

• trex-basic 데몬이 asset 뷰에서 전략 이름(StrategySet.name)을 직접 확인할 수 있도록 strategy_type 필드를 응답에 추가한다.
• DB 변경 없이 기존 StrategySet.name 컬럼을 활용하는 순수 응답 스키마 확장이다.

Acceptance Criteria Delta

• Added:
  • AC-8: Given portfolio에 active_strategy_id로 연결된 StrategySet이 있을 때, Then strategy_type은 StrategySet.name 값을 반환해야 한다.
  • AC-9: Given portfolio에 active_strategy_id가 없거나 StrategySet 조회 실패 시, Then strategy_type은 null을 반환해야 한다.
• Modified:
  • AC-3: strategy_type 필드를 필수 응답 필드 목록에 추가

Impacted Area Delta

• Modules:
  • app/schemas/v1.py: AssetItem에 strategy_type 필드 추가
  • app/api/v1_assets.py: strategy_type 매핑 로직 추가 (StrategySet.name 조회)

Delivery Trace Delta

• Batches:
  • BAT-001 (release-candidate) — REQ-006 포함, strategy_type 추가로 재검증 필요
• Releases:
  • 없음 (아직 draft-release 미수행)

Revalidation Impact

• Reverification Needed: yes
• Existing Implementation Invalidated: yes (BAT-001 verification은 strategy_type 없이 수행됨)
• Status Recommendation: keep-current (Approved 유지 — 구현 전 단계이므로 상태 되돌림 불필요)
• Follow-up Action: 구현 후 BAT-001 verification 재수행 또는 BAT-006 신규 생성 결정 필요

Validation Plan

• app/schemas/v1.py AssetItem에 strategy_type 필드 추가
• app/api/v1_assets.py에서 portfolio.active_strategy_id로 StrategySet.name 조회 후 매핑
• tests/test_v1_assets.py 또는 test_app.py에서 strategy_type 필드 존재 및 null 케이스 검증

CHG-20260502-02

• Date: 2026-05-02
• Author: repository-maintainers

Change Summary

• REQ-006 confirm-req 승인 전환 (Status: Proposed → Approved)

Intent

• 필수 필드(Status, Type, Priority, Owner, Intent, Requirement, Acceptance Criteria 7개, Impacted Area, Change Log) 모두 충족 확인 후 승인

Acceptance Criteria Delta

• No change

Impacted Area Delta

• No change

Delivery Trace Delta

• Batches:
  • none
• Releases:
  • none

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: keep-current
• Follow-up Action: suggest-batch-reqs → draft-batch

CHG-20260502-01

• Date: 2026-05-02
• Author: repository-maintainers

Change Summary

• REQ-006 최초 생성 (source Discovery: dcy-002 FR-3)

Intent

• trex-basic Consumer-Driven Contract의 GET /v1/assets 요구사항을 REQ backlog로 정규화

Acceptance Criteria Delta

• Added:
  • 전체 Acceptance Criteria 신규 작성

Impacted Area Delta

• Docs:
  • docs/interface-contract.md (REQ-011에서 갱신 예정)
• Modules:
  • app/api/v1_assets.py 신규
  • app/main.py (/v1 라우터 등록)
• Tests:
  • tests/test_v1_assets.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 후 batch 배정. REQ-009 migration(market 컬럼 추가)과 함께 delivery 단위 구성 권장.