trex/portfolio-hub
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
2470c0a00ce2cc800c98a4436d8c1287bfdf2791
portfolio-hub/docs/releases/rel-001_20260521_v1-api-full-surface.md
T
genichinandClaude Opus 4.7 84de34c301 feat: REQ-028 add display_name to GET /v1/portfolios response 
- Portfolio domain model + PortfolioItem schema에 display_name 필드 추가
- _SELECT_PORTFOLIO에 a.display_name JOIN 보강, _portfolio_to_item 매퍼 전달
- REQ-028 CHG-20260601-01/02: Implemented → Approved → Implemented
  - AC-13 신설 (display_name == joined assets.display_name)
- BAT-009 verification.md: AC-13 매핑 + augmentation history 누적
- REL-001 verification checklist 재실행 evidence 갱신 (368 PASSED, 로컬 smoke 5건 통과)
- tests/test_v1.py: dead 중복 GET /v1/assets 섹션 제거 (두 번째 동명 정의가 첫 번째를 override하던 잔재)

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-01 14:00:59 +00:00

132 lines
13 KiB
Markdown
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, BAT-013, REQ-028 CHG-20260601-01 (BAT-009 augmentation, no separate batch)
## 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 불일치를 해소.
- BAT-013 (REQ-005 CHG-20260521-02): `POST/DELETE /v1/assets/{asset_id}/tags` 라우트 SQL 대상 정합화 — `append_asset_tag_id`/`remove_asset_tag_id` 메서드 신규 + 라우트 호출 교체. BAT-012로 도입된 `assets.tag_ids` 컬럼이 비로소 정상 채워지도록 apply/remove 경로 정합화. HTTP contract·DB 스키마 무변.
- REQ-028 CHG-20260601-01 (BAT-009 augmentation): GET /v1/portfolios 응답 schema에 `display_name` 필드 추가. `Portfolio` dataclass + `PortfolioItem` schema + `_SELECT_PORTFOLIO` JOIN `a.display_name` 보강. AC-13 신설, 368 passed 회귀, 로컬 smoke로 응답 노출 확인. 별도 BAT 미할당(BAT-009 verification 재실행 누적).
- 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)
- `POST/DELETE /v1/assets/{id}/tags` 내부 SQL이 `assets` 테이블 대상으로 정합화됨 (BAT-013) — HTTP contract 무변, DB 스키마 무변
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
- **배포 전**:
- [x] trex-basic 신 path 빌드 완료 확인
- [x] DB 스냅샷(백업) 생성 완료
- [x] `alembic upgrade head` dry-run 또는 revision 목록 점검
- [x] 전체 테스트 suite pass 확인 (BAT-001~011: 340 passed @ main 4bf6b55; BAT-012 추가 후: 362 passed @ 2026-05-21 BAT-012 confirm-batch-verification; BAT-013 추가 후: **369 passed @ 2026-05-21 BAT-013 confirm-batch-verification** — +7 신규 회귀: assets 테이블 mutation 정합성 검증)
- **배포 직후 (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 의존 동작으로 통과한 것으로 우회 확인.
- [x] `GET /v1/assets` (admin token) → HTTP 200 (asset catalog 조회) — **재실행 로컬 smoke (2026-06-01 13:16 KST)**: admin DB session token으로 호출, HTTP 200 + `{"items":[{"asset_id":"bab52e11-...","symbol":"005930","display_name":"삼성전자","status":"active","tag_ids":[],...}],"total":1}` catalog 응답 확인. REQ-010 CHG-20260521-02 augmentation + BAT-012/013 verification 정합. portfolio 관련 필드 미포함, AC-9 충족. (이전 2026-05-21 smoke에서 HTTP 403 발생했던 불일치는 해소.)
- [x] `POST /v1/portfolios` (user session token) → HTTP 201 (portfolio 생성) — **재실행 로컬 smoke (2026-06-01 13:18 KST)**: admin DB session token + active asset(`bab52e11-...`)으로 호출, HTTP 201 + `portfolio_id=1cec5061-8c26-4116-be3a-1ff2357d02f4` 생성. **응답 본문에 `display_name:"삼성전자"` 포함** — REQ-028 CHG-20260601-01(AC-13) augmentation 반영 확인. `_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-06-01 13:18 KST)**: HTTP 404 `{"detail":"Not Found"}` 확인. BAT-011 신/구 path 동시 서빙 없음 정책 충족.
- [x] **(추가)** `GET /v1/portfolios` (session token) → HTTP 200 + 응답 portfolio item에 `display_name` 필드 포함 — **재실행 로컬 smoke (2026-06-01 13:18 KST)**: admin DB session token으로 호출, portfolios 2건 모두 `display_name:"삼성전자"` (joined `assets.display_name`)로 응답. REQ-028 CHG-20260601-01 AC-13 충족.
- [ ] `POST /v1/assets/{asset_id}/tags` (admin token) → HTTP 200 + 응답 후 `GET /v1/assets`에서 해당 asset의 `tag_ids`에 적용된 tag_id 포함 확인 (BAT-013 정합화 검증) — 실 배포 환경에서 수집. unit-level은 cursor-mock SQL 검증으로 1차 안전망 확보.
- [ ] `DELETE /v1/assets/{asset_id}/tags/{tag_id}` (admin token) → HTTP 200 + 응답 후 `GET /v1/assets`에서 해당 asset의 `tag_ids`에서 tag_id 제거 확인 (BAT-013 정합화 검증) — 실 배포 환경에서 수집.
- **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: `9038f41` (feat: REQ-002/REQ-010 implementation — assets.tag_ids column + GET /v1/assets admin catalog)
- + BAT-013 commit: (assets 테이블 tag apply/remove SQL 정합화 — 본 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 (2026-06-01 13:16~18 KST)** — Verification Checklist 배포 직후 5개 항목 참조:
- 통과 5건: GET /health (200), GET /v1/assets (200 + catalog 응답, REQ-010 augmentation 검증), POST /v1/portfolios (201 + display_name 포함, REQ-028 AC-13 검증), GET /v1/portfolios (200 + 모든 item에 display_name 포함), POST /v1/assets/{id}/ledger/trades (404)
- 부분 통과 1건: GET /health 응답 본문에 `db_enabled` 필드 미노출(응답 모델 확장은 후속) — 실 DB 의존 항목들이 모두 통과한 것으로 우회 검증
- pytest 전체 회귀: **368 passed** (5월 21일 base 340 → +28: REQ-010 BAT-012/013 회귀 + 신규 docs_root_path + display_name AC-13 등 누적).
- BAT-013 신규 회귀(자동 7건): assets 테이블 mutation 정합화 (`append_asset_tag_id`/`remove_asset_tag_id` 메서드 존재·SQL 대상 검증·에러 분기·멱등 가드). 실 PostgreSQL `assets.tag_ids` mutation 확인은 배포 직후 smoke 2건(POST/DELETE /v1/assets/{id}/tags)으로 수집 예정.
- 실제 배포 환경(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](app/api/health.py#L17-L21)) 보강 또는 별도 readiness endpoint 분리 후보.
- ~~**`POST/DELETE /v1/assets/{asset_id}/tags` 잘못된 테이블 대상화**~~: **Resolved by BAT-013** (2026-05-21). REQ-005 CHG-20260521-02 (AC-1/AC-5 명문화) + CHG-20260521-03 (Implemented 전환). `PostgresPortfolioRepository.append_asset_tag_id`/`remove_asset_tag_id` 메서드 신규 + 라우트([app/api/v1_assets.py:175,200](../../app/api/v1_assets.py#L175))의 호출 교체. 자동 회귀 7건 추가(`test_postgres_repository_has_*`, `test_*_targets_assets_table_not_portfolios`, `test_*_raises_when_asset_not_found`, `test_append_asset_tag_id_idempotent_guard_present`). 실 PostgreSQL `assets.tag_ids` mutation 검증은 본 release 배포 직후 smoke 항목으로 추가됨.
- **`pfhub tag apply asset` / `pfhub tag remove asset` CLI 동일 mismatch 잔존**: BAT-013 implementation/verification 단계에서 추가 발견. CLI 측도 `repo.append_portfolio_tag_id`/`repo.remove_portfolio_tag_id`를 호출하여 portfolios 테이블을 대상화 ([docs/runtime-flows.md:67-77](../runtime-flows.md#L67-L77)). REQ-005 본 batch scope는 HTTP API에 한정. **REQ-007/008 augmentation 또는 신규 REQ 후보**.
- REQ Input:
- (운영 관찰 후 기록)
- Change Request Input:
- (운영 관찰 후 기록)
Reference in New Issue View Git Blame Copy Permalink