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

BAT-016 Planning

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

Included REQ

• REQ-002 (Interface, change-req): Slot entry_price→limit_price rename + clear-on-exit(→HOLDING/→CLOSED) 생애주기.
• REQ-006 (Data, change-req): daily_slot 컬럼 rename 마이그레이션 006(idempotent) + persistence 매핑.
• REQ-013 (Integration, change-req): _dispatch 가 slot.limit_price 단일 필드로 가격/주문유형 결정(매수가 재사용 제거).
• REQ-007 (Interface, change-req): SellIntent/sell payload optional limit_price + _admit_sell 운반; buy entry_price→limit_price 매핑.
• REQ-036 (Interface, change-req): SlotService.sell optional limit_price(default None → 자율 매도 시장가).
• REQ-003 (Testing, change-req): 컬럼 계약/드리프트 가드 limit_price 반영.
• REQ-015 (Documentation, change-req): runtime-flows/interface-contract/data-model 정합.

Delivery Plan

1. REQ-002: models.py Slot 필드 + EXPECTED_SLOT_FIELDS rename; service.py transit_slot/_apply_transition_fields 파라미터 rename + clear-on-exit(→HOLDING/→CLOSED), SlotService.sell optional limit_price.
2. REQ-013: execution.py::_dispatch 가 slot.limit_price 단일 필드 사용.
3. REQ-007: intents.py SellIntent.limit_price + _admit_sell 운반 + _admit_buy limit_price 매핑; messaging_handlers.py sell payload limit_price, slot read 외부 entry_price→limit_price 매핑.
4. REQ-006: 006_*.sql rename 마이그레이션(idempotent) + postgresql.py 매핑.
5. REQ-003: 컬럼 계약/드리프트 가드 확인(상수 참조 자동 + DB 게이트).
6. REQ-015: baseline 3문서 정합.
7. 신규 테스트(test_sell_pricing) + 전체 회귀 + ruff + 인프라 게이트(PG 마이그레이션/컬럼 계약).

Dependencies

• Internal:
  • dcy-003/BAT-004 broker execution(_dispatch) — 버그 지점.
  • dcy-001/BAT-001 slot 도메인(REQ-002/003) — rename 대상.
  • dcy-002/BAT-002 persistence(REQ-006) — 컬럼/마이그레이션.
  • dcy-007/BAT-010 safety-sell(REQ-036 SlotService.sell) — 자율 매도 시장가 경로.
  • dcy-011/BAT-015 — slot.symbol 서버 resolve(가정 A-1) 충족.
• External:
  • PostgreSQL(rename 마이그레이션). KIS ORD_DVSN 00/01 매핑(OrderRequest 경유).

Design Gate

• Design Required Before Implementation: yes
• Reason: (a) entry_price→limit_price rename 은 도메인 모델·서비스 전이·persistence·마이그레이션·컬럼 계약 가드까지 교차 절단(cross-cutting) — 전이별 set/clear 매트릭스를 설계에서 못박지 않으면 매수 지정가 누수/복원 회귀(R-4) 위험. (b) 매도 가격 하이브리드(가격 유무 분기)의 단일 메커니즘 경계(자율=None=시장가, 재량=optional 지정가)를 설계에서 고정해야 reason 별 분기 혼입을 막는다(OQ-2). (c) released 집행 경로(R-1)·컬럼 rename 마이그레이션 idempotency 를 설계에서 명시. → design.md 동일 턴 scaffold.

Milestones

1. M1 — REQ-002 도메인 rename + clear-on-exit, 단위 green
2. M2 — REQ-013 _dispatch limit_price 단일 필드 + REQ-007/036 sell 가격 경로, test_sell_pricing green
3. M3 — REQ-006 마이그레이션 006 + persistence 매핑, PG 게이트 컬럼 계약 green
4. M4 — REQ-003 가드 + REQ-015 문서 정합
5. M5 — 전체 회귀 + ruff + 인프라 게이트

Risks

• R-1 (High): released 집행 경로 매도 동작 변경. 대응: paper recording broker 로 손절/지정가/현재가>매수가 시나리오 검증 + change-req 이력. 실거래 배포는 release 단계 검증.
• R-2 (Medium): 재량 지정가 미체결 시 pending_sell 잔류. 대응: 본 주기는 가격 결정 분기에 한정, 미체결 처리는 issue #9/기존 롤백 범위.
• R-3 (Low, OQ-2): reason 별 차등 없이 가격 유무로 분기 → 자율 매도는 default None 으로 항상 시장가(체결성 보장).
• R-4 (Medium): rename/clear-on-exit 가 도메인/persistence/마이그레이션 교차. 대응: 전이별 set/clear 단위 + 컬럼 계약 가드 + idempotent 마이그레이션 + 외부 필드명 유지(경계 매핑).

Notes

• 1차 게이트: 전체 회귀 green(rename 호출부 누락 부재 확인).
• 버그 검증은 반드시 지정가 매수 슬롯(entry_price 채워짐) 매도 케이스 포함(S-1 측정 조건).
• 마이그레이션은 PG 게이트(실 PostgreSQL) 컬럼 계약/드리프트 테스트로 검증.