# BAT-039 Planning

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

## Included REQ
- REQ-011 (CHG-20260612-01): paper order seq Redis 영속화 + in-memory 폴백. AC-4 신규. AC-1~3 불변.

## Delivery Plan
1. `seq_store.py` 신규 — `SeqStore` Protocol(`next_seq() -> int`), `RedisSeqStore`(Redis `INCR`, 영속·원자), `InMemorySeqStore`(thread-safe 카운터, 폴백/테스트용). token_cache 패턴(`from_url(socket_connect_timeout=2)`) 정합.
2. `paper.py` — `__init__(..., seq_store: Optional[SeqStore] = None)`. `submit_order`: `seq_store` 주입 시 `seq_store.next_seq()`, 미주입 시 기존 `self._seq += 1`(byte-for-byte 유지).
3. `config.py` — `PaperBrokerConfig.redis_url: str = ""`, `from_config` 에 `TREX_PAPER_REDIS_URL` 읽기.
4. `daemon.py` — `_build_broker` paper 경로: `config.paper.redis_url` 있으면 `RedisSeqStore` 생성·주입.
5. 테스트 — 동일 seq store 공유 두 PaperBroker(재시작 모사) order_id 단조 증가, 매수→재시작→매도 correlation_id 비충돌, 미주입 시 `PAPER-000001` 폴백, AC-1~3 회귀.

## Dependencies
- Internal:
  - `trex_core/adapters/broker/token_cache.py` — Redis best-effort 패턴 참조
  - `trex_core/application/broker_port.py` — `OrderRequest`/`OrderAck` 불변
  - execution_id 합성(`paper:{order_id}:{filled_qty}`) — order_id 단조성에 의존
- External:
  - Redis(운영). 테스트는 fake/in-memory redis_module 또는 InMemorySeqStore 로 충분.

## Design Gate
- Design Required Before Implementation: yes
- Reason: 신규 `SeqStore` 포트(인터페이스 추가) + Redis 키 네임스페이스/스코프(instance_key) + INCR 원자성·런타임 오류 처리 + 폴백 의미를 design 에서 확정해야 함.

## Milestones
1. Design confirmed — SeqStore 계약, Redis 키, 폴백 의미 확정
2. Implementation — seq_store + paper + config + daemon + 테스트
3. Verification — AC-4 + AC-1~3 회귀 + 전체 회귀 + ruff

## Risks
- R-1 (Medium): Redis 런타임 오류 시 in-memory 로 silent 폴백하면 버그 재현 위험 — 완화: 미주입(설정 부재)만 폴백, 런타임 오류는 전파(test 하네스이므로 허용). design Key Decision 에서 명시.
- R-2 (Low): order_id 가 6자리 초과(INCR 누적) 시 `PAPER-{seq:06d}` 포맷 — `:06d` 는 최소 패딩이라 초과 자리수도 정상 표기, 충돌 없음.
- R-3 (Low): 다중 인스턴스가 같은 Redis 키 공유 시 seq 교차 — 단조·고유성 유지되므로 correctness 무해. instance_key 스코프로 분리 가능(design).