portfolio-hub/docs/batches/bat-001_20260519_asset-catalog-db-foundation/design.md

BAT-001 Design

• Status: draft
• Batch: BAT-001

Architecture Summary

• assets 테이블을 신규 도입하여 "자산(종목) 카탈로그"와 "포지션(포트폴리오)" 개념을 DB 레벨에서 분리한다.
• 기존 portfolios 테이블은 symbol/market 직접 보유에서 asset_id FK 참조 구조로 전환한다.
• 기존 운영 데이터는 ARRAY_AGG(DISTINCT market) 집약 규칙으로 assets catalog로 이전하고, 각 portfolio 행에 asset_id를 역으로 연결한 뒤 레거시 컬럼을 제거한다.
• 모든 DB 변경은 Alembic으로만 관리하며 ensure_schema()는 사용하지 않는다.

Alembic Revision 전략

결정: 2-revision 분리 (rev-A → rev-B)

rev-A (REQ-009 전용):

• assets 테이블 CREATE TABLE
• idx_assets_markets_gin GIN 인덱스 CREATE

rev-B (REQ-011 + REQ-014 결합, 단일 트랜잭션):

BEGIN;
-- Step 1: 사전 검증 (symbol 수 파악)
SELECT COUNT(DISTINCT symbol) FROM portfolios;

-- Step 2: assets catalog 채우기 (ARRAY_AGG(DISTINCT market), NULL → '{}')
INSERT INTO assets (symbol, markets)
SELECT symbol, ARRAY_AGG(DISTINCT market) FILTER (WHERE market IS NOT NULL)
FROM portfolios
GROUP BY symbol
ON CONFLICT (symbol) DO NOTHING;

-- Step 3: portfolios.asset_id 컬럼 추가 (NULL 허용, 임시)
ALTER TABLE portfolios ADD COLUMN asset_id UUID;

-- Step 4: asset_id 역연결
UPDATE portfolios p SET asset_id = a.asset_id
FROM assets a WHERE a.symbol = p.symbol;

-- Step 5: NOT NULL 제약 + FK 추가
ALTER TABLE portfolios ALTER COLUMN asset_id SET NOT NULL;
ALTER TABLE portfolios ADD CONSTRAINT fk_portfolios_asset_id
  FOREIGN KEY (asset_id) REFERENCES assets(asset_id) ON DELETE RESTRICT;

-- Step 6: 레거시 컬럼 제거
ALTER TABLE portfolios DROP COLUMN symbol;
ALTER TABLE portfolios DROP COLUMN market;
COMMIT;

이유: rev-A와 rev-B를 분리하면 rev-A만 단독 롤백 가능. rev-B 내부는 단일 트랜잭션으로 원자성 보장 (REQ-014 NFR-1).

Changed Areas

• Docs:
  • docs/data-model.md — REQ-015에서 처리 (이 batch 범위 밖)
• Modules:
  • migrations/versions/ — rev-A, rev-B 신규 revision 파일 2개
  • app/domain/models.py — MarketCode Enum, Asset 모델 추가; Portfolio 모델 symbol/market 제거, asset_id 추가
  • app/repositories/portfolio_repository.py — asset CRUD Protocol 메서드 선언 추가
  • app/repositories/postgres.py — asset CRUD 구현 추가; portfolios 쿼리 assets JOIN 반영
  • app/api/portfolios.py — symbol/market 참조 제거
  • app/api/v1_assets.py — symbol/market 참조 제거 (list_assets 전면 재작성은 REQ-013 범위이므로 최소 수정)
  • app/cli/commands/portfolio.py — 출력에서 symbol/market 제거
  • app/schemas/ — PortfolioListItem 등 symbol/market 필드 제거
• Interfaces:
  • portfolio_repository.py Protocol에 신규 asset CRUD 메서드 추가

Key Decisions

1. rev-B에서 portfolios.asset_id를 NULL 허용으로 먼저 추가 후 데이터 채운 뒤 NOT NULL 제약 적용

   • 이유: ADD COLUMN ... NOT NULL 단일 문장은 기존 행에 DEFAULT 없으면 오류 → 2단계 처리 필수
   • 구현: ADD COLUMN asset_id UUID → UPDATE → SET NOT NULL

2. REQ-011 schema 변경과 REQ-014 데이터 이전을 rev-B 단일 revision 내 단일 트랜잭션으로 결합

   • 이유: 데이터 이전 없이 symbol/market DROP이 불가하고, 두 revision으로 분리하면 중간 상태(asset_id NULL + symbol 잔존)가 운영 DB에 커밋될 위험
   • 트레이드오프: revision이 크고 복잡해지지만 롤백 안전성 확보

3. app/api/v1_assets.py는 symbol/market 참조 최소 제거만 수행 (list_assets 재작성은 REQ-013 범위)

   • 이유: 이 batch는 DB/도메인 레이어 변경에 집중; list_assets 로직 전면 재작성은 BAT-002에서 처리
   • 임시 조치: portfolios JOIN assets 쿼리로 symbol을 asset.symbol로 대체, market 단수 필드 제거

4. MarketCode Enum 검증은 API 레이어(이 batch에서는 repository 구현 내)에서만 수행, DB CHECK constraint 없음

   • REQ-009 명세 준수: app-layer Enum, DB CHECK constraint 미사용

Edge Cases

• portfolios.market IS NULL인 기존 행: ARRAY_AGG(DISTINCT market) FILTER (WHERE market IS NOT NULL) → 빈 배열 '{}' 저장 (REQ-014 Requirement 명시)
• 동일 symbol의 여러 portfolio 행: GROUP BY symbol로 단일 assets 행 생성, ARRAY_AGG(DISTINCT market) 집약 (REQ-014 R-1, A-1)
• rev-B rollback 시: portfolios.symbol, portfolios.market이 복원되고 asset_id와 assets 테이블 변경이 모두 되돌아감 (단일 트랜잭션 보장)
• symbol/market 참조 코드 누락: grep -rn "\.symbol\|\.market\|p\.symbol\|p\.market" app/ 전수 조사 후 수정 — AttributeError로 런타임에서 즉시 탐지 가능

Architecture Impact

• project-structure.md: asset CRUD Protocol 추가 (domain layer 확장) — REQ-015에서 문서화
• runtime-flows.md: migration flow 신규 추가 — REQ-015에서 문서화

Reference Doc Update Plan

• project-structure.md: REQ-015(BAT-002)에서 처리
• runtime-flows.md: REQ-015(BAT-002)에서 처리