genichin
829629fa8f
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
82 lines
4.4 KiB
Markdown
82 lines
4.4 KiB
Markdown
# 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 |
|