# BAT-008 Planning

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

## Included REQ

- REQ-011: trex-basic 계약 반영을 위한 baseline 문서 갱신

## Out of Scope

- REQ-004~010 구현 자체 변경 (이미 Implemented 상태)
- 신규 API 엔드포인트 또는 스키마 추가
- runtime-flows.md 중 BAT-007에서 이미 갱신한 Alembic/ensure_schema() 경계 흐름 재작성
- docs/project-structure.md (BAT-007 범위)

## 구현 순서

### 1단계: 현황 파악

- `docs/interface-contract.md` 현재 상태 확인 — v1 API 엔드포인트 명세 누락 여부 점검
- `docs/data-model.md` 현재 상태 확인 — broker_credentials, ledger_trades, portfolios.market, auth_tokens.runtime_id 누락 여부 점검
- `docs/runtime-flows.md` 현재 상태 확인 — v1 API 처리 흐름 및 runtime_id 발급 흐름 누락 여부 점검

### 2단계: docs/interface-contract.md 갱신 (REQ-011 AC-1)

- GET /health 응답 스키마 (extended) 추가
- GET /v1/assets 엔드포인트 명세 추가
- GET /v1/user_info 엔드포인트 명세 추가
- POST /v1/assets/{asset_id}/ledger/trades 엔드포인트 명세 추가
- service-token bearer 인증 방식 섹션 추가 또는 갱신

### 3단계: docs/data-model.md 갱신 (REQ-011 AC-2)

- broker_credentials 테이블 스키마 추가 (user_id, broker, account_ref, encrypted_payload, credential_version, last_rotated_at)
- ledger_trades 테이블 스키마 추가 (ledger_entry_id, asset_id, order_id, execution_id, side, quantity, price, fee_amount, tax_amount, executed_at, recorded_at; unique constraint 포함)
- portfolios.market 컬럼 추가
- auth_tokens.runtime_id 컬럼 추가

### 4단계: docs/runtime-flows.md 갱신 (REQ-011 AC-3)

- v1 API 요청 처리 흐름(인증 → 서비스 → DB) 추가 (GET /v1/assets, GET /v1/user_info, POST /v1/assets/{asset_id}/ledger/trades)
- service-token 발급 시 runtime_id 동시 생성 흐름 추가 (REQ-005 반영)
- BAT-007에서 추가된 기존 섹션과 충돌 없이 통합

## Dependencies

- Internal:
  - REQ-004~010: 모두 Implemented 상태 확인됨 (BAT-001 release-candidate) — 선행 조건 충족
  - `app/api/v1_assets.py`, `app/api/v1_user_info.py`, `app/api/v1_ledger.py` — 실제 구현 기준으로 명세 작성
  - `app/domain/models.py` — broker_credentials, ledger_trades 모델 기준으로 data-model 작성
  - `migrations/versions/` — Alembic revision 기준으로 컬럼/테이블 정의 확인
- External: 없음

## Design Gate

- Design Required Before Implementation: no
- Reason: 신규 코드/인터페이스/DB 스키마/런타임 흐름 변경 없음. 구현 완료된 REQ-004~010 결과를 기존 3개 문서에 반영하는 doc-only 작업. 구조적 결정 사항 없음.

## Milestones

1. docs/interface-contract.md 갱신 완료 (v1 API 엔드포인트 4개 + 인증 방식)
2. docs/data-model.md 갱신 완료 (테이블 2개 + 컬럼 2개)
3. docs/runtime-flows.md 갱신 완료 (v1 API 처리 흐름 + runtime_id 발급 흐름)

## Risks

- `docs/runtime-flows.md`에 BAT-007에서 추가된 섹션과 중복 또는 충돌이 생길 수 있음 — 1단계 현황 파악에서 확인 후 통합 방식 결정
- 실제 구현 코드와 문서 내용 불일치 시 코드 기준으로 작성