# BAT-002 Planning

- Status: verified
- Batch: BAT-002
- Profile: standard

## Included REQ
- REQ-010: admin asset catalog CRUD (Interface, High)
- REQ-012: portfolio 생성 CLI catalog 검증 (Interface, High)
- REQ-013: GET /v1/assets 토큰 타입별 분기 재정의 (Interface, High)
- REQ-015: asset catalog 도입 baseline 문서 갱신 (Documentation, Low)

## Delivery Plan

### 단계 1 — REQ-010: admin asset catalog CRUD
1. `app/schemas/v1.py`에 `AssetCreateRequest`, `AssetUpdateRequest`, `AssetResponse` 스키마 추가
2. `app/api/v1_assets.py`에 `POST /v1/assets`, `PATCH /v1/assets/{id}`, `PATCH /v1/assets/{id}/deactivate` 엔드포인트 추가 (admin 권한 필요)
3. `app/cli/commands/asset.py` 신규 파일 — `pfhub asset create/list/update/deactivate` typer 커맨드 구현
4. `app/cli/main.py`에 asset 커맨드 그룹 등록
5. `tests/test_asset_catalog.py` 확장 — REQ-010 AC-1~8

### 단계 2 — REQ-013: GET /v1/assets 토큰 타입별 분기
1. `app/api/v1_assets.py` list_assets 핸들러 재작성 — token_type 분기 (service/user/admin)
2. `app/repositories/postgres.py` list_portfolios_with_strategies — `?market=<code>` 필터 지원 추가
3. `tests/test_v1.py` 갱신 및 신규 토큰 분기 케이스 추가 — REQ-013 AC-1~7

### 단계 3 — REQ-012: portfolio create catalog 검증
1. `app/services/portfolio_service.py` create_portfolio에 `get_asset_by_id()` 호출 + active 검증 추가
2. `app/cli/commands/portfolio.py` create 커맨드에 `--symbol` 옵션 추가 (asset_id 조회 경로)
3. `tests/test_asset_catalog.py` 확장 / `tests/test_portfolio_uuid.py` 또는 `tests/test_cli.py` 갱신 — REQ-012 AC-1~4

### 단계 4 — REQ-015: baseline 문서 갱신
1. `docs/data-model.md` — assets 엔티티, portfolios asset_id FK 갱신
2. `docs/interface-contract.md` — POST/PATCH /v1/assets, GET /v1/assets 토큰 분기 명세 추가
3. `docs/runtime-flows.md` — GET /v1/assets 토큰 분기 흐름, admin asset CRUD 흐름 추가
4. `docs/project-structure.md` — pfhub asset 커맨드 그룹 및 신규 api 모듈 반영

### 단계 5 — 전체 테스트 suite regression 검증
- `.venv/bin/python -m pytest --tb=short` 전체 실행 — regression 없음 확인

## Dependencies
- Internal:
  - BAT-001(verified): assets 테이블, postgres asset CRUD 5종, Portfolio.asset_id FK 모두 구현 완료 — 선행 조건 충족
  - REQ-010(단계 1) 완료 후 REQ-013(단계 2) 착수 — `app/api/v1_assets.py` 동일 파일 순서 의존
  - REQ-010(단계 1) 완료 후 REQ-012(단계 3) 착수 — assets catalog 존재가 검증 선행 조건
- External:
  - 없음

## Design Gate
- Design Required Before Implementation: yes
- Reason: (1) REQ-013 토큰 분기 아키텍처 — service/user/admin 각 경로에서 repository 호출 패턴이 다르고 기존 daemon 인증 흐름(test_daemon_assignment.py)과의 정합성 설계 필요; (2) REQ-010 CLI 구조 — `app/cli/commands/asset.py` 신규 파일 구조 및 `pfhub asset` 커맨드 그룹 등록 방식 결정 필요; (3) REQ-012 검증 위치 — CLI vs 서비스 레이어 중 어디서 catalog 검증을 수행할지 결정 필요 (현재 계획: 서비스 레이어)

## Milestones
1. REQ-010: pfhub asset CLI + admin HTTP API 3개 엔드포인트 완성 + AC-1~8 통과
2. REQ-013: GET /v1/assets 토큰 분기 재작성 + AC-1~7 통과
3. REQ-012: portfolio create catalog 검증 + AC-1~4 통과
4. REQ-015: baseline 문서 4종 갱신 + AC-1~4 통과
5. 전체 pytest suite regression 통과

## Risks
- R-1(High): REQ-010과 REQ-013이 `app/api/v1_assets.py` 동일 파일을 수정 — 구현 순서를 단계 1→2로 엄수해야 충돌 없음. 대응: planning 단계에서 순서 명시, 단계별 커밋 분리
- R-2(Medium): REQ-013 list_assets 재작성이 기존 service token 전용 동작을 변경 — `test_daemon_assignment.py`, `test_v1.py` regression 위험. 대응: 단계 2 완료 직후 전체 pytest 실행으로 조기 탐지
- R-3(Medium): REQ-012 service layer 검증 추가 시 기존 FakeRepo에 `get_asset_by_id/symbol` 스텁 미구현으로 테스트 실패 가능. 대응: 단계 3 착수 전 FakeRepo 업데이트 체크리스트 준비
- R-4(Low): REQ-015 runtime-flows.md — GET /v1/assets 분기 흐름 다이어그램이 복잡해질 수 있음. 대응: 단계 4는 단계 2 완료 후 실제 구현을 기준으로 작성