# BAT-018 Planning

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

## Included REQ
- REQ-005 (Installation, change-req): setup() UTC→TZ trading_date + `DailyPreallocationScheduler` 신규 + daemon 스레드 배선.
- REQ-048 (Configuration, change-req): TOML `trading_timezone`/`daily_preallocation_time` 키 + from_config 전파.
- REQ-009 (Documentation, change-req): runtime-flows/data-model 정합.

## Delivery Plan
1. REQ-005: `application/preallocation_scheduler.py`(SnapshotScheduler 패턴, TZ date + 일자당 1회 멱등 fire + boot run_once).
2. REQ-048: `config.py` DaemonInstanceConfig TOML 키 2종 + DaemonConfig 필드 + from_config 전파(+ from_env KST/00:00 기본).
3. REQ-005 배선: `daemon.py` setup() → `preallocation_scheduler.run_once()`, `_preallocation_loop` 스레드 + workers 등록, ZoneInfo(tz).
4. REQ-009: runtime-flows(데몬 lifecycle + 일일 preallocation Flow)/data-model(trading_date TZ vs UTC) + instance.example.toml.
5. 신규 테스트(test_preallocation_scheduler, test_instance_config 확장) + 전체 회귀 + ruff + 인프라 게이트.

## Dependencies
- Internal:
  - dcy-002/BAT-002 daemon 부트스트랩(REQ-005) — preallocation 지점.
  - dcy-005/BAT-008 SnapshotScheduler(REQ-030) — 스케줄러 패턴 준용.
  - dcy-009/BAT-013 DaemonInstanceConfig TOML(REQ-048) — 설정 키 추가.
  - REQ-002 preallocate_daily_slots — date 멱등(재사용, 본문 변경 없음).
- External:
  - stdlib `zoneinfo`(py3.12) — IANA 타임존.

## Design Gate
- Design Required Before Implementation: yes
- Reason: (a) trading_date TZ 분리는 daemon 부트스트랩·스케줄러·설정·도메인 호출부 경계에 걸쳐, "TZ 는 호출부에서, 도메인 시그니처는 date 유지"(A-3) 경계를 설계에서 못박지 않으면 도메인 침범/회귀 위험. (b) 일자 경계 fire/멱등/트리거 시각 게이팅 규칙(SnapshotScheduler 준용)을 설계에서 고정해야 중복 생성·누락(NFR-2/3)을 막는다. (c) 설정 표면(TOML 일원화 + from_env 기본)·timestamp UTC 유지(NFR-1) 경계 명시. → design.md 동일 턴 scaffold.

## Milestones
1. M1 — REQ-005 DailyPreallocationScheduler, test_preallocation_scheduler green
2. M2 — REQ-048 TOML 키 + from_config 전파, test_instance_config 확장 green
3. M3 — REQ-005 daemon 배선(setup + 스레드)
4. M4 — REQ-009 문서 정합 + instance.example.toml
5. M5 — 전체 회귀 + ruff + 인프라 게이트

## Risks
- R-1 (Low, OQ-1): 트리거 시점 운영 기대 불일치. 대응: 기본 00:00 + TOML 설정, SnapshotScheduler 패턴 재사용.
- R-2 (Medium): TZ 전환 경계에서 기존 UTC 날짜 슬롯과 새 TZ trading_date 불일치. 대응: 멱등 생성으로 중복 방지 + 경계 케이스 테스트(KST/UTC 경계).
- R-3 (Low, OQ-2 수용): 비거래일 idle 슬롯 누적. 대응: 매 캘린더일 생성 수용, idle 은 buy admit 시에만 활성화로 무해. 거래일 캘린더 후속.

## Notes
- 1차 게이트: 전체 회귀 green(부트스트랩 변경 무회귀).
- 경계 검증은 고정 clock 주입 단위로 결정론 확보(스레드 불필요).
- 멱등 preallocation 은 PG 게이트 전이/마이그레이션 테스트 회귀로도 간접 검증.