portfolio-hub/docs/srs/Interface/req-010_admin-asset-catalog-crud.md

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): dcy-003 옵션 B(path 명명 분리) 결정에 따라 REQ-013(GET /v1/assets 포트폴리오 조회)이 Deprecated(2026-05-20) 처리되어 path 충돌 우려가 해소됨. GET /v1/assets는 admin catalog 조회 전용으로 본 REQ에서 다루며, dcy-001 batch design 단계에서 본 REQ에 GET 명세를 보강(change-req)하거나 별도 신규 REQ로 분리한다. 포지션 조회 GET /v1/portfolios는 dcy-003의 별도 신규 REQ로 분리 예정.
• 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 사용