Files

T

genichin 829629fa8f feat: implement portfolio UUID migration and v1 API finalization (BAT-006, BAT-001 re-verified)

Core Changes:
- Migrate portfolio_id from string to UUID in schema and repository layer
- Update portfolio CLI commands to use name+user combination for identification
- Update HTTP API to accept portfolio_id as UUID path parameter
- Implement portfolio ownership validation in repository queries

Requirements Completed (REQ-016 to REQ-019):
- REQ-016: portfolios table UUID schema migration with data migration script
- REQ-017: CLI portfolio commands with name+user identification
- REQ-018: HTTP API portfolio path parameters and v1 asset_id UUID returns
- REQ-019: Portfolio UUID baseline documentation updates

BAT-001 Re-verification:
- REQ-004~010 marked as Implemented after verification evidence validation
- All v1 API endpoints verified with comprehensive test coverage

Documentation Updates:
- Update data-model.md with portfolio UUID structure
- Update interface-contract.md with UUID path parameters
- Update runtime-flows.md with ownership-based resolution flows
- Update project-structure.md with database layer changes
- Add migration script for portfolio UUID transition

Testing:
- Add test_portfolio_uuid.py for migration validation
- Update test_cli.py and test_portfolio_ownership.py for ownership checks

2026-05-11 09:27:57 +00:00

4.4 KiB

Raw Blame History

BAT-008 Design

Status: confirmed
Batch: BAT-008
Profile: batch-lite

Architecture Summary

BAT-008은 신규 코드/스키마/런타임 변경이 없는 doc-only batch다. REQ-004~010 구현(BAT-001)과 BAT-006(UUID migration) 완료 후 미반영 상태인 baseline 문서 3개를 실제 구현 결과와 동기화한다.

Architecture Impact: none (코드, DB 스키마, API 인터페이스 변경 없음)
설계 결정 사항 없음 — 실제 구현 코드와 migration revision을 기준으로 문서 작성

Changed Areas

docs/interface-contract.md (AC-1)

현재 상태:

v1 Consumer API (trex-basic) 섹션에 Key Endpoints 3개와 Deployment Constraint(bat-006)만 있음
GET /health extended schema 미반영 (REQ-004)
각 엔드포인트 요청/응답 스키마, HTTP 코드, 에러 계약 미반영

추가 필요:

GET /health 응답 스키마: {status, service, version, checked_at} (HealthResponse from app/api/health.py)
GET /v1/assets 상세 명세: query param, 응답 스키마(AssetsResponse/AssetItem), HTTP 200
GET /v1/user_info 상세 명세: 응답 스키마(UserInfoResponse/BrokerItem), HTTP 200/404
POST /v1/assets/{asset_id}/ledger/trades 상세 명세: 요청 스키마(LedgerTradeRequest), 응답 스키마(LedgerTradeResponse), HTTP 201/200/409/404
service-token bearer 인증 방식 명시 (v1 전용)

docs/data-model.md (AC-2)

현재 상태:

Entity: Portfolio — market 컬럼 누락
Entity: User — auth_tokens 관련 AuthToken entity 없음
broker_credentials 테이블 미문서화
ledger_trades 테이블 미문서화

추가 필요:

Portfolio Key Fields에 market :: text|null 추가
Entity: AuthToken 추가 — id, user_id, token_type, runtime_id, permission, expires_at 등 핵심 필드
Entity: BrokerCredential 추가 — 스키마 기준: (user_id, broker) PK, account_ref, encrypted_payload, credential_version, last_rotated_at
Entity: LedgerTrade 추가 — 스키마 기준: ledger_entry_id BigInt Identity PK, asset_id, order_id, execution_id, side, quantity, price, fee_amount, tax_amount, executed_at, recorded_at; uq_ledger_trades_idempotency unique constraint

docs/runtime-flows.md (AC-3)

현재 상태 (bat-001에서 이미 갱신):

Flow: v1 API — Service-Token Authentication ✓
Flow: v1 API — GET /v1/assets ✓
Flow: v1 API — GET /v1/user_info ✓
Flow: v1 API — POST /v1/assets/{asset_id}/ledger/trades ✓
Flow: v1 API — POST /auth/service-tokens (runtime_id 발급 흐름 포함) ✓
Flow: Application Startup Validation ✓

추가 필요: Source Discovery/Batch 헤더에 bat-008 추가 + Change Log 항목 추가 (AC-3 충족 확인 기록)

Key Decisions

결정	내용	근거
runtime-flows.md 내용 보완 불필요	bat-001에서 v1 API 처리 흐름과 runtime_id 발급 흐름이 이미 추가됨	현행 파일 확인
interface-contract.md 갱신 방식	`v1 Consumer API (trex-basic)` 섹션 내에 endpoint별 상세 명세 subsection 추가	기존 섹션 구조 유지
data-model.md 갱신 방식	기존 Portfolio entity에 컬럼 추가; 신규 entity(BrokerCredential, LedgerTrade) 추가; AuthToken entity 신규 추가	migration 20260502_0014 기준
broker_credentials encrypted_payload	문서에 "Fernet-encrypted ciphertext (TEXT)" 으로 명시 — 복호화는 REQ-010 참조	민감정보 취급 기준

Edge Cases

docs/runtime-flows.md의 bat-001 추가 내용과 bat-007 추가 내용이 공존 — 섹션 충돌 없음. bat-008은 Change Log와 Source Discovery만 갱신.
auth_tokens 테이블은 bootstrap baseline에 Users entity와 함께 암묵적으로 존재하나 명시적 entity 섹션이 없음 — bat-008에서 AuthToken entity 추가.
ledger_trades.asset_id는 BAT-006 이후 UUID portfolio_id를 참조하나 TEXT 타입 — 문서에 "TEXT (UUID-format after BAT-006)" 으로 명시.

Architecture Impact

none

Reference Doc Update Plan

문서	변경 유형	적용 REQ AC
docs/interface-contract.md	기존 섹션 내 endpoint 상세 명세 추가	REQ-011 AC-1
docs/data-model.md	Portfolio entity 컬럼 추가, 신규 entity 3개 추가	REQ-011 AC-2
docs/runtime-flows.md	Source Discovery/Batch 헤더 + Change Log만 갱신 (내용은 bat-001 기준 이미 충족)	REQ-011 AC-3

4.4 KiB Raw Blame History