portfolio-hub/docs/srs/Interface/req-013_get-v1-assets-token-branching.md

REQ-013: GET /v1/assets 토큰 타입별 분기 재정의

• Status: Deprecated
• Type: Interface
• Priority: High
• Owner: Justin Ko
• Deprecated By: dcy-003 (path 명명 분리 옵션 B 결정), 2026-05-20

Intent

• 현재 service token(daemon) 전용으로 구현된 GET /v1/assets를 user token 및 admin token도 지원하는 통합 portfolio 조회 엔드포인트로 재정의한다.
• daemon(service token), 로그인 사용자(user token), 관리자(admin token) 모두 단일 엔드포인트로 각자의 portfolio 목록을 조회할 수 있도록 한다.

Requirement

• GET /v1/assets 엔드포인트를 토큰 타입에 따라 아래와 같이 분기한다.
  • service token (daemon): auth context에서 daemon_id를 자동 추출, managed_by_daemon_id = auth.daemon_id 필터링. daemon_id가 없으면 HTTP 403.
  • user token: owner_user_id = auth.user_id 필터링. 본인 portfolio만 반환.
  • admin token: 기본 owner_user_id = auth.user_id(본인 portfolio). ?user_id=<id> 파라미터 지정 시 해당 user의 portfolio 반환.
• 모든 토큰 타입에서 ?market=<code> 파라미터를 지원한다. 지정 시 <code> = ANY(assets.markets)인 portfolio만 반환한다.
• 응답 항목의 asset_id는 catalog의 assets.asset_id(UUID)를 참조한다(현재 portfolio.portfolio_id가 아님).
• app/api/v1_assets.py의 list_assets 함수를 토큰 타입 분기 로직으로 재작성한다. 현재 _require_service_token 강제를 제거하고 토큰 타입 자동 분기로 교체한다.

Acceptance Criteria

1. Given daemon service token(daemon_id 있음), When GET /v1/assets, Then managed_by_daemon_id = auth.daemon_id로 필터링된 portfolio 목록이 반환된다.
2. Given daemon service token(daemon_id 없음), When GET /v1/assets, Then HTTP 403이 반환된다.
3. Given user token, When GET /v1/assets, Then owner_user_id = auth.user_id인 portfolio 목록만 반환된다.
4. Given admin token, When GET /v1/assets (?user_id 없음), Then admin 본인의 portfolio 목록이 반환된다.
5. Given admin token, When GET /v1/assets?user_id=<target_user_id>, Then 해당 user의 portfolio 목록이 반환된다.
6. Given 모든 토큰 타입, When GET /v1/assets?market=KRX, Then KRX = ANY(assets.markets)인 portfolio만 반환된다.
7. Given 응답 항목, When asset_id 필드 확인, Then assets.asset_id(catalog UUID)를 참조한다(portfolio_id가 아님).

Impacted Area

• Docs:
  • docs/runtime-flows.md — "GET /v1/assets" 플로우 재정의 (REQ-015에서 처리). 현재 기술(service-token-only, daemon-id guard)을 토큰 타입 분기 구조로 교체.
  • docs/interface-contract.md — GET /v1/assets 명세 갱신 (REQ-015에서 처리)
• Modules:
  • app/api/v1_assets.py — list_assets 토큰 타입 분기 재작성, ?user_id 파라미터 추가, _require_service_token 강제 제거
  • app/repositories/postgres.py — token-type별 portfolios 쿼리 분기
• Tests:
  • tests/test_v1_asset_catalog.py (신규) — AC-1~7 검증
  • 기존 test_v1_assets.py 또는 관련 테스트 — service token 전용 동작 갱신

Notes

• 현재 app/api/v1_assets.py의 _require_service_token은 service token 전용으로 구현되어 있다. 이 REQ는 해당 guard를 제거하고 토큰 타입 자동 분기로 완전 재작성하는 작업이다.
• 현재 runtime-flows.md "Flow: v1 API — GET /v1/assets"는 service-token-only 구조를 기술하고 있다. 이 REQ 구현 후 해당 플로우를 REQ-015에서 갱신해야 한다.
• REQ-009(assets 테이블), REQ-011(portfolios 재설계) 선행 필요.
• Source: dcy-001 FR-5

