# 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 |