Add ProofLine criteria documentation and Strategy Catalog v1 implementation

- Add acceptance criteria documentation (AC-0013 through AC-0023)
- Add Line-0003 discovery documentation
- Implement Strategy Catalog v1 with new database migration
- Update portfolio API endpoints and schemas
- Refactor strategy and portfolio services
- Add strategy management CLI commands
- Update domain models with strategy catalog support
- Add comprehensive tests for v1 strategies
- Update design documentation (data model, interfaces, runtime flows)

.proofline/lines/line-0003/evidence/implementation-complete.md

@@ -0,0 +1,61 @@
+# 구현 완료 — GitHub Issue #26 비정식 증적
+
+> 이 문서는 ProofLine canonical lifecycle artifact가 아니다. #26 구현 당시 GitHub 댓글을 출처와 함께 원문 보존한 비정식 증적이다.
+> 이 증거는 로컬 구현·검증 상태를 기록하지만 ProofLine 정식 implementation chronology, delivery closure, push, PR, 원격 main 반영, release 또는 deployment 완료를 소급 증명하지 않는다.
+> Source: https://github.com/fourblocks2020/portfolio-hub/issues/26#issuecomment-5291927258
+> Comment ID: `IC_kwDOR4l8PM8AAAABO2xm2g`
+> Author: `genichin`
+> Created: `2026-08-14T09:48:42Z`
+> Original body SHA-256: `c3bc9a3ad6c9cc6678ed700a11add03b1f5abe71645a21e157dc091faec28f10`
+> Original body boundary: 아래 `---` 다음 byte부터 파일 끝까지가 GitHub 원문 body다.
+
+---
+
+## 구현 완료
+
+이슈 #26 **전략 API v1 이전 및 관리자 전역 카탈로그 권한 분리**의 승인 범위를 로컬 `main` 작업 트리에 구현하고 실제 PostgreSQL 검증 및 독립 QC까지 완료했습니다.
+
+### 구현 내용
+
+- 비버전 `/strategy-sets` 제거 및 전략 API `/v1` 이전
+  - 일반 사용자: active 전략 조회 전용 `/v1/strategies`
+  - 관리자: 전체 전략 카탈로그 CRUD `/v1/admin/strategies`
+- 전략 카탈로그에 `active/inactive` 상태와 revision 도입
+- 신규 전략 revision 1, 실질적 PATCH만 revision 증가, no-op 유지
+- 동시 PATCH를 `FOR UPDATE`로 직렬화하고 최신 name/config 기준으로 derived `nick` 계산
+- 포트폴리오 create/update에서 기존 active `strategy_id`만 선택
+- `strategy_name`·`strategy_params`를 통한 간접 전략 생성 차단
+- 전략 선택의 `FOR SHARE`와 포트폴리오 저장을 같은 트랜잭션으로 묶어 inactivate/delete race 차단
+- 전략 DELETE의 `FOR UPDATE`·두 참조 형태 검사·삭제를 한 트랜잭션으로 통합
+- stale BUY/SELL snapshot이 전략 선택 컬럼을 덮어쓰지 못하도록 거래 저장 책임 분리
+- 거래 portfolio UPDATE와 ledger INSERT 원자화
+- 포트폴리오 응답에 최신 `strategy_revision` 노출
+- 기본 `target_value`/`{}` 전략 migration과 runtime nick 파생 규칙 통일
+- CLI, 문서, migration 및 동시성 회귀 테스트 갱신
+
+### 실제 검증 결과
+
+- 이슈 집중 회귀: `99 passed`
+- 실제 PostgreSQL 동시성·migration 통합 테스트: 최종 `4 passed`
+  - 동시 partial PATCH의 nick/revision 일관성
+  - 전략 선택 대 DELETE race의 orphan 방지
+  - stale A snapshot → B 선택 → A 삭제 → stale BUY 저장 후 B 유지
+  - 신규 DB 전체 Alembic upgrade 및 head 재실행
+- 관련 최종 회귀: `75 passed`
+- 알려진 기존 문제 파일 제외 광범위 회귀: `608 passed, 3 skipped`
+- 독립 최종 QC 재실행: PostgreSQL `4 passed`, focused `37 passed, 4 skipped`
+- Python compile, `git diff --check`, 변경 핵심 파일 Ruff 검사: 통과
+- 독립 QC 최종 판정: **PASS**
+
+전체 broad 실행에 남은 3건은 저장소 밖 `temp/deleted_20260813/.worktrees`를 스캔하는 기존 환경 오염 실패로, 이번 변경에 의한 회귀가 아닙니다.
+
+### 비차단 후속 권고
+
+- PostgreSQL 통합 테스트 cleanup을 fixture/`finally` 기반으로 강화하면 테스트가 중간 실패·중단될 때의 잔여 fixture 방지를 개선할 수 있습니다. 현재 성공 경로 cleanup은 QC 전후 잔여 레코드 수가 동일해 정상입니다.
+
+### 완료 경계
+
+- 완료: 로컬 구현, 실제 테스트, migration 검증, 문서 갱신, 독립 QC
+- 미수행: 커밋, push, PR, 원격 `main` 반영, 이미지 게시, 운영 설정 변경, 배포, 릴리스
+
+현재 변경은 기준 HEAD `5fc389dea8f05c6f711ecfe874f055979af5e58d`의 로컬 `main` 작업 트리에 **미커밋 상태**로 보존되어 있습니다. 이 댓글은 제품 구현·검증 완료를 뜻하며 배포·릴리스 또는 이슈 lifecycle closure를 뜻하지 않습니다.

