portfolio-hub/docs/batches/bat-002_20260519_asset-catalog-api-completion/planning.md

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 완료 후 실제 구현을 기준으로 작성