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,120 @@
+# REQ-010: admin asset catalog CRUD
+
+- Status: Approved
+- Type: Interface
+- Priority: High
+- Owner: Justin Ko
+
+## Intent
+- admin이 CLI 및 HTTP API를 통해 거래 가능한 종목을 `assets` catalog에 등록·수정·비활성화할 수 있도록 한다.
+- admin이 아닌 user 또는 daemon의 catalog 직접 변경 시도를 HTTP 403으로 거부한다(NFR-3).
+
+## Requirement
+- CLI: `pfhub asset create <symbol> [--markets <codes>] [--display-name <name>]` — admin 권한 필요. markets 값은 쉼표 구분 MarketCode Enum 값.
+- CLI: `pfhub asset list [--inactive]` — active asset만 기본 출력; `--inactive` 지정 시 inactive 포함 전체 출력.
+- CLI: `pfhub asset update <symbol> [--markets <codes>] [--display-name <name>]` — admin 권한 필요.
+- CLI: `pfhub asset deactivate <symbol> [--force]` — admin 권한 필요. `--force` 없으면 확인 프롬프트 출력.
+- HTTP API: `POST /v1/assets` — admin token 필요. request body에 symbol, markets, display_name. 성공 시 HTTP 201 + 생성된 asset 반환.
+- HTTP API: `PATCH /v1/assets/{asset_id}` — admin token 필요. markets, display_name 변경 가능. 성공 시 HTTP 200 + 갱신된 asset 반환.
+- HTTP API: `PATCH /v1/assets/{asset_id}/deactivate` — admin token 필요. `status='inactive'`로 변경. 성공 시 HTTP 200.
+- admin 이외의 token으로 POST/PATCH 요청 시 HTTP 403을 반환한다.
+- asset hard DELETE는 제공하지 않는다(soft delete 전용).
+- `app/cli/commands/asset.py` 신규 파일로 pfhub asset 커맨드 그룹을 구현한다.
+- `app/cli/main.py`에 `app.add_typer(asset_app, name="asset")`을 추가한다.
+- `app/services/` 또는 관련 서비스에 asset create/update/deactivate/list 로직을 추가한다.
+
+## Acceptance Criteria
+1. Given admin 토큰, When `pfhub asset create "005930.KS" --markets KRX,NXT`, Then assets catalog에 symbol='005930.KS', markets=['KRX','NXT'], status='active' 항목이 생성된다.
+2. Given admin 토큰, When `pfhub asset list`, Then status='active'인 asset 목록이 출력된다.
+3. Given active/inactive asset 모두 존재, When `pfhub asset list --inactive`, Then inactive 포함 전체 목록이 출력된다.
+4. Given admin 토큰, When `pfhub asset deactivate "005930.KS" --force`, Then 해당 asset의 status가 'inactive'로 변경된다.
+5. Given admin 토큰, When `POST /v1/assets` with valid symbol and markets, Then HTTP 201과 생성된 asset_id가 반환된다.
+6. Given admin 토큰, When `PATCH /v1/assets/{asset_id}` with updated markets, Then HTTP 200과 변경된 asset이 반환된다.
+7. Given admin 토큰, When `PATCH /v1/assets/{asset_id}/deactivate`, Then HTTP 200과 status='inactive'가 반환된다.
+8. Given non-admin token (user 또는 service token), When `POST /v1/assets` 요청, Then HTTP 403이 반환된다.
+
+## Impacted Area
+- Docs:
+  - docs/project-structure.md — `app/cli/` Command groups에 `asset` 추가 (REQ-015에서 처리)
+  - docs/interface-contract.md — POST/PATCH /v1/assets 엔드포인트 명세 추가 (REQ-015에서 처리)
+- Modules:
+  - `app/cli/commands/asset.py` — 신규 파일, pfhub asset 커맨드 그룹
+  - `app/cli/main.py` — `app.add_typer(asset_app, name="asset")` 추가
+  - `app/services/` — asset create/update/deactivate/list 서비스 메서드 추가
+  - `app/api/v1_assets.py` — POST, PATCH 라우트 추가
+  - `app/schemas/` — `CreateAssetRequest`, `UpdateAssetRequest`, `AssetCatalogResponse` 스키마 추가
+- Tests:
+  - `tests/test_asset_catalog.py` (신규) — admin CRUD CLI/API AC 검증, non-admin 403 검증
+
+## Notes
+- `pfhub asset list`의 HTTP 대응(catalog 전용 GET)은 별도 admin 전용 엔드포인트로 구현하거나, GET /v1/assets에 `?mode=catalog` 파라미터로 분기할 수 있다. 설계 결정은 batch design 단계에서 확정한다. REQ-013(GET /v1/assets 포트폴리오 조회)과 충돌하지 않도록 주의한다.
+- deactivate 후 해당 asset을 참조하는 기존 portfolio는 보존된다. 신규 portfolio 생성만 거부(REQ-012에서 처리).
+- REQ-009 선행 필요.
+- Source: dcy-001 FR-2, NFR-3
+
+## 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-2, NFR-3을 Interface REQ로 분리; admin catalog CRUD CLI + HTTP API 정의
+
+#### Acceptance Criteria Delta
+- Added:
+  - AC-1~8 최초 작성
+
+#### Impacted Area Delta
+- Docs:
+  - docs/project-structure.md, docs/interface-contract.md — 최초 지정
+- Modules:
+  - app/cli/commands/asset.py, app/cli/main.py, app/services/, app/api/v1_assets.py, app/schemas/ — 최초 지정
+- 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 선행 의존성 확인
+
+#### Validation Plan
+- pytest로 AC-1~8 검증; CLI는 CliRunner, HTTP는 TestClient 사용