.proofline/lines/line-0003/evidence/implementation-progress.md

@@ -0,0 +1,65 @@
+# 구현 진행 상황 — GitHub Issue #26 비정식 증적
+
+> 이 문서는 ProofLine canonical lifecycle artifact가 아니다. #26 구현 당시 GitHub 댓글을 출처와 함께 원문 보존한 비정식 증적이다.
+> 이 증거는 로컬 구현·검증 상태를 기록하지만 ProofLine 정식 implementation chronology, delivery closure, push, PR, 원격 main 반영, release 또는 deployment 완료를 소급 증명하지 않는다.
+> Source: https://github.com/fourblocks2020/portfolio-hub/issues/26#issuecomment-5291151212
+> Comment ID: `IC_kwDOR4l8PM8AAAABO2CPbA`
+> Author: `genichin`
+> Created: `2026-08-14T08:21:45Z`
+> Original body SHA-256: `539cfe82e6f8281c5821c52f484a4078b116e52f5696ee0f9ea502f27b42cfeb`
+> Original body boundary: 아래 `---` 다음 byte부터 파일 끝까지가 GitHub 원문 body다.
+
+---
+
+## 구현 진행 상황
+
+- **대상:** 전략 API v1 이전 및 관리자 전역 카탈로그 권한 분리
+- **브랜치:** `main`
+- **기준:** `main` (`5fc389dea8f05c6f711ecfe874f055979af5e58d`)
+- **상태:** 로컬 구현·검증·독립 QC 완료 (PASS)
+- **최종 업데이트:** 2026-08-14 18:47 KST
+
+### 구현 계획 및 작업 목록
+
+- [x] 전략 카탈로그 데이터 모델과 저장소 기능 확장
+  - 안정적인 전략 ID를 유지하면서 `active/inactive` 상태와 원자적으로 증가하는 revision을 저장·조회하고, 동시 PATCH에서도 `name/config/nick` 일관성을 보장한다.
+- [x] `/v1/strategies` 일반 조회 API 구현
+  - 일반 사용자는 active 전략의 목록과 상세만 조회할 수 있도록 한다.
+- [x] `/v1/admin/strategies` 관리자 관리 API 구현
+  - admin만 전체 목록 조회, 생성, 제자리 수정·상태 변경, 미참조 전략 삭제를 수행할 수 있도록 한다.
+- [x] 포트폴리오 전략 선택을 기존 active `strategy_id` 전용으로 변경
+  - `/v1/portfolios`와 legacy `/portfolios` 모두 생성 시 전략 ID를 필수로 받고, 수정 시에도 기존 active 전략만 선택하며 선택·저장·삭제 race를 DB 트랜잭션과 row lock으로 차단한다.
+- [x] 동시성·참조 무결성 회귀 검증
+  - 동시 전략 PATCH와 포트폴리오 선택·전략 삭제 경합에서도 derived `nick`, revision, active 선택, orphan 방지가 유지되는지 실제 PostgreSQL로 검증한다.
+- [x] 일반 사용자의 간접 전략 생성 및 비버전 API 제거
+  - 포트폴리오 요청의 `strategy_name`·`strategy_params`를 422로 거부하고 비버전 `/strategy-sets` 라우트를 제거한다.
+- [x] 기본 전략 데이터 migration과 운영자 CLI 무결성 반영
+  - 기본 active `target_value`/`{}` 전략을 중복 없이 생성·재사용하고, CLI가 상태·revision·참조 무결성을 우회하지 않도록 한다.
+- [x] 권한·상태·revision·오류·삭제·호환성 회귀 테스트 추가 및 실행
+  - 승인된 HTTP 403/404/409/422 계약, 참조 보존, 간접 생성 차단과 migration idempotency를 실제 테스트로 검증한다.
+- [x] 인터페이스·런타임·데이터 모델 문서 갱신 및 전체 변경 검수
+  - 새 API 계약과 비버전 경로 제거, downstream 적용 시점의 경계를 문서화하고 전체 diff와 회귀를 점검한다.
+
+### 진행 기록
+
+- 2026-08-14 17:21 KST — 이슈 #26의 승인된 범위와 수용 기준을 기준으로 구현 계획을 확정했다.
+- 2026-08-14 17:21 KST — 별도 구현 브랜치 없이 `main` (`5fc389d`)에서 구현·검증을 시작했다.
+- 2026-08-14 17:32 KST — v1 전략 API, 전략 상태·revision 저장소, ID 전용 포트폴리오 선택, 비버전 라우트 제거 및 migration의 초기 구현을 작업트리에 반영했다. 아직 검증 전이므로 체크하지 않았다.
+- 2026-08-14 17:33 KST — 첫 전체 회귀 실행 결과 `571 passed, 27 failed, 6 skipped`였다. 새 필수 `strategy_id` 계약에 맞지 않는 기존 테스트·CLI와 미완료 전용 테스트·문서를 보완한 뒤 다시 검증한다.
+- 2026-08-14 17:44 KST — CLI·기존 테스트·전용 API/migration 테스트·문서를 보완했다. 이슈 집중 회귀는 `166 passed`, 전체 제품 테스트는 기존 stale worktree 정적검사 3건을 제외하고 `606 passed, 3 skipped`였다.
+- 2026-08-14 17:49 KST — 실제 PostgreSQL 신규 DB에서 Alembic 전체 upgrade와 head 재실행을 검증했다. 기본 `target_value`/`{}` 전략은 active, revision 1로 한 건 생성됐다.
+- 2026-08-14 17:50 KST — 실제 PostgreSQL 기반 HTTP 흐름에서 admin 생성·PATCH·삭제, 일반 조회·권한 거부, ID 유지와 revision 증가를 검증했다.
+- 2026-08-14 17:51 KST — 검증 중 발견한 inactive 신규 전략이 revision 2로 시작하는 결함을 수정해 실제 DB와 회귀 테스트에서 revision 1을 확인했다.
+- 2026-08-14 17:52 KST — 독립 QC가 동시 PATCH의 derived `nick` 불일치 가능성과 전략 선택·삭제 사이의 참조 race를 HIGH로 판정해 반려했다. 특히 참조 race 수정은 포트폴리오 mutation과 전략 삭제를 같은 DB 트랜잭션/row lock 경계로 묶는 작업이 추가로 필요해, 승인된 구현 계획 보완이 필요하므로 구현을 중지했다.
+- 2026-08-14 18:17 KST — 요청자가 트랜잭션·row lock·동시성 테스트를 구현 계획에 추가하고 QC 지적 전체를 수정하도록 명시 승인해 구현을 재개했다.
+- 2026-08-14 18:34 KST — 전략 PATCH를 `FOR UPDATE` 트랜잭션으로 직렬화하고, active 전략 선택의 `FOR SHARE` lock과 포트폴리오 INSERT/UPDATE를 같은 트랜잭션으로 묶었다. 전략 DELETE도 `FOR UPDATE`·참조 검사·삭제를 한 트랜잭션으로 통합했다.
+- 2026-08-14 18:34 KST — 포트폴리오 응답에 최신 `strategy_revision`을 추가하고, migration 기본 전략 nick을 runtime SHA-1 규칙과 일치시켰다.
+- 2026-08-14 18:34 KST — 집중 회귀 `99 passed`, 실제 PostgreSQL 동시 PATCH·선택/삭제 race·신규 DB migration 재실행 통합 테스트 `3 passed`, 알려진 외부 정적 sweep 및 기존 ledger fixture 파일을 제외한 광범위 회귀 `607 passed, 3 skipped`를 확인했다. Python compile, `git diff --check`, 변경 핵심 파일 Ruff 검사도 통과했다.
+- 2026-08-14 18:34 KST — 전체 원문 실행은 `609 passed, 3 failed, 3 errors, 3 skipped`였다. 실패 3건은 저장소 밖 `temp/deleted_20260813/.worktrees`를 스캔하는 기존 정적 테스트이고, error 3건은 기존 ledger integration fixture가 현재 DB의 필수 `owner_user_id`를 넣지 않는 문제로 이번 전략 변경과 분리했다. 독립 재-QC를 요청했다.
+- 2026-08-14 18:40 KST — 독립 재-QC는 거래 저장 `save()`가 stale 포트폴리오 snapshot의 전략 A를 다시 써, B로 선택 변경 후 삭제된 A 참조를 되살릴 수 있음을 HIGH로 재현해 FAIL 판정했다. 이전 findings는 모두 해소된 것으로 확인됐다.
+- 2026-08-14 18:43 KST — `save()`에서 전략 선택 컬럼 쓰기를 제거하고 balance/price/buffer/timestamp UPDATE와 ledger INSERT를 단일 트랜잭션으로 묶었다. A snapshot→B 선택→A 삭제→stale BUY 저장 후에도 B가 유지되고 A가 없는 실제 PostgreSQL 회귀 테스트를 추가했다.
+- 2026-08-14 18:43 KST — 실제 PostgreSQL 통합 테스트 `4 passed`, 관련 회귀 `75 passed`, 알려진 기존 문제 파일 제외 광범위 회귀 `608 passed, 3 skipped`, 핵심 Ruff·compile·diff 검사를 통과해 최종 독립 재-QC를 요청했다.
+- 2026-08-14 18:47 KST — 최종 독립 재-QC가 PASS를 판정했다. stale BUY/SELL snapshot의 삭제 전략 참조 복원 문제가 완전히 해소됐고, 거래 UPDATE와 ledger INSERT의 단일 트랜잭션, selection/strategy lock 상호작용, 실제 PostgreSQL 회귀 시나리오를 확인했다. 독립 재실행은 PostgreSQL `4 passed`, focused `37 passed, 4 skipped`, compile·diff 검사 통과였다.
+- 2026-08-14 18:47 KST — 비차단 테스트 위생 권고: PostgreSQL 통합 테스트 cleanup을 향후 fixture/finally로 강화하면 테스트 중단 시 잔여 fixture를 더 확실히 방지할 수 있다. 현재 성공 경로 cleanup은 전후 잔여 레코드 수가 동일해 정상이다.
+
+> 모든 체크는 로컬 작업 트리의 구현·테스트·독립 QC 완료를 뜻한다. 커밋·push·PR·main 원격 반영·게시·배포·릴리스는 수행하지 않았으며 별도 지시와 게이트가 필요하다.