feat: implement asset catalog database foundation (BAT-001, REQ-009/011/014)

Asset Catalog Model Implementation (BAT-001): - Introduce assets table with UUID PK, symbol UNIQUE, markets TEXT[] array - Define MarketCode enum (KRX, NXT, SOR, NASDAQ, NYSE, UPBIT, BITHUMB) - Add Asset domain model with catalog properties - Implement asset CRUD protocols in portfolio_repository - Add PostgreSQL asset CRUD operations with GIN index on markets Portfolio Model Refactoring (REQ-011): - Add portfolios.asset_id UUID FK to assets(asset_id) ON DELETE RESTRICT - Remove portfolios.symbol and portfolios.market columns - Update Portfolio domain model to reference asset_id instead of symbol/market - Refactor all portfolio queries to JOIN assets catalog - Update all repository methods to use asset references Data Migration (REQ-014): - Create 20260519_0017 Alembic revision for assets table creation - Create 20260519_0018 Alembic revision for atomic data migration: * Extract unique symbol combinations from portfolios * Aggregate markets using ARRAY_AGG(DISTINCT market) * Populate assets catalog with extracted data * Update portfolios.asset_id to reference new assets * Remove legacy symbol/market columns in single transaction - Implement migration with rollback support Requirements Approved (REQ-001~008): - REQ-001~008 transitioned from Proposed to Approved - Complete tag model requirement set with implementation readiness New Requirements Approved (REQ-009~015): - REQ-009: assets table schema (approved, included in BAT-001) - REQ-010: admin asset catalog CRUD (approved, future BAT-002) - REQ-011: portfolios asset_id FK (approved, included in BAT-001) - REQ-012: portfolio create catalog validation (approved, future BAT-002) - REQ-013: GET /v1/assets token branching (approved, future BAT-002) - REQ-014: portfolios data migration (approved, included in BAT-001) - REQ-015: asset catalog baseline docs (approved) Code Changes: - app/domain/models.py: Add Asset model, MarketCode enum, Portfolio asset_id FK - app/repositories/portfolio_repository.py: Define asset CRUD protocol - app/repositories/postgres.py: Implement asset operations with full CRUD - app/api/v1_assets.py: Remove symbol/market direct references - app/cli/commands/portfolio.py: Update portfolio commands for asset references - app/schemas/portfolio.py: Update portfolio schema with asset_id - All portfolio operations throughout codebase: Use asset references Testing: - Add test_asset_catalog.py for asset CRUD operations - Verify REQ-009 AC-1~5 (asset catalog creation, lookup, uniqueness) - Verify REQ-011 AC-1~5 (FK constraint, portfolio asset reference) - Verify REQ-014 AC-1~6 (migration atomicity, data correctness, rollback) - Update existing tests for asset model usage Documentation: - Create BAT-001 batch documents (planning, design, implementation, verification) - Update dcy-001 with implementation details and confirmed architecture - Add 8 new requirement documents (REQ-009~015) - Update docs/discovery/index.md with batch entry Impact: - Database: assets catalog table, portfolios refactored to reference assets - Migration: 2 new Alembic revisions (0017 assets, 0018 portfolio migration) - API: Symbol/market now accessed through asset references - CLI: Portfolio commands require asset reference pattern - All existing portfolio data preserved and correctly migrated
2026-05-19 15:59:20 +00:00
parent 1082f041a1
commit e2226e28b6
40 changed files with 2118 additions and 168 deletions
@@ -0,0 +1,102 @@
+# REQ-012: portfolio 생성 CLI catalog 검증
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- user가 `pfhub portfolio create` CLI로 portfolio를 생성할 때 지정한 asset이 catalog에 active 상태로 존재하는지 검증하여, 미등록 또는 비활성 asset 기반의 portfolio 생성을 방지한다.
+
+## Requirement
+- `pfhub portfolio create` 명령에 `--asset-id <uuid>` 또는 `--symbol <symbol>` 옵션을 추가하여 catalog asset을 지정하도록 한다.
+- portfolio 생성 전 지정된 `asset_id`(또는 symbol로 조회한 asset_id)가 `assets` catalog에 `status='active'`로 존재하는지 검증한다.
+- catalog에 없거나 `status='inactive'`인 asset이면 오류 메시지와 함께 생성을 거부한다.
+- `app/services/portfolio_service.py`의 `create_portfolio`에 asset 검증 로직을 추가한다.
+- user portfolio CRUD HTTP API(POST /portfolios 등)는 이 REQ 범위 밖이다(별도 Discovery에서 처리).
+
+## Acceptance Criteria
+1. Given active asset이 catalog에 존재, When `pfhub portfolio create <name> --asset-id <asset_id> --user <username>`, Then portfolio가 생성되고 해당 asset_id로 연결된다.
+2. Given 존재하지 않는 asset_id, When `pfhub portfolio create` with 미등록 asset_id, Then "asset not found" 오류가 출력되고 portfolio가 생성되지 않는다.
+3. Given `status='inactive'`인 asset_id, When `pfhub portfolio create` with 해당 asset_id, Then "asset is inactive" 오류가 출력되고 portfolio가 생성되지 않는다.
+4. Given `--symbol <symbol>` 옵션 사용, When 해당 symbol이 catalog에 active로 존재, Then symbol로 asset_id를 조회하여 portfolio를 생성한다.
+
+## Impacted Area
+- Docs: 없음 (별도 문서 갱신 불필요)
+- Modules:
+  - `app/cli/commands/portfolio.py` — create 명령에 `--asset-id` / `--symbol` 옵션 추가
+  - `app/services/portfolio_service.py` — create_portfolio에 catalog 검증 로직 추가
+- Tests:
+  - `tests/test_asset_catalog.py` (신규) — catalog 검증 AC-1~4 검증
+
+## Notes
+- REQ-009(assets 테이블), REQ-011(portfolios 재설계) 선행 필요.
+- HTTP API를 통한 portfolio 생성 시 catalog 검증 정책은 동일하게 적용되어야 하나, HTTP mutation API는 Out of Scope(별도 Discovery 처리 예정)이다.
+- Source: dcy-001 FR-4
+
+## Change Log
+
+### 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-4를 Interface REQ로 분리; portfolio create CLI catalog 검증 정의
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~4 최초 작성
+
+#### Impacted Area Delta
+- Docs:
+  - 없음
+- Modules:
+  - app/cli/commands/portfolio.py, app/services/portfolio_service.py — 최초 지정
+- Tests:
+  - 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, REQ-011 선행 의존성 확인
+
+#### Validation Plan
+- pytest CliRunner로 AC-1~4 검증