# BAT-008 Implementation

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

## Plan Summary

REQ-011 AC-1~3에 대응하는 3개 baseline 문서 갱신. 코드/스키마/런타임 변경 없음.

## Changed Files

| 파일 | 변경 유형 | 대응 AC |
|------|----------|---------|
| `docs/interface-contract.md` | 기존 섹션 내 endpoint 상세 명세 추가 | REQ-011 AC-1 |
| `docs/data-model.md` | portfolios.market 컬럼 추가; AuthToken, BrokerCredential, LedgerTrade entity 추가 | REQ-011 AC-2 |
| `docs/runtime-flows.md` | Source Discovery/Batch 헤더 + Change Log 갱신 (내용은 bat-001에서 이미 충족) | REQ-011 AC-3 |

## Execution Log

### docs/interface-contract.md

- Source Discovery/Batch 헤더: `bootstrap-baseline, bat-006` → `bootstrap-baseline, bat-001, bat-006, bat-008`
- GET /health 응답 스키마 갱신: `{"status": "ok"}` 단순 설명 → `{status, service, version, checked_at}` 명시 (HealthResponse 기준)
- `v1 Consumer API (trex-basic)` 섹션 확장:
  - `### Authentication` 추가: service-token bearer, DB-issued 조건, trade-write 권한 명시
  - `### Endpoint: GET /v1/assets` 추가: query param, AssetsResponse/AssetItem 스키마, HTTP 200/401/403
  - `### Endpoint: GET /v1/user_info` 추가: UserInfoResponse/BrokerItem 스키마, HTTP 200/401/403/404
  - `### Endpoint: POST /v1/assets/{asset_id}/ledger/trades` 추가: LedgerTradeRequest/LedgerTradeResponse 스키마, HTTP 201/200/409/404/401/403
  - `### Idempotency Contract` 추가: deduplication key, duplicate/conflict 처리 방식
- Change Log 항목 추가

### docs/data-model.md

- Source Discovery/Batch 헤더: `bootstrap-baseline, bat-006` → `bootstrap-baseline, bat-001, bat-006, bat-008`
- Model Summary: AuthToken, BrokerCredential, LedgerTrade 추가
- Entity: Portfolio — `market :: text|null` 필드 추가 (migration 20260502_0014 기준)
- Entity: `AuthToken` 신규 추가:
  - Key Fields: id, user_id, token_type, token_source, permission, service_name, runtime_id, expires_at, created_at
  - Uniqueness Constraints: idx_auth_tokens_service_name_unique, idx_auth_tokens_runtime_id_unique
  - State Rules: runtime_id 없는 토큰 v1 거부 명시
- Entity: `BrokerCredential` 신규 추가:
  - Key Fields: user_id, broker, account_ref, encrypted_payload, credential_version, last_rotated_at
  - PK: (user_id, broker)
  - State Rules: 평문 저장 금지, 복호화 실패 처리 명시
- Entity: `LedgerTrade` 신규 추가:
  - Key Fields: ledger_entry_id, asset_id, order_id, execution_id, side, quantity, price, fee_amount, tax_amount, executed_at, recorded_at
  - Unique Constraint: uq_ledger_trades_idempotency
  - Index: idx_ledger_trades_asset_executed
  - State Rules: immutable rows, payload conflict → 409
- Change Log 항목 추가

### docs/runtime-flows.md

- Source Discovery/Batch 헤더: `bat-007` 뒤에 `bat-008` 추가
- Change Log 항목 추가: "REQ-011 AC-3 confirmed: v1 API flows and runtime_id issuance flow already present from bat-001"
- 내용 변경 없음 — bat-001에서 추가된 v1 API 처리 흐름 5개, Application Startup Validation, bat-007에서 추가된 Local DB 흐름 2개 모두 현행 유지

## Validation

- `docs/interface-contract.md`: REQ-011 AC-1 대상 4개 엔드포인트 명세 + 인증 방식 포함 확인 ✓
- `docs/data-model.md`: broker_credentials, ledger_trades, portfolios.market, auth_tokens.runtime_id 모두 반영 확인 ✓
- `docs/runtime-flows.md`: v1 API 처리 흐름(4개) + runtime_id 발급 흐름(POST /auth/service-tokens) 존재 확인 ✓
- 코드 변경 없음 — lint/typecheck 불필요

## Remaining Risks

- `docs/runtime-flows.md` v1 API flows는 bat-001에서 최초 작성됨. 이후 구현 변경 시 해당 흐름도 갱신 필요 (현재 기준 코드와 일치 확인됨).