---
id: "req-0003"
status: approved
discovery: "dcy-0003"
criteria:
  create:
    - "ac-0013"
    - "ac-0014"
    - "ac-0015"
    - "ac-0016"
    - "ac-0017"
    - "ac-0018"
    - "ac-0019"
    - "ac-0020"
    - "ac-0021"
    - "ac-0022"
    - "ac-0023"
  update: []
  retire: []
  satisfy: []
---

# 전략 API v1 이전 및 관리자 전역 카탈로그 권한 분리

## Objective

전역 전략 카탈로그의 일반 조회·선택과 관리자 관리를 versioned API에서 분리하고, 안정적인 전략 identity·revision·상태·참조 무결성을 유지하면서 포트폴리오의 ID-only 선택 계약과 downstream 적용 시점 경계를 제공한다.

## Scope

- 일반 사용자와 admin의 active 전략 목록·상세 조회를 `/v1/strategies`로 제공한다.
- active·inactive 전체 전략의 생성·조회·제자리 수정·상태 변경·미참조 삭제를 `/v1/admin/strategies`의 admin 전용 권한으로 제공한다.
- 전략의 안정적인 ID, 양의 revision, active/inactive 상태와 동시 변경 시 원자적 일관성을 보장한다.
- `/v1/portfolios`와 legacy `/portfolios`의 생성·수정을 기존 active `strategy_id` 전용으로 통일하고 간접 전략 생성을 제거한다.
- 요청의 제거된 전략 이름·파라미터 필드는 거부하되 기존 downstream 응답 필드는 최신 공유 설정과 revision으로 유지한다.
- 참조 중 전략의 hard delete를 거부하고 inactive retirement 및 기존 참조 보존을 지원한다.
- 비버전 `/strategy-sets`를 alias 없이 제거하고 운영자 CLI가 HTTP와 같은 상태·참조 무결성을 우회하지 않게 한다.
- 기본 active `target_value`/`{}` 전략을 idempotent Alembic data migration으로 생성하거나 기존 동일 row를 재사용한다.
- portfolio-hub의 commit된 최신 revision 제공 시점과 trex-core 슬롯의 재생성·정기 갱신 적용 시점을 구분한다.
- 동시 PATCH, 선택·상태 변경·삭제 경합 및 stale 거래 snapshot 저장에서도 derived field, revision, 현재 참조와 ledger 원자성을 보존한다.

## Constraints

- 전역 active 카탈로그가 신규 선택 권위이며 legacy `avabile_strategies`는 선택 권한 근거가 아니다.
- 외부 오류 계약은 미존재 `404`, inactive 신규 선택과 참조 중 삭제 `409`, 제거 필드·malformed 입력 `422`, 권한 부족 `403`으로 구분한다.
- 기존 inactive 전략 참조는 보존하며 자동 이전하거나 삭제하지 않는다.
- portfolio-hub는 downstream daemon을 강제 reload/restart하거나 설정을 push하지 않고 이미 생성된 슬롯·주문·완료 거래를 소급 재해석하지 않는다.
- 내부 DB 테이블명 `strategy_sets`는 유지한다.

### Current Implementation Assessment

- 이 REQ는 요청자 지시에 따라 사후 승인 상태로 포착됐다. `approved`/`active`는 normative authority이며 ProofLine 구현 chronology나 satisfaction marker가 아니다.
- 현재 `main` 기준 HEAD `5fc389dea8f05c6f711ecfe874f055979af5e58d` 위 미커밋 working tree에 portfolio-hub 범위의 구현·테스트·문서 변경이 존재한다.
- 2026-08-15 현재 scoped 재실행 `uv run python -m pytest -q tests/test_v1_strategies.py tests/test_strategy_catalog_migration.py tests/test_v1_portfolios_crud.py tests/test_strategy_catalog_postgres_integration.py tests/test_cli.py`는 `70 passed, 4 skipped`였다. 이어 `PORTFOLIOHUB_RUN_POSTGRES_INTEGRATION=1 uv run python -m pytest -q tests/test_strategy_catalog_postgres_integration.py`를 실행해 실제 PostgreSQL integration `4 passed`를 확인했다.
- `ac-0013`~`ac-0021`, `ac-0023`은 현재 working-tree 구현과 executable tests가 대응한다. 다만 `ac-0014`의 비-admin mutation별 독립 negative test, `ac-0017`의 제거 요청 필드·응답 호환 필드 전용 test, `ac-0023`의 ledger INSERT 실패 fault-injection rollback test는 `PARTIAL`이며, exact implementation commit과 ProofLine delivery closure도 없다.
- `ac-0022`의 portfolio-hub 경계(최신 revision 조회 제공, 강제 push/reload 부재)는 구현되어 있으나, trex-core가 다음 슬롯 재생성·정기 갱신에서 최신 revision을 실제 반영한다는 cross-repository end-to-end seam은 이 저장소 증거만으로 확인되지 않아 `UNVERIFIED`다.

## Non-Goals

- trex-core의 정확한 일일 슬롯 갱신 시각 또는 scheduler 구현 변경
- downstream daemon 강제 reload·restart 또는 설정 push
- 기존 슬롯·주문·완료 거래의 소급 재해석
- 내부 `strategy_sets` 테이블명 변경
- 운영 배포, production data migration 실행, push, PR, 원격 main 반영 또는 release 승인
- 이 사후 문서로 과거 구현에 ProofLine 정식 implementation/delivery chronology나 terminal closure를 소급 부여하는 행위