# 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)에서 처리