trex/portfolio-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
9038f41010af45dad655dfe15648d9a1e995d89a
portfolio-hub/docs/releases/rel-001_20260521_v1-api-full-surface.md
T
genichinandClaude Opus 4.7 9038f41010 feat: REQ-002/REQ-010 implementation — assets.tag_ids column + GET /v1/assets admin catalog (BAT-012) 
- REQ-002 scope redefinition: portfolios.tag_ids → assets.tag_ids UUID[] column with GIN index
- REQ-010 augmentation: GET /v1/assets redesigned as admin catalog endpoint (admin-only, no token_type branching)
- Asset tagging infrastructure: tag_ids column, archived flag synthesis for inactive tags, list_assets N+1 optimization
- DB migration 20260521_0023: assets.tag_ids UUID[] NOT NULL DEFAULT '{}', idx_assets_tag_ids_gin
- Test suite: 17 new test cases for assets.tag_ids + GET /v1/assets AC-9~12 (362 tests total)
- Documentation: runtime flows, release baseline, batch verification all updated
- BAT-012 added to REL-001 Included Batch and marked release-candidate

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-21 23:37:08 +09:00

9.7 KiB
Raw Blame History

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, BAT-012

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 제거
    • BAT-012 (REQ-002 재정의, REQ-010 augmentation): assets.tag_ids UUID[] 컬럼 + idx_assets_tag_ids_gin + GET /v1/assets admin catalog 재정의(token_type 분기 제거) + AssetCatalogResponse tag_ids/archived 합성. 기존 smoke의 GET /v1/assets 403 불일치를 해소.
  • 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/012 관련 revision 순차 적용
    • assets 테이블, portfolios.asset_id FK, tags 마스터, portfolios.tag_ids 컬럼, assets.tag_ids 컬럼 + idx_assets_tag_ids_gin (20260521_0023), 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 컬럼(portfolios/assets 양쪽)·ledger_trades·daemons 테이블은 마이그레이션 downgrade 시 데이터 소실 가능성 존재 — 사전 DB 스냅샷 필수. assets.tag_ids(20260521_0023) downgrade는 컬럼·인덱스 drop으로 안전.

Verification Checklist

  • 배포 전:
    • trex-basic 신 path 빌드 완료 확인
    • DB 스냅샷(백업) 생성 완료
    • alembic upgrade head dry-run 또는 revision 목록 점검
    • 전체 테스트 suite pass 확인 (BAT-001~011: 340 passed @ main 4bf6b55; BAT-012 추가 후: 362 passed @ 2026-05-21 BAT-012 confirm-batch-verification)
  • 배포 직후 (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)에 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 발생. BAT-012에서 해소 (2026-05-21): REQ-010 augmentation(CHG-20260521-02 AC-9~12) 구현으로 GET /v1/assets가 admin catalog 응답을 반환하도록 재정의됨. 자동 회귀 통과: tests/test_asset_catalog.py::test_get_v1_assets_admin_returns_catalog_response + status/market 필터 + non-admin(user/service) 403. 실 배포 환경 smoke는 REL 배포 시 재확인.
    • 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)에서 session token 정상 허용.
    • 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) + BAT-012 commit (assets.tag_ids + GET /v1/assets admin catalog 재정의, 본 release 진입 시 commit hash 기록)
  • 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, BAT-012 augmentation으로 admin catalog 응답 재정의. 자동 회귀 통과 — tests/test_asset_catalog.py 50 passed)
      • 실제 배포 환경(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 재정의 미정합: Resolved by BAT-012 (2026-05-21). REQ-010 CHG-20260521-02 augmentation(AC-9~12)을 BAT-012에서 구현 — GET /v1/assets가 require_admin 의존성으로 단일화되고 admin catalog 응답을 반환. session token이 admin permission을 가진 경우 정상 통과. 자동 회귀 9건 추가(test_get_v1_assets_*).
    • /health 응답 모델에 db_enabled 필드 부재: 운영 관점에서 health probe 결과로 DB 연결 상태를 외부 관찰자에게 노출하지 않는 상태. 체크리스트의 의도와 응답 모델 간 gap. HealthResponse(app/api/health.py:17-21) 보강 또는 별도 readiness endpoint 분리 후보.
    • POST/DELETE /v1/assets/{asset_id}/tags 잘못된 테이블 대상화: BAT-012 implementation 단계에서 발견. 라우트는 admin asset tagging을 의도하지만 내부적으로 append_portfolio_tag_id/remove_portfolio_tag_id(portfolios 테이블)를 호출. assets.tag_ids 컬럼은 본 release로 도입되었으나 apply/remove 경로가 정합되지 않아 실제로 채워지지 않음. REQ-005 follow-up REQ 또는 신규 REQ 후보.
  • REQ Input:
    • (운영 관찰 후 기록)
  • Change Request Input:
    • (운영 관찰 후 기록)
Reference in New Issue View Git Blame Copy Permalink