# BAT-016 Planning

- Status: confirmed
- Batch: BAT-016
- Profile: standard

## Included REQ
- REQ-036 (Migration): portfolio_ledger 회계 원장 통합 마이그레이션
- REQ-037 (Interface): 신 path 회계 책임 단일화 + 응답에 portfolio 상태 포함
- REQ-038 (Interface): 레거시 buy/sell endpoint deprecated 표기

## Delivery Plan
- 순서: **REQ-036 → REQ-037 → REQ-038** (마이그레이션 선행 필수)
  - REQ-036: portfolio_ledger 신 스키마 마이그레이션 + ensure_schema 갱신 + ledger_trades DROP. 이 스키마가 REQ-037/038의 기반.
  - REQ-037: insert_ledger_trade 재정의(portfolio_ledger insert + portfolios UPDATE 단일 트랜잭션 + FOR UPDATE + ON CONFLICT partial), 도메인 모델 통합(LedgerEntry 단일화), 응답 확장, 회계 헬퍼(음수 허용).
  - REQ-038: 레거시 buy/sell `deprecated=True` + 헤더, 신 스키마에서 레거시 append 동작 보존 확인.
- 선행 조건:
  - dcy-006 confirmed (2026-06-05) ✓
  - REQ-036/037/038 Approved (2026-06-05) ✓
- batch 통합 회귀: 3건 구현 후 전체 pytest + 로컬 smoke (신 path 201 + cash/quantity_after, duplicate 200, 음수 허용, 레거시 buy deprecated 헤더)

## Dependencies
- Internal:
  - REQ-036 → REQ-037/038 선행 (portfolio_ledger 신 스키마)
  - REQ-029/REQ-033: 기존 ledger path/컬럼명 정합 — 본 batch가 그 위에 회계 책임 + 테이블 통합을 쌓음
  - dcy-006: OQ-1~7 결정 본문 반영 완료
  - BAT-015(release-candidate): 분리된 별도 batch — 본 batch와 독립
- External:
  - trex-core daemon (slot-core, 별도 repo) — 본 응답 schema로 스냅샷 갱신 구현. issue #8 comment(2026-06-05)로 응답 명세 사전 공유 완료.

## Design Gate
- Design Required Before Implementation: yes
- Reason: DB schema 마이그레이션(REQ-036, 컬럼 추가 + partial UNIQUE + 타입 변경 + 테이블 DROP) + 도메인 모델 통합(REQ-037, LedgerEntry/LedgerTrade 통합) + 회계 트랜잭션 설계(단일 트랜잭션 + FOR UPDATE + 음수 헬퍼 분리)가 architecture/data 영향을 가진다. design 단계에서 마이그레이션 전략, 도메인 모델 통합 형태, 회계 헬퍼 추출 방식, baseline 갱신 계획을 명문화한 뒤 implementation 진입.

## Milestones
1. Design: 마이그레이션 전략(action 분포/backfill/partial UNIQUE) + 도메인 모델 통합 형태 + 회계 헬퍼 분리 + runtime-flows/data-model 갱신 계획 확정
2. Implementation: REQ-036(마이그레이션 + ensure_schema) → REQ-037(repository/도메인/응답/회계) → REQ-038(deprecated)
3. Verification: 전체 pytest 회귀 + 마이그레이션 schema 검증(AC-1~7) + 로컬 smoke(신 path 회계/응답/duplicate/음수 + 레거시 deprecated) + 동시성 회귀
4. confirm-batch-verification → confirm-req-implemented 3건 일괄

## Risks
- R-1 (Medium): 도메인 모델 통합(LedgerEntry/LedgerTrade)이 광범위한 import/usage를 건드려 회귀 실패 다발. (BAT-015 REQ-033에서 LedgerTrade 필드 rename 시 test_v1/test_daemon_assignment 잔존 참조로 5건 실패한 선례)
  - 대응: grep 기반 전수 참조 확인 후 일괄 갱신. 구현 후 전체 회귀 incremental.
- R-2 (Medium): 단일 트랜잭션(portfolio_ledger insert + portfolios UPDATE + FOR UPDATE) 도입이 기존 테스트 mock 구조와 충돌.
  - 대응: repository 통합 함수 단위로 mock 갱신. 동시성은 별도 회귀.
- R-3 (Low): partial UNIQUE + ON CONFLICT inference SQL이 기존 idempotency 테스트와 다른 동작.
  - 대응: REQ-037 AC-2(duplicate) + AC-3(음수) 회귀로 검증.
- R-4 (Low): 본 워크스페이스 ledger_trades 미생성/portfolio_ledger 데이터 단순 — 마이그레이션 backfill 검증이 prod와 다를 수 있음.
  - 대응: AC-6(backfill) 회귀는 개발 DB 기준. prod 정밀도/action 분포는 release staging 이연(dcy-006 R-5/R-6).