portfolio-hub/docs/srs/Data/req-011_portfolios-asset-id-fk-and-column-removal.md

REQ-011: portfolios 테이블 asset_id FK 추가 및 symbol/market 제거

• Status: Implemented
• Type: Data
• Priority: High
• Owner: Justin Ko

Intent

• portfolios 테이블이 assets catalog를 참조하도록 재설계하여 "포지션"이 항상 검증된 catalog 항목 위에서만 존재하도록 한다.
• symbol/market 컬럼을 portfolios에서 제거하고 assets JOIN으로 대체한다.

Requirement

• portfolios 테이블에 asset_id UUID NOT NULL 컬럼을 추가하고 FOREIGN KEY (asset_id) REFERENCES assets(asset_id) ON DELETE RESTRICT DB-level FK constraint를 적용한다.
• portfolios.symbol 컬럼과 portfolios.market 컬럼을 제거한다.
• portfolios.broker 컬럼은 그대로 유지한다.
• (owner_user_id, asset_id) UNIQUE constraint는 추가하지 않는다(동일 user가 동일 asset에 복수 portfolio 허용).
• portfolios.managed_by_daemon_id는 기존과 동일하게 nullable soft reference로 유지한다.
• app/domain/models.py의 Portfolio 모델에서 symbol, market 필드를 제거하고 asset_id 참조를 추가한다.
• app/repositories/postgres.py의 portfolios 쿼리를 assets JOIN portfolios 형태로 변경한다.
• symbol/market 컬럼을 직접 참조하는 모든 쿼리, API response, CLI 출력을 수정한다(R-2 리스크 대응).

Acceptance Criteria

1. Given Alembic migration 적용 후, When portfolios 테이블 스키마를 확인, Then asset_id UUID NOT NULL과 FOREIGN KEY (asset_id) REFERENCES assets(asset_id) ON DELETE RESTRICT가 존재하고 symbol, market 컬럼이 없다.
2. Given 존재하지 않는 asset_id로 portfolio insert 시도, When DB에 반영, Then FK constraint violation이 발생한다.
3. Given status='inactive'인 asset을 참조하는 portfolio가 존재, When 해당 asset 행을 DELETE 시도, Then ON DELETE RESTRICT로 인해 거부된다.
4. Given portfolios 테이블 재설계 후, When 기존 portfolio 조회 API/CLI 호출, Then symbol, market 필드 참조 오류 없이 정상 응답이 반환된다.
5. Given 동일 user, 동일 asset_id, When 두 번째 portfolio를 생성, Then 성공적으로 생성된다(UNIQUE constraint 없음).

Impacted Area

• Docs:
  • docs/data-model.md — Portfolio 엔티티 재정의 (REQ-015에서 처리)
• Modules:
  • migrations/versions/ — portfolios.asset_id FK 추가, symbol/market 컬럼 제거 Alembic revision
  • app/domain/models.py — Portfolio 모델 symbol/market 필드 제거, asset_id 추가
  • app/repositories/postgres.py — portfolios 쿼리 assets JOIN 반영, symbol/market 참조 제거
  • app/api/portfolios.py — portfolio 생성/조회 response에서 symbol/market 제거
  • app/api/v1_assets.py — response에서 symbol/market 제거 (asset 참조로 대체)
  • app/cli/commands/portfolio.py — portfolio 출력에서 symbol/market 제거
  • app/schemas/ — PortfolioListItem, PortfolioDetailResponse 등 스키마 변경
• Tests:
  • 기존 테스트 suite — symbol/market 참조 테스트 갱신
  • tests/test_asset_catalog.py (신규) — FK constraint, RESTRICT 동작 검증

Notes

• R-2(High): migration 전 grep -rn "\.symbol\|\.market" app/으로 참조 범위를 전수 조사해야 한다. broker는 portfolios에 유지되므로 별도 조사 불필요.
• NFR-2(성능): portfolios.asset_id FK 인덱스는 DB가 자동 생성한다. assets JOIN portfolios 쿼리 성능을 batch verification에서 확인한다.
• REQ-009 선행 필요(assets 테이블이 먼저 존재해야 FK 적용 가능).
• REQ-014(data migration)가 이 REQ의 schema 변경과 연계되어야 한다. schema 변경과 데이터 이전을 같은 Alembic revision 또는 순서 보장된 revision 시퀀스로 처리한다.
• Source: dcy-001 FR-3, R-2

Change Log

CHG-20260521-01

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

Change Summary

• Status: Approved → Implemented

Intent

• BAT-001 confirm-batch-verification 완료. portfolios.asset_id FK, symbol/market 컬럼 제거, 기존 조회 API 회귀 없음 확인. DB-integration ACs는 실 DB 의존 — release 배포 시 최종 확인 예정.

Acceptance Criteria Delta

• No change

Impacted Area Delta

• No change

Delivery Trace Delta

• Batches:
  • BAT-001
• Releases:
  • REL-001

Revalidation Impact

• Reverification Needed: no
• Existing Implementation Invalidated: no
• Status Recommendation: implemented
• Follow-up Action: REL-001 배포 시 alembic upgrade 결과로 DB-integration AC 최종 확인

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-3을 Data REQ로 분리; portfolios 테이블 asset_id FK 추가, symbol/market 제거

Acceptance Criteria Delta

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

Impacted Area Delta

• Docs:
  • docs/data-model.md — 최초 지정
• Modules:
  • migrations/versions/, app/domain/models.py, app/repositories/postgres.py, app/api/portfolios.py, app/api/v1_assets.py, app/cli/commands/portfolio.py, app/schemas/ — 최초 지정
• Tests:
  • 기존 테스트 suite, tests/test_asset_catalog.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 선행 의존성 확인

Validation Plan

• pytest로 AC-1~5 검증; grep으로 symbol/market 참조 잔존 여부 확인