feat: REQ-001~018 Implemented 전환, REQ-010 GET /v1/assets admin catalog 재정의, REL-001 draft

- confirm-req-implemented: REQ-001~018 (17건, REQ-013 제외) Approved → Implemented - BAT-001(REQ-009/011/014), BAT-002(REQ-010/012/015), BAT-003(REQ-001/002/003/006) - BAT-004(REQ-004/005), BAT-005(REQ-007/008), BAT-006(REQ-016/017/018) - CHG-20260521-01 entry 각 REQ에 추가; SRS index Recent Change Log 갱신 - REQ-010 CHG-20260521-02: GET /v1/assets admin catalog 전용 재정의 - 기존 token_type 분기 portfolio 조회 코드 제거, admin permission + list_assets() 호출로 대체 - AssetCatalogListResponse 스키마 추가 (items/total) - REQ-010 Status: Implemented → Approved (재검증 필요) - 테스트 343건 전체 통과: service/user token 403, admin token 200 + catalog schema 검증 - migration 보강: portfolios_asset_migration market 컬럼 부재 fallback, portfolio_tags 빈 테이블 early-return, service_token index fix autocommit_block 정리 - docs/releases/rel-001: REL-001 draft 추가 (BAT-001~011 포함) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-05-21 10:17:39 +00:00
parent 4bf6b554a7
commit 6add0ade29
28 changed files with 894 additions and 393 deletions
@@ -0,0 +1,119 @@
+# REL-001: v1 API full surface
+
+- Status: draft
+- Profile: app-service
+- Included Batch: BAT-001, BAT-002, BAT-003, BAT-004, BAT-005, BAT-006, BAT-007, BAT-008, BAT-009, BAT-010, BAT-011
+
+## Scope
+- Included:
+  - BAT-001 (REQ-009, REQ-011, REQ-014): assets 테이블 스키마 + portfolios.asset_id FK + data migration
+  - BAT-002 (REQ-010, REQ-012, REQ-013, REQ-015): admin asset catalog CRUD API + portfolio 생성 CLI catalog 검증 + baseline 갱신
+  - BAT-003 (REQ-001, REQ-002, REQ-003, REQ-006): tags 마스터 테이블 + assets/portfolios.tag_ids 컬럼 + data migration
+  - BAT-004 (REQ-004, REQ-005): 태그 HTTP API (POST/GET /v1/tags, PATCH /v1/tags/{id}/deactivate, POST/DELETE /v1/assets|portfolios/{id}/tags)
+  - BAT-005 (REQ-007, REQ-008): pfhub tag CLI + baseline 문서 갱신
+  - BAT-006 (REQ-016, REQ-017, REQ-018): client token 발급 폐지 + service-token rotate unique index 보강 + POST /auth/service-tokens daemon_id forward
+  - BAT-007 (REQ-022, REQ-023): daemon deactivation auto-revoke + NULL daemon migration CLI
+  - BAT-008 (REQ-019, REQ-020, REQ-021, REQ-024): 토큰 surface baseline 문서 갱신 (AuthContext, 권한 매트릭스, TTL 정책, env admin token SOP)
+  - BAT-009 (REQ-025, REQ-026, REQ-027, REQ-028): POST/PATCH/DELETE/GET /v1/portfolios CRUD 신설
+  - BAT-010 (REQ-030, REQ-031, REQ-032): GET/POST/DELETE /v1/portfolios/{id}/tags + POST/GET/PATCH/DELETE /v1/portfolios/{id}/comments + baseline 갱신
+  - BAT-011 (REQ-029): POST /v1/portfolios/{id}/ledger/trades 신설 + 구 path POST /v1/assets/{id}/ledger/trades 제거
+- Excluded:
+  - REQ-013 (Deprecated): GET /v1/assets 토큰 타입별 분기 재정의 — dcy-003 옵션 B 결정으로 무효화
+  - trex-basic 내부 코드 변경 (별도 레포 — 본 릴리즈와 동시 배포 필요)
+
+## Rollout Plan
+1. **사전 확인**: trex-basic 신 path(`POST /v1/portfolios/{id}/ledger/trades`) 빌드 완료 및 배포 준비 확인
+2. **DB 마이그레이션**: `alembic upgrade head` — BAT-001/003/006/007 관련 revision 순차 적용
+   - assets 테이블, portfolios.asset_id FK, tags 마스터, tag_ids 컬럼, auth_tokens.runtime_id/daemon_id, daemons 테이블, ledger_trades
+3. **portfolio-hub 서비스 배포**: 신규 이미지 rolling restart
+   - 신 API surface: `/v1/portfolios/*`, `/v1/tags`, `/v1/assets` (catalog), `/v1/portfolios/{id}/ledger/trades`
+   - 구 path `/v1/assets/{id}/ledger/trades` → HTTP 404 (BAT-011)
+4. **trex-basic 배포**: 신 path로 전환된 클라이언트 배포
+   - **이 단계가 완료되기 전까지 구 path 호출 불가 — portfolio-hub 배포 후 즉시 trex-basic 배포 수행**
+5. **배포 후 smoke 검증**: health endpoint + 신 path 동작 확인
+
+## Rollback Plan
+- **트리거 조건**: portfolio-hub 배포 후 health 실패, 신 API 500/401 대규모 발생, trex-basic 배포 실패
+- **BAT-011 포함 전체 롤백**:
+  1. portfolio-hub → 이전 이미지로 즉시 롤백 (`alembic downgrade` 또는 이전 이미지 재기동)
+  2. trex-basic → 구 path 사용 버전으로 동반 롤백 (portfolio-hub 롤백 완료 후)
+  - **BAT-011 단독 부분 롤백 불가** — 신/구 path 동시 서빙은 설계상 없음
+- **DB 마이그레이션 롤백**: 데이터 손실 리스크를 평가한 뒤 DBA 판단 하에 수행. tag_ids 컬럼·ledger_trades·daemons 테이블은 마이그레이션 downgrade 시 데이터 소실 가능성 존재 — 사전 DB 스냅샷 필수
+
+## Verification Checklist
+- **배포 전**:
+  - [x] trex-basic 신 path 빌드 완료 확인
+  - [x] DB 스냅샷(백업) 생성 완료
+  - [x] `alembic upgrade head` dry-run 또는 revision 목록 점검
+  - [x] 전체 테스트 suite pass 확인 (340 passed, main branch 4bf6b55)
+- **배포 직후 (portfolio-hub)**:
+  - [~] `GET /health` → HTTP 200 + `db_enabled: true` (DB 연결 정상) — **로컬 smoke (2026-05-21 17:08 KST)**: HTTP 200 응답, 단 `HealthResponse` 모델([app/api/health.py:17-21](app/api/health.py#L17-L21))에 `db_enabled` 필드 미노출. DB 연동은 `PORTFOLIOHUB_DB_ENABLED=true` + `alembic upgrade head` head revision 적용 + 본 smoke의 다른 항목들이 DB 의존 동작으로 통과한 것으로 우회 확인.
+  - [!] `GET /v1/assets` (admin token) → HTTP 200 (asset catalog 조회) — **로컬 smoke (2026-05-21 17:08 KST)**: admin session token으로 호출 시 HTTP 403 `{"detail":"Unsupported token type"}`. 현재 [app/api/v1_assets.py:135-164](app/api/v1_assets.py#L135-L164) token_type 분기는 `user/admin/service` 케이스만 처리하고 `session`은 누락. dcy-003 옵션 B 결정으로 REQ-013(Deprecated) 후 GET /v1/assets를 admin catalog 조회 전용으로 재정의하는 작업(REQ-010 Notes 후속)이 아직 반영되지 않음. **이 체크리스트 항목은 현재 코드 상태와 불일치 — 본 릴리즈 범위 결정 필요(아래 Feedback Handoff 참조).**
+  - [x] `POST /v1/portfolios` (user session token) → HTTP 201 (portfolio 생성) — **로컬 smoke (2026-05-21 17:13 KST)**: admin session token + active asset(`bab52e11-...`)으로 호출, HTTP 201 + `portfolio_id=c629c31e-b77d-44fb-a515-0edfe4f00cee` 생성 확인. `_require_write_token` 게이트([app/api/v1_portfolios.py:45-50](app/api/v1_portfolios.py#L45-L50))에서 session token 정상 허용.
+  - [x] `POST /v1/assets/{id}/ledger/trades` → HTTP 404 (구 path 제거 확인) — **로컬 smoke (2026-05-21 17:13 KST)**: HTTP 404 `{"detail":"Not Found"}` 확인. BAT-011 신/구 path 동시 서빙 없음 정책 충족.
+- **trex-basic 배포 직후**:
+  - [ ] `POST /v1/portfolios/{id}/ledger/trades` (service token) → HTTP 201 + `status="new"` (신 path 동작 확인)
+  - [ ] daemon assignment 인가 3단계 정상 동작 확인
+
+## Release Execution Evidence
+- Release Status Transition Target: released
+
+### Deployment Facts
+- Executed At:
+  - (배포 시작 시각 — 배포 시 기록)
+- Completed At:
+  - (배포 완료 시각 — 배포 시 기록)
+- Environment:
+  - (배포 대상 환경 — 배포 시 기록)
+- Operator:
+  - (배포 수행자 — 배포 시 기록)
+- Revision or Artifact:
+  - main branch commit: `4bf6b55` (feat: v1 portfolio mutation, sub-resources, ledger path migration BAT-008~011)
+- Commands or Procedure:
+  - `alembic upgrade head` → portfolio-hub rolling restart → trex-basic 배포
+
+### Profile-Specific Checks
+- app-service:
+  - Health Endpoint:
+    - 로컬 smoke (2026-05-21 17:08 KST, 127.0.0.1:18000): `{"status":"ok","service":"portfolio-hub","version":"0.1.0","checked_at":"2026-05-21T17:08:45.608024+09:00"}` HTTP 200. `db_enabled` 필드는 응답 모델에 미정의 — 별도 후속 항목으로 등록.
+  - Startup Log Fields:
+    - (실제 배포 후 기록 — app, event, command, run_id 확인)
+  - Request Log Fields:
+    - (실제 배포 후 기록 — request_id 포함 여부)
+  - Smoke or Manual Verification:
+    - 로컬 smoke 결과(Verification Checklist 배포 직후 4개 항목 참조):
+      - 통과 2건: POST /v1/portfolios (201), POST /v1/assets/{id}/ledger/trades (404)
+      - 부분 통과 1건: GET /health (200, 단 `db_enabled` 필드 미노출)
+      - 불일치 1건: GET /v1/assets (admin session token → 403 "Unsupported token type"). 본 릴리즈 진행 전 결정 필요.
+    - 실제 배포 환경(prod/staging) smoke는 본 릴리즈 시 별도 수집.
+
+### Rollback Outcome
+- Rollback Required:
+  - (배포 후 기록)
+- Rollback Trigger:
+  - none
+- Rollback Action:
+  - none
+
+### Release Decision Evidence
+- Released Decision:
+  - (배포 후 기록)
+- Rationale:
+  - (배포 후 기록)
+- Recorded By:
+  - (배포 후 기록)
+- Recorded At:
+  - (배포 후 기록)
+
+## Feedback Handoff
+- Observation Summary:
+  - (운영 관찰 후 기록)
+- Discovery Input:
+  - ledger_trades.asset_id 컬럼명이 portfolio_id를 가리키는 혼용 상태 잔존 (REQ-029 Notes) — 컬럼명 정합화 후속 REQ 후보
+  - session token의 no_expiry 코드 enforcement 미구현 (REQ-021 follow-up) — 후속 REQ 후보
+  - **GET /v1/assets token_type 게이트와 admin catalog 재정의 미정합**: dcy-003 옵션 B로 REQ-013이 Deprecated되었으나 [app/api/v1_assets.py:135-164](app/api/v1_assets.py#L135-L164)의 token_type 분기(user/admin/service)는 그대로 잔존하고, REQ-010 Notes에 명시된 GET /v1/assets의 "admin catalog 조회 전용" 재정의가 아직 별도 REQ로 분리되지 않음. session token이 v1 portfolio path와 달리 v1 assets path에서 거부되는 inconsistency 발생. **후속 Discovery 또는 dcy-001 batch design 단계의 REQ-010 augmentation 후보**.
+  - **/health 응답 모델에 `db_enabled` 필드 부재**: 운영 관점에서 health probe 결과로 DB 연결 상태를 외부 관찰자에게 노출하지 않는 상태. 체크리스트의 의도와 응답 모델 간 gap. `HealthResponse`([app/api/health.py:17-21](app/api/health.py#L17-L21)) 보강 또는 별도 readiness endpoint 분리 후보.
+- REQ Input:
+  - (운영 관찰 후 기록)
+- Change Request Input:
+  - (운영 관찰 후 기록)