Change Log

CHG-20260520-01

• Date: 2026-05-20
• Author: Justin Ko

Change Summary

• Status: Approved → Deprecated. dcy-003(docs/discovery/dcy-003_20260520_user-portfolio-mutation-v1-api-migration.md, confirmed 2026-05-20)의 옵션 B(완전 분리) 결정으로 본 REQ의 path 결정이 무효화됨.

Intent

• dcy-003은 GET /v1/assets를 admin asset catalog 전용으로 회수하고 포지션 조회는 GET /v1/portfolios 신설 경로로 분리하는 정책을 채택했다. 본 REQ의 통합 endpoint 정의(GET /v1/assets가 토큰 타입별로 catalog/포지션을 동시 처리)는 dcy-003 결정에 따라 더 이상 기준 문서가 아니므로 Deprecated로 전환한다.
• 본 REQ의 후속:
  • GET /v1/assets (admin catalog 조회 의미) → dcy-001 batch design 단계에서 REQ-010 또는 신규 REQ로 분리 처리 (REQ-010 Notes 참조)
  • GET /v1/portfolios (포지션 토큰 분기 조회) → dcy-003 FR-5에서 별도 신규 REQ로 작성 예정 (dcy-003 draft-req 단계)

Acceptance Criteria Delta

• Removed: AC-1~7 전체 (본 REQ Deprecated로 인해 검증 대상에서 제외). 후속 신규 REQ에서 새 path 기준으로 재작성 예정.

Impacted Area Delta

• Docs:
  • docs/discovery/dcy-003 §6 OQ-5, §10 CONFIRM_DCY001_FR5_CHANGE_REQ가 본 Deprecated 처리의 근거
  • docs/srs/Interface/req-010 Notes에 후속 GET /v1/assets catalog 명세 처리 계획 반영
• Modules:
  • 본 REQ Approved 시점에 코드 변경이 일어나지 않은 상태였으므로 코드 회귀 없음. 후속 신규 REQ에서 app/api/v1_portfolios.py 신규 + app/api/v1_assets.py 정리.
• Tests:
  • 신규 tests/test_v1_asset_catalog.py(REQ-013 Notes에 지정)는 작성되지 않은 상태. 후속 신규 REQ로 이관.

Delivery Trace Delta

• Batches: 본 REQ가 포함된 batch 미정. Deprecated 이후 batch 편입 없음.
• Releases: 본 REQ 포함 release 미정.

Revalidation Impact

• Reverification Needed: no (구현 미진행 상태에서 Deprecated)
• Existing Implementation Invalidated: no
• Status Recommendation: deprecated
• Follow-up Action: dcy-003 draft-req 단계에서 GET /v1/portfolios 신규 REQ 작성, dcy-001 batch design 단계에서 GET /v1/assets catalog 조회 명세 처리(REQ-010 보강 또는 신규 REQ)

Validation Plan

• 없음 (Deprecated 전환만)

CHG-20260519-02

• Date: 2026-05-19
• Author: Justin Ko

Change Summary

• Status: Proposed → Approved

Intent

• 승인 게이트 통과: 필수 필드(Status/Type/Priority/Owner/Intent/Requirement/AC/Impacted Area/Change Log) 모두 충족, AC 구체성 확인 완료

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: promote-to-approved
• Follow-up Action: batch 계획 편입

CHG-20260519-01

• Date: 2026-05-19
• Author: Justin Ko

Change Summary

• 최초 생성 — dcy-001 confirm-discovery 후 draft-req 실행

Intent

• dcy-001 FR-5를 Interface REQ로 분리; GET /v1/assets 토큰 타입별 분기 정의

Acceptance Criteria Delta

• Added:
  • AC-1~7 최초 작성

Impacted Area Delta

• Docs:
  • docs/runtime-flows.md, docs/interface-contract.md — 최초 지정
• Modules:
  • app/api/v1_assets.py, app/repositories/postgres.py — 최초 지정
• Tests:
  • tests/test_v1_asset_catalog.py (신규), 기존 v1 테스트 — 최초 지정

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, REQ-011 선행 의존성 확인

Validation Plan

• pytest TestClient로 AC-1~7 검증; 토큰 타입별 시나리오를 각각 독립 테스트로 분리