portfolio-hub/docs/srs/Interface/req-018_portfolio-http-api-uuid-path-param.md

req-018: HTTP API portfolio path parameter UUID 전환 및 v1 asset_id UUID 반환

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

Intent

• HTTP API의 portfolio 관련 path parameter를 기존 문자열 portfolio_id에서 UUID 기반으로 전환해 REQ-016의 스키마 변경과 일관성을 맞춘다.
• GET /v1/assets 응답의 asset_id 필드를 UUID로 반환해 trex-basic 계약을 갱신하고, dcy-002 A-3을 철회한다.

Requirement

• app/api/portfolios.py의 portfolio 관련 path parameter를 UUID 기반으로 변경한다.
• GET /v1/assets 응답의 asset_id 필드는 portfolios.portfolio_id(UUID)를 반환한다.
• app/api/v1_assets.py의 AssetItem 직렬화에서 asset_id는 portfolio_id(UUID) 값을 사용한다.
• POST /v1/assets/{asset_id}/ledger/trades 경로의 asset_id path parameter는 UUID를 받아 repo.get(asset_id)로 portfolio를 조회한다.
• dcy-002 문서의 A-3("asset_id는 portfolio_id를 그대로 사용") 조항은 이번 REQ 구현으로 공식 철회된다. docs/discovery/dcy-002_20260502_trex-basic-consumer-api-contract.md에 철회 주석을 추가한다.

Acceptance Criteria

1. Given GET /v1/assets를 유효한 service-token으로 호출하면, When 응답 JSON의 assets[].asset_id 필드를 확인하면, Then 값이 UUID 형식(re.match(r'^[0-9a-f-]{36}$', ...))이다.
2. Given UUID를 asset_id로 사용해 POST /v1/assets/{asset_id}/ledger/trades를 호출하면, When 해당 UUID의 portfolio가 존재하면, Then HTTP 201(status="new") 또는 HTTP 200(status="duplicate")으로 정상 처리된다.
3. Given UUID를 asset_id로 사용해 POST /v1/assets/{asset_id}/ledger/trades를 호출하면, When 해당 UUID의 portfolio가 존재하지 않으면, Then HTTP 404가 반환된다.
4. Given portfolio 관련 HTTP API path(/portfolios/{portfolio_id})를 UUID로 호출하면, When 해당 UUID의 portfolio가 존재하면, Then 정상 응답이 반환된다.
5. Given docs/discovery/dcy-002_20260502_trex-basic-consumer-api-contract.md를 확인하면, Then A-3 항목에 이번 REQ 구현으로 철회되었다는 주석이 추가되어 있다.

Impacted Area

• Docs:
  • docs/interface-contract.md (GET /v1/assets asset_id 변경 반영 — REQ-019에서 처리)
  • docs/discovery/dcy-002_20260502_trex-basic-consumer-api-contract.md (A-3 철회 주석 추가)
• Modules:
  • app/api/portfolios.py: path parameter UUID 기반 전환
  • app/api/v1_assets.py: asset_id 직렬화 UUID 사용
  • app/schemas/portfolio.py, app/schemas/v1.py: asset_id/portfolio_id 필드 타입 문서화
• Tests:
  • tests/test_app.py 또는 tests/test_v1.py: GET /v1/assets asset_id UUID 형식 검증, POST /v1/assets/{asset_id}/ledger/trades UUID 호출 정상 동작 확인

Notes

• trex-basic 측 코드 변경은 이번 REQ 범위 밖. portfolio-hub API 변경만 담당.
• trex-basic과 portfolio-hub는 동시에 배포한다(NFR-3 — 동시 배포 계획 기록은 REQ-019에서 docs/interface-contract.md에 처리).
• dcy-002 A-3 철회 주석 추가는 이 REQ 구현 시 함께 수행한다.
• GET /v1/assets flow의 asset_id 직렬화: docs/runtime-flows.md Flow v1 API — GET /v1/assets 갱신 필요 (REQ-019에서 처리).
• Source Discovery: dcy-004_20260511_portfolio-id-uuid-migration-and-user-scoped-name-resolution (FR-4)

Change Log

CHG-20260511-01

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

Change Summary

• 최초 생성 — dcy-004 draft-req에 의해 생성

Intent

• dcy-004 Discovery의 FR-4(HTTP API path parameter UUID 전환, GET /v1/assets asset_id UUID 반환, dcy-002 A-3 철회) 반영

Acceptance Criteria Delta

• Added:
  • 1~5 (최초 생성)

Impacted Area Delta

• Docs:
  • docs/interface-contract.md: GET /v1/assets asset_id 변경 반영 (REQ-019에서 처리)
  • docs/discovery/dcy-002_*: A-3 철회 주석 추가
• Modules:
  • app/api/portfolios.py: path parameter UUID 전환
  • app/api/v1_assets.py: asset_id UUID 직렬화
  • app/schemas/portfolio.py, app/schemas/v1.py: 필드 타입 변경
• Tests:
  • tests/test_app.py 또는 tests/test_v1.py: GET /v1/assets asset_id UUID 형식 검증

Delivery Trace Delta

• Batches: none (batch 미결정)
• Releases: none

Revalidation Impact

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

Validation Plan

• pytest: GET /v1/assets asset_id UUID 형식 검증, POST /v1/assets/{asset_id}/ledger/trades UUID 호출 동작 검증, HTTP 404 반환 확인

CHG-20260511-02

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

Change Summary

• Approved 전환 — confirm-req 게이트 통과

Intent

• Delivery 입력으로 사용할 수 있도록 REQ-018을 승인 상태로 승격한다.

Acceptance Criteria Delta

• Added:
  • none
• Updated:
  • none
• Removed:
  • none

Impacted Area Delta

• Docs:
  • none
• Modules:
  • none
• Tests:
  • none

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로 batch grouping 검토

Validation Plan

• confirm-req 게이트 재평가 결과: 필수 메타데이터, 구체적 Acceptance Criteria, Impacted Area, Change Log, blocker 없음 확인

CHG-20260511-03

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

Change Summary

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

Intent

• BAT-006 verification.md의 REQ-018 AC-15 모두 evidence 포함 (AC-14: 구현 코드 검증, AC-5: dcy-002 A-3 철회 주석 문서 확인). Blocking Issues 없음.

Acceptance Criteria Delta

• none

Impacted Area Delta

• none

Delivery Trace Delta

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

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: implemented
• Follow-up Action: draft-release (BAT-006); trex-basic 동시 배포 조정 필요

Validation Plan

• BAT-006 verification.md AC-1~5 evidence 연결 확인; dcy-002 A-3 철회 주석 직접 확인 완료