trex-core/docs/batches/bat-016_20260608_sell-pricing-limit-price-rename/design.md

BAT-016 Design

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

설계 목표

• 매도 주문이 매수 지정가(entry_price)로 나가는 버그(issue #10)를 도메인 모델 차원에서 구조적으로 제거한다.
• released 집행 경로 변경·컬럼 rename 마이그레이션을 회귀 없이 cutover 한다.

1. 슬롯 가격 필드 의미 통일 (REQ-002)

rename

• Slot.entry_price → Slot.limit_price (side 무관 "현재 pending 주문 지정가"). EXPECTED_SLOT_FIELDS 동시 반영(컬럼 계약 가드가 곧 검출).
• transit_slot/_apply_transition_fields 의 entry_price 파라미터 → limit_price.

limit_price 생애주기 (FR-1, 핵심)

• 결정: limit_price 는 pending 상태에서만 유효. _apply_transition_fields 의 generic 경로에서:
  • to_state ∈ {PENDING_BUY, PENDING_SELL} → limit_price = 입력값 if not None else slot.limit_price(set on entry).
  • to_state ∈ {HOLDING, CLOSED} → limit_price = None(clear on exit).
  • to_state == IDLE(롤백/복구) → 기존 reset 분기에서 이미 None clear.
• 효과: PENDING_BUY→HOLDING 에서 매수 지정가가 clear 되므로, 이후 HOLDING→PENDING_SELL 에서 매도 가격 미전달이면 slot.limit_price 는 None → 시장가. 매수 지정가가 매도로 누수될 경로가 구조적으로 없음.
• 전이 매트릭스:
  • IDLE→PENDING_BUY: set(매수 지정가) / PENDING_BUY→HOLDING: clear / HOLDING→PENDING_SELL: set(매도 지정가 또는 None) / PENDING_SELL→CLOSED: clear / *→IDLE: clear.

SlotService.sell (REQ-036)

• sell(slot_id, actor, reason, *, limit_price=None). default None → 자율 매도(safety-sell/kill-switch)는 가격 없이 호출 → 시장가. transit_slot 에 limit_price 전달.

2. dispatch 가격 결정 (REQ-013)

• _dispatch: side 분기 제거. limit = int(slot.limit_price) if slot.limit_price else None; order_type = "00" if limit is not None else "01". 매수가 재사용 경로 삭제.

3. sell intent 계약 (REQ-007)

• SellIntent.limit_price: Optional[float] = None. _admit_sell → transit_slot(..., limit_price=intent.limit_price).
• _admit_buy: 기존 entry_price=intent.entry_price(BuyIntent 외부 필드 유지) → 슬롯 limit_price=intent.entry_price 로 매핑(매수 동작 동일).
• 단일 메커니즘(가격 유무 분기, OQ-2): reason 별 코드 차등 없음.

4. 메시지 경계 (REQ-007, NFR-3)

• sell 핸들러: limit_price=_opt_float(body.get("limit_price")) 추가.
• buy 핸들러: 외부 payload 필드명 entry_price 유지(BuyIntent.entry_price).
• slot read(_slot_to_dict): 외부 read 키 "entry_price" 유지하되 내부 s.limit_price 로 매핑(계약 호환 — 외부 필드명 rename 은 본 주기 밖).

5. persistence + 마이그레이션 (REQ-006)

• 006_rename_entry_price_to_limit_price.sql: ALTER TABLE daily_slot RENAME COLUMN entry_price TO limit_price 를 idempotent DO-block(컬럼 존재 && 신컬럼 부재 시에만)으로. 글롭 재적용 모델에서 안전. 순수 rename → 기존 행 데이터 보존(S-3).
• postgresql.py: _SLOT_COLUMNS/update_slot/_row_to_slot 의 entry_price → limit_price.

6. 컬럼 계약 가드 (REQ-003)

• test_contract.py(도메인 필드셋)·test_migration_and_drift.py(DB 컬럼 = EXPECTED_SLOT_FIELDS)는 상수 참조라 rename 자동 반영; PG 게이트에서 실 컬럼명 limit_price 검증.

7. baseline 문서 (REQ-015)

• runtime-flows: dispatch 가격 결정 = slot.limit_price 단일 필드 + limit_price 생애주기.
• interface-contract: sell payload optional limit_price + ORD_DVSN 매핑.
• data-model: 슬롯 limit_price 컬럼 의미/생애주기.

하위호환 / 회귀 통제

• 외부 buy/sell payload·slot read 필드명 유지(NFR-3) → 전략 모듈 계약 무파괴.
• sell limit_price optional default None → 기존 재량 매도 호출 시장가로 안전 동작.
• 전체 회귀 green 이 rename 호출부 누락 부재의 1차 게이트.

테스트 설계

• 신규 tests/application/test_sell_pricing.py(recording paper broker 로 OrderRequest 직접 검증):
  • (a) 지정가 매수 슬롯 + 가격 미전달 매도 → sell order_type "01"/limit None(entry_price 미사용 — 핵심 버그 검출).
  • (b) 지정가 매수 슬롯 + 가격 전달 매도 → "00"/그 가격.
  • (c) SlotService.sell(가격 없음) → 시장가 + closed(S-2).
  • (d) 시장가 매수 슬롯 매도 → 시장가(회귀 안전).
• test_service.py: PENDING_BUY→HOLDING 시 limit_price clear 단언 추가.